Practical notes: Inside ARD: Как на самом деле работает спецификация Agentic Resource Discovery
Пошаговое руководство по Practical notes: Inside ARD: Как на самом деле работает спецификация Agentic Resource Discovery — контракты, проверки и слоты для кода для команд, использующих эту модель.
В следующих заметках описывается практический подход к изучению документа «Inside ARD: How the Agentic Resource Discovery Spec Actually Works». Основное внимание уделяется контрактам, проверкам и местам для вставки кода, а не мотивирующей подаче материала. На этапе обзора сначала запишите контракт: необходимые входные данные, сигнал о успешном выполнении и действия при частичной неудаче. Такой чек-лист поможет сохранять честность при последующих изменениях кода. Документируйте как успешный сценарий работы, так и сценарий восстановления. Повторные попытки, проверки человеком и обработка неработоспособных сообщений являются частью продукта, а не элементами последующей доработки.
Проблема, которую решает ARD
Проблема ARD наилучшим образом решается, когда с ней работают как с измеримой структурой. Сначала зафиксируйте один успешный пример, один случай сбоя и запись о возврате к предыдущему состоянию, прежде чем расширять объем работ. Лучше использовать небольшие, тестируемые единицы вместо обширных скриптов. При сбое какого-либо шага причина должна быть связана с конкретной ответственностью, а не с запутанной цепочкой операций. Сохраняйте простую и типизированную структуру графа; вложенные элементы мешают понять, какой узел заполнил тот или иной поле, и приводят к нарушению продолжения работы после перерывов.
Ментальная модель: описание, просмотр, поиск, вызов
Ментальная модель этого этапа лучше всего работает, если рассматривать её как измеримую поверхность. Зафиксируйте один идеальный пример выполнения, один случай сбоя и запись о возврате к предыдущему состоянию перед расширением объёма работ. Рассматривайте этот этап как контракт между входными данными и проверенными результатами. Дайте названия создаваемым элементам, определите критерии успеха и не соглашайтесь на молчаливое частичное выполнение задачи. Установите лимит токенов на каждый ход и на каждую сессию. Инструменты агентов активно расширяют контекст; строгие ограничения предотвращают появление неожиданных счетов.
Описание ресурса: манифест ai-catalog.json
Этап описания ресурса работает наилучшим образом, когда его рассматривают как измеримую поверхность. Соберите один идеальный пример работы, один случай сбоя и записку о возврате к предыдущему состоянию перед расширением объёма работ. Записывайте временные показатели, а также стоимость токенов или запросов рядом с функциональными результатами. Отображение стоимости на раннем этапе предотвращает неожиданные счёты при переходе от демо-среды к общедоступным средам. Сохраняйте структуру графа простой и типизированной. Вложенные структуры скрывают информацию о том, какой узел заполнил тот или иной поле, и могут нарушить возобновление работы после прерываний. Этап описания ресурса работает наилучшим образом, когда его рассматривают как измеримую поверхность. Соберите один идеальный пример работы, один случай сбоя и записку о возврате к предыдущему состоянию перед расширением объёма работ. Документируйте одновременно успешный путь выполнения и путь восстановления. Повторные попытки, проверки человеком и обработка неработающих сообщений являются частью продукта, а не элементами последующей доработки.
https://yourdomain.com/.well-known/ai-catalog.json
{
"specVersion": "1.0",
"host": {
"displayName": "Northwind Labs",
"identifier": "northwindlabs.dev"
},
"entries": [
{
"identifier": "urn:ai:northwindlabs.dev:tools:pdf-table-extractor",
"displayName": "PDF Table Extractor",
"type": "application/mcp-server+json",
"url": "https://tools.northwindlabs.dev/pdf-extractor/mcp.json",
"description": "Extracts structured tables from scanned or digital
PDFs into CSV or JSON.",
"representativeQueries": [
"pull the line-item table out of this invoice PDF",
"convert the tables in this scanned report into a spreadsheet"
]
}
]
}
Идентификатор: почему он выглядит как URN
Для определения идентичности на этапе создания идентификатора необходимо заранее определить входные данные, ответственного за шаг и критерии завершения перед изменением кода. Операторы должны иметь возможность перезапустить шаг с известной точки контроля, не догадываясь о скрытом состоянии. Лучше использовать небольшие, тестируемые единицы вместо обширных скриптов. При сбое шага он должен указывать на конкретную причину, а не на сложную структуру обработки данных. Внедрять человеческое утверждение для операций, связанных с тратой денег или изменением производственных данных. Настройка на этапе компиляции не гарантирует полноты решения бизнес-задач.
API: поиск, исследование и простой список
На этапе исследования поиска через API необходимо определить входные данные, ответственного за выполнение шага и критерии завершения перед изменением кода. Операторы должны иметь возможность перезапустить шаг с известной точки контроля, не догадываясь о скрытом состоянии. Рассматривайте этот этап как контракт между входными данными и проверенными выходными результатами. Дайте названия элементам, определите критерии успеха и не допускайте молчаливого частичного завершения работы. Внедрите утверждение человека для операций, связанных с тратой денег или изменением производственных данных. Подключение на этапе компиляции не эквивалентно полноте выполнения бизнес-задач.
{
"query": {
"text": "I need to digitize an invoice's line items",
"filter": {
"type": ["application/mcp-server+json"]
}
},
"pageSize": 5
}
Федерация: реестры, обменивающиеся данными между собой
Для реестров Federation, взаимодействующих с этапом выполнения, необходимо определить входные данные, ответственного за шаг и критерии завершения перед изменением кода. Операторы должны иметь возможность перезапустить шаг с известной точки контроля, не догадываясь о скрытом состоянии. Записывайте время выполнения и стоимость токенов или запросов рядом с функциональными результатами. Отображение стоимости заранее предотвращает неожиданные счета при переходе от демо-среды к общедоступным средам. Вводите человеческое утверждение для операций, связанных с тратой денег или изменением производственных данных. Подключение на этапе компиляции не гарантирует полноты функционала продукта. Для реестров Federation, взаимодействующих с этапом выполнения, необходимо определить входные данные, ответственного за шаг и критерии завершения перед изменением кода. Операторы должны иметь возможность перезапустить шаг с известной точки контроля, не догадываясь о скрытом состоянии. Документируйте одновременно успешный путь выполнения и путь восстановления. Повторные попытки, человеческое утверждение и обработка некорректных сообщений являются частью продукта, а не отдельными элементами.
Доработка на уровне Polish.
Как это встраивается в чат-бота
На этапе определения того, куда именно будет встраиваться функция, сначала запишите условия работы: необходимые входные данные, сигнал успешного выполнения и действия при частичной неудаче. Такой чек-лист поможет сохранять честность при последующих изменениях кода. Лучше использовать небольшие, тестируемые модули вместо обширных скриптов. При сбое какого-либо шага причина неудачи должна указывать на конкретную ответственность, а не на запутанную цепочку операций. Устанавливайте контрольные точки после дорогостоящих шагов. Система возобновления работы не должна снова взимать плату за один и тот же вызов большой языковой модели, когда оператор пытается выполнить последующий элемент.
Реальная реализация: промышленная версия ARD на Snowflake
При работе над этапом «Создание в реальном времени» сначала запишите контракт: необходимые входные данные, сигнал о успехе и действия при частичной неудаче. Такой чек-лист поможет сохранять честность при последующих изменениях кода. Рассматривайте этот этап как контракт между входными данными и проверенными выходными результатами. Укажите названия элементов, определите критерии успеха и не допускайте безусловного частичного завершения работы. Выполняйте контрольные точки после дорогостоящих операций. Система возобновления работы не должна снова взимать плату за один и тот же вызов LLM, когда оператор пытается выполнить следующий этап.
┌─────────────────────────────────────────────────────────────┐
│ Streamlit UI Layer │
│ (Serves /.well-known/ai-catalog.json + search interface) │
├─────────────────────────────────────────────────────────────┤
│ API Procedures Layer │
│ ARD_SEARCH │ ARD_LIST_AGENTS │ ARD_EXPLORE │ ARD_GATE │
├─────────────────────────────────────────────────────────────┤
│ Semantic Ranking Layer │
│ Python UDF: TF-IDF + Cosine Similarity (scikit-learn) │
├─────────────────────────────────────────────────────────────┤
│ Registry Layer │
│ ARD_REGISTRY_ENTRIES table + ARD_AUDIT_LOG │
├─────────────────────────────────────────────────────────────┤
│ Ingestion Layer │
│ ARD_INGEST_MANIFEST (parse JSON → populate registry) │
├─────────────────────────────────────────────────────────────┤
│ Generation Layer │
│ ARD_MANIFEST_GENERATOR (DESCRIBE AGENT → ai-catalog.json) │
└─────────────────────────────────────────────────────────────┘
Уровень 1: Автогенерация манифеста из живых агентов
При работе над этапом автогенерации уровня 1 сначала запишите «контракт»: необходимые входные данные, сигнал о успехе и действия при частичной неудаче. Такой чек-лист помогает сохранять честность при последующих изменениях кода. Записывайте время выполнения и стоимость токенов или запросов рядом с функциональными результатами. Очевидность затрат заранее предотвращает неожиданные счета при переходе от демо-среды к общедоступным средам. Выполняйте контрольные точки после дорогостоящих шагов. Функция возобновления не должна снова взимать плату за один и тот же вызов LLM при повторной попытке обработки последующего узла. При работе над этапом автогенерации уровня 1 сначала запишите «контракт»: необходимые входные данные, сигнал о успехе и действия при частичной неудаче. Такой чек-лист помогает сохранять честность при последующих изменениях кода. Документируйте одновременно «идеальный путь» и путь восстановления. Повторные попытки, человеческое вмешательство и обработка некорректных сообщений являются частью продукта, а не элементами последующей доработки.
SHOW AGENTS IN SCHEMA ANALYTICS.AGENTS;
{
"specVersion": "1.0",
"host": {
"displayName": "Snowflake Analytics Platform",
"identifier": "analytics.snowflake-demo.com"
},
"entries": [
{
"identifier": "urn:ai:analytics.snowflake-demo.com:analytics:finance-agent",
"displayName": "Finance Agent",
"type": "application/vnd.snowflake.cortex-agent+json",
"url": "https://zkumjrw-uib48895.snowflakecomputing.com/api/v2/cortex/agents/...",
"description": "Finance AI analyst with expertise in ASC 606...",
"tags": ["finance", "revenue", "ASC-606", "ARR", "bookings"],
"capabilities": ["text-to-sql", "metric-disambiguation"],
"representativeQueries": [
"What was our recognized revenue last quarter?",
"Show me ARR trend over the past 12 months"
],
"trustManifest": {
"identity": {"type": "domain-verified", "domain": "analytics.snowflake-demo.com"},
"attestations": [
{"type": "RBAC-governed", "detail": "FINANCE_AGENT_ROLE required"}
]
}
}
]
}
Уровень 2: Вставка данных в поисковый реестр
Этап вставки данных на уровне 2 работает наилучшим образом, если рассматривать его как измеримую структуру. Сначала соберите один эталонный пример данных, один случай сбоя и запись о возврате к предыдущему состоянию, прежде чем расширять объем работы. Предпочитайте небольшие, тестируемые единицы кода вместо обширных скриптов. При сбое какого-либо шага причина сбоя должна указывать на конкретный элемент ответственности, а не на запутанную цепочку операций. Сохраняйте структуру графа простой и типизированной. Вложенные структуры данных маскируют информацию о том, какой узел заполнил тот или иной поле, и мешают возобновлению работы после прерываний.
ARD_REGISTRY_ENTRIES
├── IDENTIFIER (URN, unique)
├── DISPLAY_NAME
├── TYPE (IANA media type)
├── URL
├── DESCRIPTION
├── TAGS (ARRAY)
├── CAPABILITIES (ARRAY)
├── REPRESENTATIVE_QUERIES (ARRAY)
├── TRUST_MANIFEST (VARIANT)
├── SEARCH_TEXT (lower-cased concatenation of description + queries + tags)
├── STATUS ('ACTIVE' | 'STALE' | 'REMOVED')
└── Timestamps (INGESTED_AT, LAST_VERIFIED_AT, UPDATED_AT)
Уровень 3: Семантический поиск — подход с пользовательскими функциями на Python
Этап семантического поиска уровня 3 работает наилучшим образом, когда его рассматривают как измеримую поверхность. Соберите один идеальный пример работы, один случай сбоя и запись о возврате к предыдущему состоянию перед расширением объема работ. Рассматривайте этот этап как контракт между входными данными и проверенными выходными результатами. Дайте названия соответствующим элементам, определите критерии успешности и не соглашайтесь на молчаливое частичное выполнение задачи. Заблокируйте интерпретатор и файлы зависимостей перед запуском цикла. Различия в работе на ноутбуке и в среде CI являются наиболее распространенной причиной скрытых сбоев в демонстрациях API.
CREATE OR REPLACE FUNCTION ANALYTICS.AGENTS.ARD_SEMANTIC_RANK(
query_text VARCHAR,
candidates ARRAY
)
RETURNS ARRAY
LANGUAGE PYTHON
RUNTIME_VERSION = '3.11'
PACKAGES = ('scikit-learn', 'numpy')
HANDLER = 'rank_candidates'
AS
$
from sklearn.feature_extraction.text import TfidfVectorizer
from sklearn.metrics.pairwise import cosine_similarity
def rank_candidates(query_text, candidates):
if not candidates or not query_text:
return []
identifiers = [c['identifier'] for c in candidates]
texts = [c.get('search_text', '') for c in candidates]
all_texts = [query_text.lower()] + [t.lower() for t in texts]
vectorizer = TfidfVectorizer(
ngram_range=(1, 3),
max_features=5000,
stop_words='english',
sublinear_tf=True
)
try:
tfidf_matrix = vectorizer.fit_transform(all_texts)
except ValueError:
return [{'identifier': id, 'score': 0} for id in identifiers]
similarities = cosine_similarity(tfidf_matrix[0:1], tfidf_matrix[1:])[0]
results = [
{'identifier': id, 'score': round(float(sim) * 100, 1)}
for id, sim in zip(identifiers, similarities)
]
results.sort(key=lambda x: x['score'], reverse=True)
return results
$;
Уровень 4: Шлюз вызова — RBAC перед выполнением
Этап вызова на уровне 4 работает наилучшим образом, когда его рассматривают как измеримую поверхность. Соберите один идеальный пример работы, один случай сбоя и записку о возврате к предыдущему состоянию перед расширением объёма работ. Записывайте временные показатели, а также стоимость токенов или запросов рядом с функциональными результатами. Отображение стоимости на раннем этапе предотвращает неожиданные счёты при переходе от демо-среды к общедоступным средам. Сохраняйте структуру графа простой и типизированной. Вложенные структуры скрывают информацию о том, какой узел заполнил какое поле, и могут нарушить возобновление работы после прерываний. Этап вызова на уровне 4 работает наилучшим образом, когда его рассматривают как измеримую поверхность. Соберите один идеальный пример работы, один случай сбоя и записку о возврате к предыдущему состоянию перед расширением объёма работ. Документируйте одновременно успешный путь выполнения и путь восстановления. Повторные попытки, проверки человеком и обработка неработающих сообщений являются частью продукта, а не элементами последующей доработки.
CALL ARD_INVOCATION_GATE(
'urn:ai:analytics.snowflake-demo.com:analytics:finance-agent',
'ACCOUNTADMIN'
)
-- Returns: {"authorized": true, "agentFqn": "ANALYTICS.AGENTS.FINANCE_AGENT", ...}
CALL ARD_INVOCATION_GATE(
'urn:ai:analytics.snowflake-demo.com:analytics:finance-agent',
'PUBLIC'
)
-- Returns: {"authorized": false, "reason": "Role PUBLIC lacks FINANCE_AGENT_ROLE grant."}
Уровень 5: Сервер манифеста Streamlit
Для этапа Layer 5 в The Streamlit необходимо заранее определить входные данные, ответственного за выполнение шага и критерии завершения перед изменением кода. Операторы должны иметь возможность перезапустить шаг с известной точки контроля, не догадываясь о скрытом состоянии системы. Лучше использовать небольшие, тестируемые модули вместо обширных скриптов. При сбое шага причина должна быть связана с конкретной областью ответственности, а не с запутанной структурой всей системы. Внедрять человеческую проверку там, где происходит расход средств или изменяются данные в продакшене. Простое подключение компонентов на этапе компиляции не гарантирует полноты функционала системы.
manifest = get_manifest()
st.code(json.dumps(manifest, indent=2), language="json")
st.download_button("Download", json.dumps(manifest, indent=2), "ai-catalog.json")
query = st.text_input("Query", placeholder="I need to analyze quarterly revenue")
cap_filter = st.selectbox("Capability", [None, "text-to-sql", "multi-tool-routing"])
if st.button("Search"):
results = search_registry(query, filters)
for entry in results["results"]:
st.expander(f"{entry['displayName']} — Score: {entry['score']}")
stats = get_registry_stats()
# Shows: 4 entries, 18 tags across 4 agents, 3 capability types
Layer 6: Полный набор инструментов для тестирования
Для этапа конечной обработки на уровне слоя 6 необходимо заранее определить входные данные, ответственного за выполнение шага и критерии завершения перед изменением кода. Операторы должны иметь возможность перезапустить шаг, исходя из известной точки контроля, без необходимости угадывания скрытого состояния. Рассматривайте этот этап как контракт между входными данными и проверенными выходными результатами. Укажите названия результатов работы, определите критерии успеха и не допускайте молчаливого частичного завершения задачи. Проводите аутентификацию на шлюзе и повторно предоставляйте разрешения на уровне передачи данных. Одного лишь токена-носителя недостаточно для обозначения границы тенантности.
Test 1: MANIFEST_GENERATION
→ Calls ARD_MANIFEST_GENERATOR(), asserts specVersion = "1.0"
and entries array is non-empty
Test 2: MANIFEST_INGESTION
→ Calls ARD_INGEST_MANIFEST(manifest), asserts status = "SUCCESS"
and entries_ingested > 0
Test 3: SEARCH_FINANCE_QUERY
→ Searches "What was our revenue last quarter?"
→ Asserts top result identifier contains "finance"
Test 4: SEARCH_CHURN_QUERY
→ Searches "Which customers are likely to churn?"
→ Asserts top result identifier contains "cs"
Test 5: SEARCH_WITH_FILTER
→ Searches "pipeline forecast" with capabilities filter ["text-to-sql"]
→ Asserts results > 0 (filter applied correctly)
Test 6: LIST_AGENTS
→ Calls ARD_LIST_AGENTS(1, 10)
→ Asserts pagination.totalEntries > 0
Test 7: EXPLORE_FACETS
→ Calls ARD_EXPLORE()
→ Asserts facets.tags is not null and totalEntries > 0
Test 8: GATE_AUTHORIZED
→ Calls ARD_INVOCATION_GATE(finance URN, "ACCOUNTADMIN")
→ Asserts authorized = true
Test 9: GATE_UNAUTHORIZED
→ Calls ARD_INVOCATION_GATE(finance URN, "PUBLIC")
→ Asserts authorized = false
Test 10: HEALTH_CHECK
→ Calls ARD_HEALTH_CHECK()
→ Asserts status = "COMPLETE"
{
"summary": {
"total_tests": 10,
"passed": 10,
"failed": 0,
"success_rate": "100.0%"
},
"tests": [...],
"timestamp": "2026-06-18T..."
}
Усиление безопасности в производственной среде: что ломается и как мы это исправили
Для этапа укрепления производственной среды, предназначенного для выявления сбоев, необходимо заранее определить входные данные, ответственного за выполнение шага и критерии завершения перед изменением кода. Операторы должны иметь возможность перезапустить шаг с известной точки контроля, не догадываясь о скрытом состоянии. Записывайте время выполнения и стоимость токенов или запросов рядом с функциональными результатами. Отображение стоимости на раннем этапе предотвращает неожиданные счета при переходе с демо-среды в общедоступные среды. Внедряйте человеческое утверждение для операций, связанных с тратой денег или изменением производственных данных. Настройки во время компиляции не гарантируют полноты функционала бизнеса. Для этапа укрепления производственной среды, предназначенного для выявления сбоев, необходимо заранее определить входные данные, ответственного за выполнение шага и критерии завершения перед изменением кода. Операторы должны иметь возможность перезапустить шаг с известной точки контроля, не догадываясь о скрытом состоянии. Документируйте одновременно «идеальный путь» и пути восстановления. Повторные попытки, человеческое утверждение и обработка некорректных сообщений являются частью продукта, а не отдельными элементами.
Доработайте на английском.
Сервер манифеста Streamlit — обслуживание ARD через HTTP
При работе над этапом сервера манифеста Streamlit сначала запишите условия работы: необходимые входные данные, сигнал успешного выполнения и последствия частичной неудачи. Такой список поможет сохранять честность при последующих изменениях кода. Предпочитайте небольшие, тестируемые модули вместо обширных скриптов. Если какой-то шаг не сработает, причина неудачи должна указывать на конкретную ответственность, а не на запутанную цепочку операций. Вносите контрольные точки после дорогостоящих шагов. Функция возобновления работы не должна повторно запускать один и тот же вызов большой языковой модели, когда оператор пытается выполнить следующий узел.
Развертывание
При работе на этапе развертывания сначала запишите условия соглашения: необходимые входные данные, сигнал о успешном выполнении и действия при частичной неудаче. Такой список помогает сохранять честность при последующих изменениях кода. Рассматривайте этот этап как соглашение между входными данными и проверенными выходными результатами. Укажите названия файлов, определите критерии успешности и не допускайте безусловного частичного завершения работы. Выполняйте контрольные точки после дорогостоящих операций. Система возобновления работы не должна повторно взимать плату за один и тот же вызов большой языковой модели, когда оператор пытается выполнить следующий этап.
CREATE STAGE IF NOT EXISTS ANALYTICS.AGENTS.STREAMLIT_STAGE
ENCRYPTION = (TYPE = 'SNOWFLAKE_SSE');
-- Upload source (via COPY INTO from temp table)
COPY INTO @ANALYTICS.AGENTS.STREAMLIT_STAGE/ard_manifest_app/streamlit_app.py
FROM (SELECT content FROM _STREAMLIT_SRC)
FILE_FORMAT = (TYPE = CSV COMPRESSION = NONE ...)
SINGLE = TRUE OVERWRITE = TRUE;
CREATE OR REPLACE STREAMLIT ANALYTICS.AGENTS.ARD_MANIFEST_SERVER
ROOT_LOCATION = '@ANALYTICS.AGENTS.STREAMLIT_STAGE/ard_manifest_app'
MAIN_FILE = '/streamlit_app.py'
QUERY_WAREHOUSE = COMPUTE_WH;
Полный исходный код Streamlit
При работе над полным исходным кодом Streamlit сначала запишите условия работы: необходимые входные данные, сигнал о успешном выполнении и действия при частичной неудаче. Такой список поможет сохранять честность при последующих изменениях кода. Записывайте время выполнения и стоимость токенов или запросов рядом с результатами работы. Отображение стоимости заранее предотвращает неожиданные счета при переходе от демо-среды к общедоступным средам. Выполняйте контрольные точки после дорогостоящих шагов. Функция возобновления работы не должна снова взимать плату за один и тот же вызов большой языковой модели, когда оператор пытается выполнить следующий узел.
import streamlit as st
import json
from snowflake.snowpark.context import get_active_session
st.set_page_config(page_title="ARD Manifest Server", layout="wide")
session = get_active_session()
@st.cache_data(ttl=300)
def get_manifest():
result = session.sql("CALL ANALYTICS.AGENTS.ARD_MANIFEST_GENERATOR()").collect()
return json.loads(result[0][0])
@st.cache_data(ttl=300)
def search_registry(query, filters=None):
safe_query = query.replace("'", "''")
if filters:
filter_json = json.dumps(filters).replace("'", "''")
sql = f"CALL ANALYTICS.AGENTS.ARD_SEARCH('{safe_query}', PARSE_JSON('{filter_json}'))"
else:
sql = f"CALL ANALYTICS.AGENTS.ARD_SEARCH('{safe_query}')"
result = session.sql(sql).collect()
return json.loads(result[0][0])
@st.cache_data(ttl=300)
def get_registry_stats():
result = session.sql("CALL ANALYTICS.AGENTS.ARD_EXPLORE()").collect()
return json.loads(result[0][0])
tab1, tab2, tab3, tab4 = st.tabs([
"ai-catalog.json", "Search", "Explorer", "API Docs"
])
Вкладка 1: Чистый манифест
При работе с вкладкой 1 «Сырой этап» сначала запишите условия работы: необходимые входные данные, сигнал о успешном выполнении и действия при частичной неудаче. Такой список поможет сохранять честность при последующих изменениях кода. Храните конфигурацию вне кода приложения. Файлы с настройками окружения, хранилища секретов и флаги функций должны находиться в одном месте, чтобы операторы могли их проверять, не читая весь код. Создавайте контрольные точки после дорогостоящих операций. Функция возобновления работы не должна повторно взимать плату за один и тот же вызов большой языковой модели, когда оператор пытается выполнить следующий шаг.
with tab1:
st.markdown("## /.well-known/ai-catalog.json")
manifest = get_manifest()
c1, c2, c3 = st.columns(3)
c1.metric("Spec Version", manifest.get("specVersion", "?"))
c2.metric("Host", manifest.get("host", {}).get("identifier", "?"))
c3.metric("Entries", len(manifest.get("entries", [])))
st.code(json.dumps(manifest, indent=2), language="json")
st.download_button(
"Download ai-catalog.json",
json.dumps(manifest, indent=2),
"ai-catalog.json",
"application/json"
)
Вкладка 2: Интерактивный семантический поиск
При работе над интерактивной семантической стадией Tab 2 сначала запишите условия работы: необходимые входные данные, сигнал о успешном выполнении и действия при частичной неудаче. Такой чек-лист поможет сохранять честность при последующих изменениях кода. Документируйте одновременно успешный и восстановительный пути выполнения. Повторные попытки, проверки человеком и обработка неработоспособных сообщений являются частью продукта, а не элементами последующей доработки. Выполняйте контрольные точки после дорогостоящих шагов. Механизм возобновления работы не должен повторно взимать плату за один и тот же вызов LLM при повторной попытке оператора обработки последующего узла.
with tab2:
st.markdown("## POST /search")
query = st.text_input("Query", placeholder="e.g., I need to analyze quarterly revenue")
cap_filter = st.selectbox("Capability", [None, "text-to-sql", "multi-tool-routing"])
if st.button("Search", type="primary") and query:
filters = {"capabilities": [cap_filter]} if cap_filter else None
results = search_registry(query, filters)
st.markdown(f"### {results['resultCount']} results")
st.caption(f"Method: {results.get('method', 'keyword')}")
for i, entry in enumerate(results.get("results", [])):
with st.expander(f"#{i+1} {entry['displayName']} — Score: {entry['score']}"):
st.markdown(f"**ID:** `{entry['identifier']}`")
st.markdown(f"**URL:** `{entry.get('url', 'N/A')}`")
st.markdown(f"**Tags:** {', '.join(entry.get('tags', []))}")
st.markdown(f"**Capabilities:** {', '.join(entry.get('capabilities', []))}")
if entry.get("representativeQueries"):
for q in entry["representativeQueries"]:
st.markdown(f"- _{q}_")
Tab 3: Детальное исследование
Во время работы на этапе фасетного исследования Таба 3 сначала запишите условия работы: необходимые входные данные, сигнал успешного выполнения и действия при частичной неудаче. Такой чек-лист поможет сохранять честность при последующих изменениях кода. Предпочитайте небольшие, тестируемые модули вместо обширных скриптов. Если какой-то шаг не сработает, причина неудачи должна указывать на конкретную ответственность, а не на запутанную цепочку операций. Выполняйте контрольные точки после дорогостоящих шагов. Функция возобновления работы не должна повторно взимать плату за один и тот же вызов LLM при повторной попытке обработки последующего узла.
with tab3:
st.markdown("## POST /explore")
stats = get_registry_stats()
st.metric("Active Entries", stats.get("totalEntries", 0))
e1, e2, e3 = st.columns(3)
with e1:
st.markdown("### Types")
for f in stats.get("facets", {}).get("type", []):
st.markdown(f"- `{f['value']}` ({f['count']})")
with e2:
st.markdown("### Tags")
for f in stats.get("facets", {}).get("tags", []):
st.markdown(f"- `{f['value']}` ({f['count']})")
with e3:
st.markdown("### Capabilities")
for f in stats.get("facets", {}).get("capabilities", []):
st.markdown(f"- `{f['value']}` ({f['count']})")
Таб 4: Справочник API
При работе над этапом справочника API Tab 4 сначала запишите условия взаимодействия: необходимые параметры входных данных, сигнал о успешном выполнении и последствия частичной неудачи. Такой чек-лист поможет сохранять честность при последующих изменениях кода. Рассматривайте этот этап как договор между входными данными и проверенными выходными результатами. Дайте названия соответствующим элементам, определите критерии успешности и не допускайте безусловного частичного завершения работы. Выполняйте контрольные точки после дорогостоящих операций. Система возобновления работы не должна снова взимать плату за один и тот же вызов LLM, когда оператор пытается выполнить следующий этап.
with tab4:
st.markdown("""
| ARD Endpoint | Procedure | Description |
|---|---|---|
| `GET /.well-known/ai-catalog.json` | `ARD_MANIFEST_GENERATOR()` | Live manifest |
| `POST /search` | `ARD_SEARCH(query, filters)` | Semantic search |
| `POST /explore` | `ARD_EXPLORE()` | Faceted browse |
| `GET /agents` | `ARD_LIST_AGENTS(page, size)` | Paginated list |
| Gate | `ARD_INVOCATION_GATE(urn, role)` | RBAC check |
Scoring: TF-IDF + cosine similarity (scikit-learn), 0-100 scale.
Identity: urn:ai:<domain>:<namespace>:<agent-name>
""")
Доступ к приложению
При работе над этапом «Подключение к приложению» сначала запишите условия взаимодействия: необходимые параметры ввода, сигнал о успешном выполнении и действия при частичной неудаче. Такой список помогает сохранять честность при последующих изменениях кода. Запишите также время выполнения операций и стоимость токенов или запросов рядом с результатами работы. Отображение стоимости заранее предотвращает неожиданные счета при переходе от демо-среды к общедоступным средам. Выполняйте контрольные проверки после дорогостоящих шагов. Система возобновления работы не должна снова взимать плату за один и тот же вызов большой языковой модели при повторной попытке обработки последующего элемента. При работе над этапом «Подключение к приложению» сначала запишите условия взаимодействия: необходимые параметры ввода, сигнал о успешном выполнении и действия при частичной неудаче. Такой список помогает сохранять честность при последующих изменениях кода. Документируйте одновременно успешный сценарий работы и сценарий восстановления. Повторные попытки, проверки со стороны человека и обработка неработоспособных сообщений являются частью продукта, а не элементами последующей доработки.
Результаты прямых тестов
Этап тестирования в реальном времени работает наилучшим образом, если рассматривать его как измеримую основу. Соберите один идеальный пример работы, один случай сбоя и записку о возврате к предыдущему состоянию перед расширением объёма тестирования. Предпочитайте небольшие, тестируемые единицы вместо обширных скриптов. Когда какой-то шаг терпит неудачу, причина сбоя должна указывать на конкретную ответственность, а не на запутанную цепочку операций. Сохраняйте структуру графа простой и типизированной. Вложенные структуры скрывают информацию о том, какой узел заполнил тот или иной поле, и мешают возобновлению работы после прерываний.
Поиск: «вам нужно проанализировать наш квартальный доход»
Поиск, который необходимо организовать, работает наилучшим образом, когда его рассматривают как измеримую структуру. Соберите один идеальный пример результатов, один случай сбоя и запись о возврате к предыдущему состоянию перед расширением объема работ. Рассматривайте этот этап как контракт между входными данными и проверенными результатами. Дайте названия элементам, определите критерии успеха и не соглашайтесь на молчаливое частичное выполнение задачи. Сохраняйте структуру графа простой и типизированной. Вложенные структуры данных скрывают информацию о том, какой узел заполнил тот или иной поле, и приводят к нарушению последовательности выполнения после перерывов.
Results: 2 found | Method: tfidf-cosine-similarity
#1 Finance Agent — Score: 3.5
ID: urn:ai:analytics.snowflake-demo.com:analytics:finance-agent
Tags: finance, revenue, ASC-606, ARR, bookings
Capabilities: text-to-sql, metric-disambiguation#2 Executive Agent — Score: 1.5
ID: urn:ai:analytics.snowflake-demo.com:analytics:executive-agent
Tags: executive, cross-domain, orchestrator, KPI
Capabilities: text-to-sql, metric-disambiguation, multi-tool-routing
Поиск: «Какие клиенты склонны уйти?»
Поиск клиентов на определенной стадии работает лучше всего, когда его рассматривают как измеримую величину. Соберите один пример успешного выполнения, один случай сбоя и записку о возврате к предыдущему состоянию перед расширением объема работ. Записывайте время выполнения и стоимость токенов или запросов рядом с функциональными результатами. Отслеживание затрат на раннем этапе предотвращает неожиданные счета при переходе от демо-среды к общедоступным средам. Сохраняйте структуру графа простой и типизированной; вложенные структуры скрывают информацию о том, какой узел заполнил какое поле, и могут нарушить возобновление работы после прерываний.
Results: 1 found | Method: tfidf-cosine-similarity
#1 CS Agent — Score: 10.5
ID: urn:ai:analytics.snowflake-demo.com:analytics:cs-agent
Tags: customer-success, health-score, churn, NPS, CSAT
Поиск: «прогноз потока» с возможностями фильтрации=[“text-to-sql”]
Прогнозирование процесса поиска с использованием этапов работает наилучшим образом, когда его рассматривают как измеримую структуру. Соберите один идеальный пример обработки данных, один случай сбоя и запись о возврате к предыдущему состоянию перед расширением объёма работ. Храните конфигурацию вне кода приложения. Файлы среды, хранилища секретов и флаги функций должны находиться в одном месте, чтобы операторы могли их проверять, не читая весь граф. Сохраняйте состояние графа простым и типизированным. Вложенные структуры данных маскируют информацию о том, какой узел заполнил тот или иной поле, и приводят к нарушению возобновления работы после перерывов.
Results: 2 found (filtered from 4 total)
#1 Sales Agent — Score: 8.2
#2 Finance Agent — Score: 2.1
Аспекты просмотра
Механизм Explorer facets работает наилучшим образом, когда его рассматривают как измеримую поверхность. Соберите один пример успешного выполнения, один случай сбоя и запись о возврате к предыдущему состоянию перед расширением объема работ. Документируйте одновременно путь успешного выполнения и путь восстановления. Повторные попытки, проверки человеком и обработка неработающих сообщений являются частью продукта, а не этапом последующей доработки. Сохраняйте структуру графа простой и типизированной. Вложенные структуры данных скрывают информацию о том, какой узел заполнил тот или иной поле, и мешают возобновлению работы после прерываний.
Total Active Entries: 4
Types:
- application/vnd.snowflake.cortex-agent+json (4)
Tags (18 total):
- bookings (2), finance (1), revenue (1), ASC-606 (1), ARR (1),
sales (1), pipeline (1), forecast (1), win-rate (1),
customer-success (1), health-score (1), churn (1), NPS (1),
CSAT (1), executive (1), cross-domain (1), orchestrator (1), KPI (1)
Capabilities:
- text-to-sql (7), metric-disambiguation (7), multi-tool-routing (1)
Тест ворота вызова
Этап тестирования шлюза Invocation работает наилучшим образом, если рассматривать его как измеримую среду. Сохраните один успешный пример выполнения, один случай сбоя и записку о возврате к предыдущему состоянию перед расширением объёма тестирования. Предпочитайте небольшие, тестируемые единицы вместо обширных скриптов. При сбое какого-либо шага причина должна указывать на конкретную ответственность, а не на запутанную цепочку операций. Сохраняйте структуру графа простой и типизированной. Вложенные структуры скрывают информацию о том, какой узел заполнил тот или иной поле, и мешают возобновлению работы после прерываний.
CALL ARD_INVOCATION_GATE('urn:ai:...finance-agent', 'ACCOUNTADMIN')
→ {"authorized": true, "reason": "Role ACCOUNTADMIN is authorized..."}
CALL ARD_INVOCATION_GATE('urn:ai:...finance-agent', 'PUBLIC')
→ {"authorized": false, "reason": "Role PUBLIC lacks FINANCE_AGENT_ROLE grant."}
Слой мониторинга
Этап слоя мониторинга работает наилучшим образом, когда его рассматривают как измеримую поверхность. Соберите один идеальный пример работы, один случай сбоя и запись о возврате к предыдущему состоянию перед расширением объёма работы. Рассматривайте этот этап как контракт между входными данными и проверенными выходными результатами. Дайте названия создаваемым объектам, определите критерии успешного выполнения и не соглашайтесь на молчаливое частичное завершение работы. Сохраняйте структуру графа простой и типизированной. Вложенные структуры данных скрывают информацию о том, какой узел заполнил тот или иной поле, что приводит к нарушению возобновления работы после перерывов.
Что это означает на практике
На практике этап «Что это означает» работает лучше всего, когда его рассматривают как измеримую поверхность. Соберите один идеальный пример работы, один случай сбоя и записку о возврате к предыдущему состоянию перед расширением объёма работ. Записывайте временные показатели, а также стоимость токенов или запросов рядом с функциональными результатами. Отображение стоимости на раннем этапе предотвращает неожиданные счёты при переходе от демо-среды к общедоступным средам. Сохраняйте структуру графа простой и типизированной. Вложенные структуры скрывают информацию о том, какой узел заполнил какое поле, и могут нарушить возобновление работы после прерываний. На практике этап «Что это означает» работает лучше всего, когда его рассматривают как измеримую поверхность. Соберите один идеальный пример работы, один случай сбоя и записку о возврате к предыдущему состоянию перед расширением объёма работ. Документируйте одновременно успешный путь выполнения и путь восстановления. Повторные попытки, проверки человеком и обработка неработающих сообщений являются частью продукта, а не элементами последующей доработки.
"I need to analyze our quarterly revenue figures"
Finance Agent — Score: 15.8
Executive Agent — Score: 3.5
Sales Agent — Score: 3.2
Инструменты для разработчиков
На этапе «Инструменты для разработчиков» необходимо заранее определить входные данные, ответственного за выполнение шага и критерии завершения перед внесением изменений в код. Операторы должны иметь возможность перезапустить шаг, исходя из известной точки контроля, без необходимости угадывать скрытое состояние системы. Лучше использовать небольшие, тестируемые модули вместо обширных скриптов. При сбое шага причина должна быть связана с конкретной функцией, а не с запутанной структурой обработки данных. Аутентификация происходит на входе, а повторная авторизация — на уровне обработки данных. Одного только токена не достаточно для определения границы использования ресурсов.
Что дальше
На этапе «Что дальше» необходимо определить входные данные, ответственного за выполнение шага и критерии завершения перед изменением кода. Операторы должны иметь возможность перезапустить шаг с известной точки контроля, не догадываясь о скрытом состоянии. Рассматривайте этот этап как контракт между входными данными и проверенными выходными результатами. Дайте названия результатам работы, определите критерии успеха и не допускайте молчаливого частичного завершения задачи. Внедрите утверждение человека для операций, связанных с тратой денег или изменением производственных данных. Подключение компонентов во время компиляции не гарантирует полноты выполнения бизнес-задач.
Начало работы
На этапе «Начало работы» необходимо определить входные данные, ответственного за выполнение шага и критерии завершения перед внесением изменений в код. Операторы должны иметь возможность перезапустить шаг с известной точки контроля, не догадываясь о скрытом состоянии. Регистрируйте время выполнения и стоимость токенов или запросов рядом с функциональными результатами. Отображение стоимости заранее предотвращает неожиданные счета при переходе от демо-среды к общедоступным средам. Внедряйте человеческое утверждение для операций, связанных с тратой денег или изменением производственных данных. Настройки во время компиляции не гарантируют полноты функционала продукта. На этапе «Начало работы» необходимо определить входные данные, ответственного за выполнение шага и критерии завершения перед внесением изменений в код. Операторы должны иметь возможность перезапустить шаг с известной точки контроля, не догадываясь о скрытом состоянии. Документируйте одновременно «идеальный путь» выполнения и пути восстановления. Повторные попытки, человеческое утверждение и обработка некорректных сообщений являются частью продукта, а не элементами, добавляемыми позже.
git clone https://github.com/satish/ard-registry.git
cd ard-registry
-- In Snowsight, execute these SQL files in order:
sql/01_infrastructure.sql -- Creates stage, tables, audit log
sql/02_manifest_generator.sql -- Reads agent metadata → ARD manifest
sql/03_ingest.sql -- Parses manifest → searchable registry
sql/04_semantic_rank.sql -- Python UDF (TF-IDF + cosine similarity)
sql/05_search.sql -- Semantic search endpoint
sql/06_list_and_explore.sql -- List + explore endpoints
sql/07_invocation_gate.sql -- RBAC authorization gate
sql/08_monitoring.sql -- Scheduled refresh + health check
sql/10_e2e_test.sql -- Test harness-- Then ingest and verify:
EXECUTE IMMEDIATE $
DECLARE v_manifest VARIANT; v_result VARIANT;
BEGIN
CALL ANALYTICS.AGENTS.ARD_MANIFEST_GENERATOR() INTO v_manifest;
CALL ANALYTICS.AGENTS.ARD_INGEST_MANIFEST(:v_manifest) INTO v_result;
RETURN :v_result;
END;
$;CALL ANALYTICS.AGENTS.ARD_END_TO_END_TEST();
-- Expected: 10/10 PASS (100%)
Чек-лист операционной работы
На этапе составления чек-листа операционной работы необходимо определить входные данные, ответственного за выполнение шага и критерии завершения перед внесением изменений в код. Операторы должны иметь возможность повторно выполнить шаг, исходя из известной точки контроля, без необходимости угадывания скрытого состояния.
Храните конфигурацию вне кода приложения. Файлы среды, хранилища секретов и флаги функций должны находиться в одном месте, которое операторы могут проверять, не читая весь кодовый граф.
Внедряйте проверку с участием человека для операций, связанных с тратой денег или изменением производственных данных. Подключение компонентов во время компиляции не гарантирует полноты функционала продукта.
Напишите краткое руководство по эксплуатации: как обновлять ключи, как опустошать очередь, как откатывать последнюю загрузку данных.
Документируйте как успешный, так и восстановительный сценарии работы. Повторные попытки, проверки человеком и обработка некорректных сообщений являются частью продукта, а не элементами последующей доработки.
Внедряйте человеческое утверждение для операций, связанных с расходованием средств или изменением производственных данных. Компиляционная настройка не гарантирует полноты функционала бизнес-приложения.
Перед внедрением всей стек-технологии заморозьте версии, сохраните эталонные записи для критически важных этапов и уточните шаги отката. В совместных средах необходимы ограничения на частоту запросов, проверки принадлежности пользователя и четко определенный ответственный за обновление секретов. Лучше выбирать надежность, чем креативные одноразовые демонстрации.
Примечание для ba61be007942: не храните ключи поставщика в репозитории, установите лимит токенов на сессию и сохраняйте записи рядом с фикстурами оценки, чтобы последующие замены моделей оставались сопоставимыми.