Notas prácticas: Dentro de ARD: cómo funciona realmente la especificación de descubrimiento de recursos agenciales.
Guía paso a paso para utilizar las notas prácticas: Dentro de ARD: cómo funciona realmente la especificación de descubrimiento de recursos agenciales, incluyendo contratos, verificaciones y espacios para código adicional para los equipos que implementan este patrón.
Las notas siguientes reconstruyen un enfoque práctico para abordar “Inside ARD: How the Agentic Resource Discovery Spec Actually Works”. Se da prioridad a los contratos, las verificaciones y los marcadores de código reutilizables en lugar de a una presentación motivacional. Al trabajar en la etapa de descripción general, anote primero el contrato: las entradas requeridas, la señal de éxito y qué ocurre en caso de fallo parcial. Esa lista de verificación garantiza que los cambios posteriores en el código sean transparentes. Documente tanto la ruta óptima como la ruta de recuperación. Las reintentos, los controles humanos y el manejo de mensajes no entregados forman parte del producto, no son mejoras realizadas posteriormente.
El problema que resuelve ARD
El problema con ARD es que funciona mejor cuando se trata como una superficie medible. Capture una transcripción ejemplar, un caso de fallo y la nota de reversión antes de ampliar el alcance. Prefiera unidades pequeñas y verificables en lugar de scripts extensos. Cuando un paso falla, el fallo debe apuntar a una única responsabilidad y no a un proceso complicado. Mantenga el estado del grafo simple y tipado; los bloques anidados ocultan qué nodo escribió qué campo y provocan interrupciones en la continuación del proceso.
El modelo mental: describir, rastrear, buscar, invocar
El modelo mental que describe esta etapa funciona mejor cuando se trata como una superficie medible. Capture un registro ejemplar, un caso de fallo y la nota de reversión antes de ampliar el alcance. Considere esta etapa como un contrato entre las entradas y los resultados validados. Asigne nombres a los artefactos, defina verificaciones de éxito y rechace las completaciones parciales silenciosas. Asigne un presupuesto de tokens por turno y por sesión; las herramientas agentes amplían el contexto de forma agresiva; los límites máximos evitan que las demostraciones se conviertan en facturas inesperadas.
Describiendo un recurso: el manifiesto ai-catalog.json
La etapa de descripción de un recurso funciona mejor cuando se trata como una superficie medible. Capture una transcripción ideal, un caso de fallo y la nota de reversión antes de ampliar el alcance. Registre los tiempos y el costo de tokens o consultas junto con los resultados funcionales. Tener visibilidad del costo desde el principio evita facturas inesperadas cuando el proceso pasa de la fase de demostración a entornos compartidos. Mantenga el estado del gráfico simple y tipado; los bloques anidados ocultan qué nodo escribió qué campo y causan interrupciones en la continuación del proceso. La etapa de descripción de un recurso funciona mejor cuando se trata como una superficie medible. Capture una transcripción ideal, un caso de fallo y la nota de reversión antes de ampliar el alcance. Documente tanto el camino óptimo como el camino de recuperación. Las reintentos, los controles humanos y el manejo de mensajes no entregados forman parte del producto, no son ajustes realizados posteriormente.
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"
]
}
]
}
Identidad: por qué el identificador parece un URN
En cuanto a la identidad, durante la fase de definición del identificador se deben establecer las entradas, el responsable de cada paso y los criterios de finalización antes de modificar el código. Los operadores deben poder volver a ejecutar el paso a partir de un punto de control conocido, sin tener que adivinar el estado oculto. Es preferible utilizar unidades pequeñas y verificables en lugar de scripts extensos. Cuando un paso falla, el error debe indicar una única responsabilidad y no un proceso complicado. Se debe incluir la aprobación humana en aquellos casos en que se gastan fondos o se modifican datos de producción. La configuración en tiempo de compilación no equivale a la completitud del proceso empresarial.
La API: búsqueda, exploración y una lista sencilla
En la fase de exploración de búsquedas mediante la API, defina las entradas, el responsable de cada paso y los criterios de finalización antes de modificar el código. Los operadores deben poder volver a ejecutar el paso a partir de un punto de control conocido, sin tener que adivinar el estado oculto. Considere esta fase como un contrato entre las entradas y los resultados validados. Asigne nombres a los artefactos, defina verificaciones de éxito y rechace las completaciones parciales silenciosas. Incorpore la aprobación humana en aquellos casos en que se gasten fondos o se modifiquen datos de producción. La conexión en tiempo de compilación no equivale a la completitud del proceso empresarial.
{
"query": {
"text": "I need to digitize an invoice's line items",
"filter": {
"type": ["application/mcp-server+json"]
}
},
"pageSize": 5
}
Federación: registros que se comunican entre sí
Para los registros de Federation que se comunican con la etapa de ejecución, defina las entradas, el responsable de cada paso y los criterios de finalización antes de modificar el código. Los operadores deben poder volver a ejecutar el paso a partir de un punto de control conocido sin tener que adivinar el estado oculto. Registre los tiempos de ejecución y el costo de tokens o consultas junto con los resultados funcionales. La visibilidad temprana del costo evita facturas inesperadas cuando el flujo pasa de entornos de demostración a entornos compartidos. Incorpore la aprobación humana en aquellos procesos que generan gastos o modifican datos de producción. La conexión en tiempo de compilación no equivale a la completitud del proceso empresarial. Para los registros de Federation que se comunican con la etapa de ejecución, defina las entradas, el responsable de cada paso y los criterios de finalización antes de modificar el código. Los operadores deben poder volver a ejecutar el paso a partir de un punto de control conocido sin tener que adivinar el estado oculto. Documente tanto la ruta óptima como la ruta de recuperación. Las reintentos, los controles humanos y el manejo de mensajes no entregados forman parte del producto, no algo aparte.
Efecto de pulido final.
Dónde se integra realmente en un chatbot
Al trabajar en la fase de determinar dónde se integra realmente, anote primero el contrato: entradas requeridas, señal de éxito y qué ocurre en caso de fallo parcial. Esa lista de verificación mantiene honestas las futuras modificaciones del código. Prefiera unidades pequeñas y probables sobre scripts extensos. Cuando un paso falla, el fallo debe apuntar a una única responsabilidad en lugar de a un proceso complicado. Haga puntos de control después de los pasos costosos. La función de reanudación no debe volver a facturar la misma llamada al LLM cuando un operador intenta nuevamente un nodo posterior.
Desarrollándolo en la práctica: una implementación de ARD en producción en Snowflake
Al trabajar en la fase de “Construirlo en realidad”, anote primero el contrato: los datos necesarios, la señal de éxito y qué ocurre en caso de un fallo parcial. Esa lista de verificación mantiene honestas las futuras modificaciones del código. Trate esta fase como un contrato entre los datos de entrada y los resultados validados. Asigne nombres a los artefactos, defina las comprobaciones de éxito y evite completaciones parciales silenciosas. Haga una verificación después de los pasos costosos. La función de reanudación no debe volver a facturar la misma llamada al LLM cuando un operador intenta nuevamente un nodo posterior.
┌─────────────────────────────────────────────────────────────┐
│ 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) │
└─────────────────────────────────────────────────────────────┘
Nivel 1: Generación automática del manifiesto a partir de agentes en tiempo real
Al trabajar en la etapa de generación automática de Capa 1, anote primero el contrato: los inputs requeridos, la señal de éxito y qué ocurre en caso de fallo parcial. Esa lista de verificación garantiza que los cambios posteriores en el código sean transparentes. Registre los tiempos y el costo de tokens o consultas junto con los resultados funcionales. Tener visibilidad del costo desde el principio evita facturas inesperadas cuando el proceso pasa de la versión de demostración a entornos compartidos. Haga un punto de control después de los pasos costosos. La reanudación no debe volver a facturar la misma llamada al LLM cuando un operador intenta nuevamente un nodo posterior. Al trabajar en la etapa de generación automática de Capa 1, anote primero el contrato: los inputs requeridos, la señal de éxito y qué ocurre en caso de fallo parcial. Esa lista de verificación garantiza que los cambios posteriores en el código sean transparentes. Documente tanto la ruta óptima como la ruta de recuperación. Las reintentos, los controles humanos y el manejo de mensajes no entregados forman parte del producto, no son mejoras adicionales realizadas posteriormente.
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"}
]
}
}
]
}
Capa 2: Ingestión en un registro buscable
La etapa de ingestión de la Capa 2 funciona mejor cuando se trata como una superficie medible. Capture una transcripción de referencia, un caso de fallo y la nota de reversión antes de ampliar el alcance. Prefiera unidades pequeñas y verificables en lugar de scripts extensos. Cuando falla un paso, el fallo debe apuntar a una única responsabilidad y no a un proceso complicado. Mantenga el estado del grafo simple y tipado. Los bloques anidados ocultan qué nodo escribió qué campo y provocan interrupciones en la continuación del proceso.
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)
Capa 3: Búsqueda semántica: el enfoque con UDF en Python
La etapa de búsqueda semántica de Capa 3 funciona mejor cuando se trata como una superficie medible. Capture un registro ideal, un caso de fallo y la nota de reversión antes de ampliar el alcance. Trate esta etapa como un contrato entre las entradas y las salidas validadas. Asigne nombres a los artefactos, defina verificaciones de éxito y rechace las completaciones parciales silenciosas. Fije el intérprete y el archivo de bloqueo de dependencias antes de enseñar el bucle. La diferencia entre la computadora portátil y los entornos de integración continua es la causa más común de fallos silenciosos en las demostraciones de 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
$;
Capa 4: La puerta de invocación — RBAC antes de la ejecución
La etapa de invocación de la Capa 4 funciona mejor cuando se trata como una superficie medible. Capture un registro ideal, un caso de fallo y la nota de reversión antes de ampliar el alcance. Registre los tiempos y el costo de tokens o consultas junto con los resultados funcionales. Tener visibilidad del costo desde el principio evita facturas inesperadas cuando el proceso pasa de la fase de demostración a entornos compartidos. Mantenga el estado del gráfico simple y tipado; los bloques anidados ocultan qué nodo escribió qué campo y causan interrupciones en la continuación del proceso. La etapa de invocación de la Capa 4 funciona mejor cuando se trata como una superficie medible. Capture un registro ideal, un caso de fallo y la nota de reversión antes de ampliar el alcance. Documente tanto el camino óptimo como el camino de recuperación juntos. Las reintentos, los controles humanos y el manejo de mensajes no entregados forman parte del producto, no son mejoras posteriores.
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."}
Capa 5: El servidor de manifiesto de Streamlit
Para la etapa Layer 5 de Streamlit, defina las entradas, el responsable del paso y los criterios de finalización antes de modificar el código. Los operadores deben poder volver a ejecutar el paso a partir de un punto de control conocido sin tener que adivinar el estado oculto. Prefiera unidades pequeñas y verificables en lugar de scripts extensos. Cuando un paso falla, el error debe indicar una única responsabilidad y no un proceso complicado. Incluya la aprobación humana en aquellos casos en que se gastan fondos o se modifican datos de producción. La conexión en tiempo de compilación no equivale a la completitud del proceso empresarial.
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: El conjunto de pruebas de extremo a extremo
En la etapa de extremo a extremo del Nivel 6, se deben definir las entradas, el responsable de cada paso y los criterios de finalización antes de modificar el código. Los operadores deben poder volver a ejecutar el paso a partir de un punto de control conocido, sin tener que adivinar el estado oculto. Esta etapa debe considerarse como un contrato entre las entradas y los resultados validados. Se deben nombrar los artefactos, definir las verificaciones de éxito y rechazar cualquier completación parcial silenciosa. Es necesario autenticarse en la pasarela y volver a autorizarlo en el plano de datos; un token portador por sí solo no constituye un límite entre entidades.
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..."
}
Fortalecimiento en producción: qué falla y cómo lo solucionamos
En la fase de endurecimiento para producción, antes de modificar el código, se deben definir las entradas, el responsable del paso y los criterios de finalización. Los operadores deben poder volver a ejecutar el paso a partir de un punto de control conocido, sin tener que adivinar el estado oculto. Se deben registrar los tiempos de ejecución y el costo de tokens o consultas junto con los resultados funcionales. La visibilidad temprana del costo evita facturas inesperadas cuando el proceso pasa de entornos de demostración a entornos compartidos. Se debe incluir la aprobación humana en aquellos casos que impliquen gastos o cambios en datos de producción. La configuración en tiempo de compilación no equivale a la completitud del proceso empresarial. En la fase de endurecimiento para producción, antes de modificar el código, se deben definir las entradas, el responsable del paso y los criterios de finalización. Los operadores deben poder volver a ejecutar el paso a partir de un punto de control conocido, sin tener que adivinar el estado oculto. Se deben documentar conjuntamente la ruta óptima y la ruta de recuperación. Las reintentos, los controles humanos y el manejo de mensajes no entregados forman parte del producto, no algo aparte.
Efecto de pulido final.
El servidor de manifiesto de Streamlit: servir ARD mediante HTTP
Al trabajar en la etapa del servidor de manifiesto de Streamlit, anote primero el contrato: entradas requeridas, señal de éxito y qué ocurre en caso de fallo parcial. Esa lista de verificación mantiene honestas las futuras modificaciones del código. Prefiera unidades pequeñas y probables sobre scripts extensos. Cuando un paso falla, el fallo debe apuntar a una única responsabilidad en lugar de a un proceso complicado. Haga puntos de control después de pasos costosos. La función de reanudación no debe volver a realizar la misma llamada al LLM cuando un operador intenta nuevamente un nodo posterior.
Despliegue
Al trabajar en la fase de despliegue, anote primero el contrato: los datos de entrada requeridos, la señal de éxito y qué ocurre en caso de fallo parcial. Esa lista de verificación mantiene honestas las futuras modificaciones del código. Trate esta fase como un contrato entre los datos de entrada y los resultados validados. Asigne nombres a los artefactos, defina comprobaciones de éxito y rechace las completaciones parciales silenciosas. Haga una verificación después de los pasos costosos. La función de reanudación no debe volver a facturar la misma llamada al LLM cuando un operador intenta nuevamente un nodo posterior.
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;
El código completo de Streamlit
Al trabajar en la etapa completa del código fuente de Streamlit, anote primero el contrato: las entradas requeridas, la señal de éxito y qué ocurre en caso de fallo parcial. Esa lista de verificación mantiene honestas las futuras modificaciones del código. Registre los tiempos y el costo de tokens o consultas junto con los resultados funcionales. Tener visibilidad del costo desde el principio evita facturas inesperadas cuando se pasa de entornos de demostración a entornos compartidos. Haga un punto de control después de los pasos costosos. La reanudación no debe volver a facturar la misma llamada al LLM cuando un operador vuelve a intentar un nodo posterior.
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"
])
Pestaña 1: El manifiesto en bruto
Al trabajar en la pestaña 1, la etapa “raw”, anote primero el contrato: los datos de entrada requeridos, la señal de éxito y qué ocurre en caso de fallo parcial. Esa lista de verificación ayuda a mantener honestas las futuras modificaciones del código. Guarde la configuración fuera del código de la aplicación. Los archivos de entorno, los almacenes de datos secretos y las banderas de funcionalidad deben encontrarse en un lugar donde los operadores puedan auditarlos sin tener que leer todo el sistema. Haga un punto de control después de los pasos costosos. La función de reanudación no debe volver a facturar la misma llamada al LLM cuando un operador intente nuevamente un nodo posterior.
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"
)
Pestaña 2: Búsqueda semántica interactiva
Al trabajar en la etapa semántica interactiva de Tab 2, anote primero el contrato: las entradas requeridas, la señal de éxito y qué ocurre en caso de fallo parcial. Esa lista de verificación mantiene honestas las futuras modificaciones del código. Documente junto con ello el camino óptimo y el camino de recuperación. Las reintentos, los controles humanos y el manejo de mensajes no entregados forman parte del producto, no son mejoras posteriores. Haga un punto de control después de los pasos costosos. Resume no debe volver a facturar la misma llamada al LLM cuando un operador vuelve a intentar un nodo posterior.
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: Exploración por facetas
Al trabajar en la fase de exploración facetada de la Pestaña 3, anote primero el contrato: los datos requeridos, la señal de éxito y qué ocurre en caso de fallo parcial. Esa lista de verificación mantiene honestas las futuras modificaciones del código. Prefiera unidades pequeñas y probables sobre scripts extensos. Cuando un paso falla, el fallo debe apuntar a una única responsabilidad y no a un proceso complicado. Haga una verificación después de los pasos costosos. La función de reanudación no debe volver a facturar la misma llamada al LLM cuando un operador intenta nuevamente un nodo posterior.
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']})")
Pestaña 4: Referencia de API
Al trabajar en la fase de referencia de la API Tab 4, anote primero el contrato: las entradas requeridas, la señal de éxito y qué ocurre en caso de fallo parcial. Esa lista de verificación mantiene honestas las futuras modificaciones del código. Trate esta fase como un contrato entre las entradas y las salidas validadas. Asigne nombres a los artefactos, defina comprobaciones de éxito y rechace las completaciones parciales silenciosas. Haga una verificación después de los pasos costosos. La función de reanudación no debe volver a facturar la misma llamada al LLM cuando un operador intenta nuevamente un nodo posterior.
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>
""")
Accediendo a la aplicación
Al trabajar en la etapa de Acceso a la aplicación, anote primero el contrato: los datos de entrada requeridos, la señal de éxito y qué ocurre en caso de fallo parcial. Esa lista de verificación garantiza que los cambios posteriores en el código sean transparentes. Registre los tiempos de ejecución y el costo del token o la consulta junto con los resultados funcionales. Tener visibilidad temprana del costo evita facturas inesperadas cuando el proceso pasa de la versión de demostración a entornos compartidos. Haga una verificación después de los pasos más costosos. La función de reanudación no debe volver a facturar la misma llamada al LLM cuando un operador intenta nuevamente un nodo posterior. Al trabajar en la etapa de Acceso a la aplicación, anote primero el contrato: los datos de entrada requeridos, la señal de éxito y qué ocurre en caso de fallo parcial. Esa lista de verificación garantiza que los cambios posteriores en el código sean transparentes. Documente tanto la ruta óptima como la ruta de recuperación. Las intentonas repetidas, los controles humanos y el manejo de mensajes no entregados forman parte del producto, no son mejoras adicionales realizadas posteriormente.
Resultados de las pruebas en tiempo real
La etapa de resultados de pruebas en tiempo real funciona mejor cuando se trata como una superficie medible. Capture un registro ideal, un caso de fallo y la nota de reversión antes de ampliar el alcance. Prefiera unidades pequeñas y probables sobre scripts extensos. Cuando falla un paso, el fallo debe apuntar a una única responsabilidad en lugar de a un proceso complicado. Mantenga el estado del gráfico simple y tipado. Los bloques anidados ocultan qué nodo escribió qué campo y provocan interrupciones en la continuación después de las interrupciones.
Búsqueda: “necesita analizar nuestros ingresos trimestrales”
La búsqueda que necesita llevar a cabo funciona mejor cuando se trata como una superficie medible. Capture un registro exitoso, un caso de fallo y la nota de reversión antes de ampliar el alcance. Considere esta etapa como un contrato entre las entradas y los resultados validados. Asigne nombres a los artefactos, defina verificaciones de éxito y rechace las completaciones parciales silenciosas. Mantenga el estado del grafo plano y tipado. Los bloques anidados ocultan qué nodo escribió qué campo y provocan interrupciones en la continuación del proceso.
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
Búsqueda: “¿Qué clientes tienen probabilidades de abandonar?”
La búsqueda de clientes en etapa funciona mejor cuando se trata como una superficie medible. Capture un registro exitoso, un caso de fallo y la nota de reversión antes de ampliar el alcance. Registre los tiempos y el costo de tokens o consultas junto con los resultados funcionales. Tener visibilidad del costo desde el principio evita facturas inesperadas cuando el proceso pasa de la versión de demostración a entornos compartidos. Mantenga el estado del gráfico simple y con tipos definidos; los bloques anidados ocultan qué nodo escribió qué campo y causan interrupciones en la continuación del proceso.
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
Búsqueda: “pipeline forecast” con capacidades de filtrado=[“text-to-sql”]
El modelo de pronóstico del pipeline de búsqueda con etapas funciona mejor cuando se trata como una superficie medible. Capture un transcripte ideal, un caso de fallo y la nota de reversión antes de ampliar el alcance. Mantenga la configuración fuera del código de la aplicación. Los archivos de entorno, los almacenes de secretos y las banderas de funcionalidad deben estar en un lugar donde los operadores puedan auditarlos sin tener que leer todo el grafo. Mantenga el estado del grafo plano y tipado. Los bloques anidados ocultan qué nodo escribió qué campo y provocan interrupciones en la continuación del proceso.
Results: 2 found (filtered from 4 total)
#1 Sales Agent — Score: 8.2
#2 Finance Agent — Score: 2.1
Facetas del explorador
Las fases de Explorer funcionan mejor cuando se tratan como una superficie medible. Capture un registro exitoso, un caso de fallo y la nota de reversión antes de ampliar el alcance. Documente tanto el camino óptimo como el camino de recuperación juntos. Las reintentos, los controles humanos y el manejo de mensajes no entregados forman parte del producto, no son mejoras posteriores. Mantenga el estado del gráfico simple y tipado; los bloques anidados ocultan qué nodo escribió qué campo y provocan interrupciones en la continuación después de las interrupciones.
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)
Prueba de control de invocación
La etapa de pruebas de la puerta de invocación funciona mejor cuando se trata como una superficie medible. Capture un registro exitoso, un caso de fallo y la nota de reversión antes de ampliar el alcance. Prefiera unidades pequeñas y probables sobre scripts extensos. Cuando un paso falla, el fallo debe apuntar a una única responsabilidad en lugar de a un proceso complicado. Mantenga el estado del grafo simple y tipado. Los bloques anidados ocultan qué nodo escribió qué campo y provocan interrupciones en la continuación después de las interrupciones.
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."}
La capa de monitoreo
La etapa de capa de monitoreo funciona mejor cuando se trata como una superficie medible. Capture un registro ejemplar, un caso de fallo y la nota de reversión antes de ampliar el alcance. Considere esta etapa como un contrato entre las entradas y las salidas validadas. Asigne nombres a los artefactos, defina verificaciones de éxito y rechace las completaciones parciales silenciosas. Mantenga el estado del grafo plano y tipado; los bloques anidados ocultan qué nodo escribió qué campo y provocan interrupciones en la continuación del proceso.
Qué significa esto en la práctica
En la práctica, esta etapa funciona mejor cuando se trata como una superficie medible. Capture un registro ideal, un caso de fallo y la nota de reversión antes de ampliar el alcance. Registre los tiempos y el costo de tokens o consultas junto con los resultados funcionales. Tener visibilidad del costo desde el principio evita facturas inesperadas cuando el proceso pasa de la demostración a entornos compartidos. Mantenga el estado del gráfico simple y tipado; los bloques anidados ocultan qué nodo escribió qué campo y causan interrupciones en la continuación del proceso. En la práctica, esta etapa funciona mejor cuando se trata como una superficie medible. Capture un registro ideal, un caso de fallo y la nota de reversión antes de ampliar el alcance. Documente tanto el camino óptimo como el camino de recuperación. Las reintentos, los controles humanos y el manejo de mensajes no entregados forman parte del producto, no son ajustes realizados posteriormente.
"I need to analyze our quarterly revenue figures"
Finance Agent — Score: 15.8
Executive Agent — Score: 3.5
Sales Agent — Score: 3.2
Herramientas para implementadores
En la fase de Herramientas para implementadores, se deben definir las entradas, el responsable de cada paso y los criterios de finalización antes de modificar el código. Los operadores deben poder volver a ejecutar el paso a partir de un punto de control conocido, sin tener que adivinar el estado oculto. Es preferible utilizar unidades pequeñas y verificables en lugar de scripts extensos. Cuando un paso falla, el error debe indicar una única responsabilidad y no un proceso complicado. Autenticarse en la pasarela de entrada y volver a autorizarlo en el plano de datos. Un token portador por sí solo no constituye un límite entre tenencias.
Próximos pasos
En la fase de “¿Qué sigue?”, defina las entradas, el responsable del paso y los criterios de finalización antes de modificar el código. Los operadores deben poder volver a ejecutar el paso a partir de un punto de control conocido, sin tener que adivinar el estado oculto. Considere esta fase como un contrato entre las entradas y los resultados validados. Asigne nombres a los artefactos, defina verificaciones de éxito y rechace las completaciones parciales silenciosas. Incluya la aprobación humana en aquellos casos que impliquen gastos o cambios en datos de producción. La conexión en tiempo de compilación no equivale a la completitud del proceso empresarial.
Comenzando
En la fase de inicio, defina las entradas, el responsable del paso y los criterios de finalización antes de modificar el código. Los operadores deben poder volver a ejecutar el paso a partir de un punto de control conocido sin tener que adivinar el estado oculto. Registre los tiempos de ejecución y el costo en tokens o consultas junto con los resultados funcionales. La visibilidad temprana de los costos evita facturas inesperadas cuando el proceso pasa de la fase de demostración a entornos compartidos. Incorpore la aprobación humana en aquellos casos en que se gastan fondos o se modifican datos de producción. La configuración en tiempo de compilación no equivale a la completitud del proceso empresarial. En la fase de inicio, defina las entradas, el responsable del paso y los criterios de finalización antes de modificar el código. Los operadores deben poder volver a ejecutar el paso a partir de un punto de control conocido sin tener que adivinar el estado oculto. Documente tanto la ruta óptima como la ruta de recuperación. Las intentonas repetidas, los controles humanos y el manejo de mensajes no entregados forman parte del producto, no son mejoras aplicadas posteriormente.
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%)
Lista de verificación operativa
En la fase de lista de verificación operativa, defina las entradas, el responsable de cada paso y los criterios de finalización antes de modificar el código. Los operadores deben poder volver a ejecutar el paso a partir de un punto de control conocido, sin tener que adivinar el estado oculto.
Mantenga la configuración fuera del código de la aplicación. Los archivos de entorno, los almacenes de datos secretos y las banderas de funcionalidad deben estar en un lugar donde los operadores puedan auditarlos sin necesidad de leer todo el sistema.
Coloque la aprobación humana en aquellos procesos que generan gastos o modifican datos de producción. La conexión realizada en tiempo de compilación no equivale a una solución completa desde el punto de vista empresarial.
Escriba un manual breve: cómo rotar claves, cómo vaciar la cola de tareas y cómo revertir la última operación de inserción.
Documente tanto el camino óptimo como el proceso de recuperación. Las intentonas repetidas, los controles humanos y el manejo de mensajes no entregados forman parte del producto, no son algo que se añada posteriormente.
Se debe obtener aprobación humana para las operaciones que implican gastos o modificaciones en los datos de producción. La configuración en tiempo de compilación no equivale a una solución completa para el negocio.
Antes de promocionar la tecnología, congele las versiones, guarde una transcripción de referencia para el camino crítico y confirme los pasos para revertir cambios. Los entornos compartidos requieren límites de velocidad, verificaciones de asignación y un responsable claro para la rotación de credenciales secretas. Prefiera una fiabilidad sencilla a demostraciones ingeniosas pero puntuales.
Nota para el lote ba61be007942: mantenga las claves del proveedor fuera del repositorio, establezca un límite para los tokens por sesión y almacene las transcripciones junto a los archivos de prueba para que los cambios en los modelos posteriores sigan siendo comparables.