Notes pratiques : À l’intérieur d’ARD : Comment la spécification de découverte de ressources agnitives fonctionne réellement
Guide pratique détaillé des notes pratiques : À l’intérieur d’ARD : Comment la spécification de découverte de ressources agnitives fonctionne réellement, avec des contrats, des vérifications et des emplacements de code prêts à l’emploi pour les équipes utilisant ce modèle.
Les notes suivantes reconstituent une approche pratique pour aborder « Inside ARD : Comment fonctionne réellement la spécification de découverte de ressources agnitives ». L’accent est mis sur les contrats, les vérifications et les placeholders de code à insérer, plutôt que sur une présentation motivante. Lors de la phase d’aperçu, notez d’abord le contrat : les entrées requises, le signal de succès et ce qui se passe en cas d’échec partiel. Cette liste de contrôle permet de rester honnête lors des modifications ultérieures du code. Documentez à la fois le parcours normal et les scénarios de récupération. Les tentatives répétées, les contrôles humains et la gestion des messages non livrés font partie intégrante du produit, et non d’une mise en forme ultérieure.
Le problème que résout ARD
Le problème avec ARD est que les étapes fonctionnent le mieux lorsqu’elles sont traitées comme des surfaces mesurables. Capturez un exemple réussi, un cas d’échec et la note de réversion avant d’élargir le périmètre. Préférez des unités petites et testables aux scripts complexes. Lorsqu’une étape échoue, l’erreur doit pointer vers une seule responsabilité plutôt que vers un processus embrouillé. Maintenez l’état des graphes simple et typé. Les blocs imbriqués cachent le fait que tel nœud a écrit telle champ et perturbent la reprise après interruption.
Le modèle mental : décrire, parcourir, rechercher, invoquer
Le modèle mental qui décrit cette étape fonctionne le mieux lorsqu’il est considéré comme une surface mesurable. Capturez un exemple réussi, un cas d’échec et la note de réversion avant d’élargir le périmètre. Considérez cette étape comme un contrat entre les entrées et les sorties validées. Donnez des noms aux artefacts, définez des critères de succès et refusez toute mise en œuvre partielle silencieuse. Fixez un budget de tokens par tour et par session. Les outils agents élargissent l’étendue du contexte de manière importante ; des plafonds stricts empêchent que les démonstrations se transforment en factures inattendues.
Description d’une ressource : le manifest ai-catalog.json
La phase de description d’une ressource fonctionne le mieux lorsqu’elle est considérée comme une surface mesurable. Capturez un enregistrement idéal, un cas d’échec et la note de réversion avant d’élargir le périmètre. Enregistrez les temps d’exécution ainsi que le coût des tokens ou des requêtes à côté des résultats fonctionnels. Une visibilité précoce des coûts évite les factures inattendues lorsque le processus passe d’un environnement de démonstration à des environnements partagés. Maintenez l’état du graphe plat et typé. Les blocs imbriqués masquent l’identité du nœud qui a modifié tel champ et perturbent la reprise après interruption. La phase de description d’une ressource fonctionne le mieux lorsqu’elle est considérée comme une surface mesurable. Capturez un enregistrement idéal, un cas d’échec et la note de réversion avant d’élargir le périmètre. Documentez ensemble le parcours réussi et le parcours de récupération. Les tentatives de réessai, les contrôles humains et le traitement des messages non livrés font partie intégrante du produit, et non d’une mise en forme ultérieure.
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"
]
}
]
}
Identité : pourquoi l’identifiant ressemble à un URN
Pour l’identité, avant de modifier le code, il faut définir les entrées, le responsable de l’étape et les critères de fin avant d’entrer dans la phase d’identification. Les opérateurs doivent pouvoir relancer l’étape à partir d’un point de contrôle connu, sans avoir à deviner l’état caché. Préférez des unités petites et testables plutôt que des scripts complexes. Lorsqu’une étape échoue, l’échec doit indiquer une seule responsabilité et non un processus embrouillé. Faites approuver par des humains les actions qui entraînent des dépenses ou modifient des données de production. Une connexion en temps de compilation ne garantit pas la complétude du processus métier.
L’API : recherche, exploration et liste simple
Pour la phase d’exploration de recherche via l’API, définissez les entrées, le responsable de l’étape et les critères de fin avant de modifier du code. Les opérateurs doivent pouvoir relancer l’étape à partir d’un point de contrôle connu sans deviner l’état caché. Considérez cette phase comme un contrat entre les entrées et les sorties validées. Nommez les artefacts, définissez des vérifications de succès et refusez toute exécution partielle silencieuse. Faites approuver par un humain les cas où de l’argent est dépensé ou où des données de production sont modifiées. Une connexion en temps de compilation ne garantit pas la complétude du processus métier.
{
"query": {
"text": "I need to digitize an invoice's line items",
"filter": {
"type": ["application/mcp-server+json"]
}
},
"pageSize": 5
}
Fédération : des registres qui communiquent entre eux
Pour les registres de Federation qui communiquent avec l’environnement de test, définissez les entrées, le responsable de l’étape et les critères de sortie avant de modifier le code. Les opérateurs doivent pouvoir relancer l’étape à partir d’un point de contrôle connu sans deviner l’état caché. Enregistrez les temps d’exécution ainsi que le coût des tokens ou des requêtes à côté des résultats fonctionnels. Une visibilité précoce des coûts évite les factures inattendues lorsque le parcours passe de l’environnement de démonstration à des environnements partagés. Imposez une approbation humaine pour les actions qui entraînent des dépenses ou modifient des données de production. La connexion en temps de compilation ne garantit pas la complétude du processus métier. Pour les registres de Federation qui communiquent avec l’environnement de test, définissez les entrées, le responsable de l’étape et les critères de sortie avant de modifier le code. Les opérateurs doivent pouvoir relancer l’étape à partir d’un point de contrôle connu sans deviner l’état caché. Documentez conjointement le parcours normal et les scénarios de récupération. Les tentatives de réexécution, les contrôles humains et la gestion des messages échoués font partie intégrante du produit, et non pas quelque chose d’accessoire.
Polissage final.
Où cela s’intègre réellement dans un chatbot
Lors de l’étape déterminant où cela s’intègre réellement, notez d’abord les exigences : entrées requises, signal de succès et ce qui se passe en cas d’échec partiel. Cette liste de contrôle permet de rester honnête lors des modifications ultérieures du code. Préférez des unités petites et testables plutôt que des scripts volumineux. Lorsqu’une étape échoue, l’échec doit pointer vers une seule responsabilité et non vers un processus complexe. Créez des points de contrôle après les étapes coûteuses. Le système de reprise ne doit pas facturer à nouveau la même appel du LLM lorsque l’opérateur réessaie un nœud ultérieur.
Conception concrète : une implémentation en production ARD sur Snowflake
Lors de la phase « Construire pour de vrai », notez d’abord le contrat : les entrées requises, le signal de succès, ainsi que ce qui se passe en cas d’échec partiel. Cette liste de contrôle permet de garantir l’honnêteté des modifications ultérieures du code. Considérez cette phase comme un contrat entre les entrées et les sorties validées. Donnez des noms aux artefacts, définez des vérifications de succès, et refusez les terminations partielles silencieuses. Faites des points de contrôle après les étapes coûteuses. Le système de reprise ne doit pas facturer à nouveau la même appel du LLM lorsque l’opérateur réessaie un nœud ultérieur.
┌─────────────────────────────────────────────────────────────┐
│ 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) │
└─────────────────────────────────────────────────────────────┘
Niveau 1 : Génération automatique du manifest à partir d’agents en temps réel
Lors du travail sur l’étape d’auto-génération de la couche 1, notez d’abord le contrat : les entrées requises, le signal de succès et ce qui se passe en cas d’échec partiel. Cette liste de contrôle permet de garantir l’intégrité des modifications ultérieures du code. Enregistrez les temps d’exécution ainsi que le coût des tokens ou des requêtes à côté des résultats fonctionnels. Une visibilité précoce des coûts évite les factures inattendues lorsque le processus passe d’un environnement de démonstration à des environnements partagés. Créez un point de contrôle après les étapes coûteuses. La reprise du processus ne doit pas facturer à nouveau la même appel de LLM lorsque l’opérateur réessaie un nœud ultérieur. Lors du travail sur l’étape d’auto-génération de la couche 1, notez d’abord le contrat : les entrées requises, le signal de succès et ce qui se passe en cas d’échec partiel. Cette liste de contrôle permet de garantir l’intégrité des modifications ultérieures du code. Documentez ensemble le parcours normal et le parcours de récupération. Les tentatives de réessai, les contrôles humains et la gestion des messages non livrés font partie intégrante du produit, et non d’améliorations apportées ultérieurement.
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"}
]
}
}
]
}
Niveau 2 : Intégration dans un registre recherchable
L’étape d’intégration au niveau 2 fonctionne le mieux lorsqu’elle est considérée comme une surface mesurable. Capturez un transcript idéal, un cas d’échec et la note de réversion avant d’élargir le périmètre. Préférez des unités petites et testables plutôt que des scripts complexes. Lorsqu’une étape échoue, l’erreur doit indiquer une seule responsabilité plutôt qu’un processus embrouillé. Maintenez l’état du graphe plat et typé. Les blocs imbriqués masquent le fait que tel nœud a écrit telle champ et perturbent la reprise après interruption.
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)
Niveau 3 : Recherche sémantique — l’approche des UDF en Python
La phase de recherche sémantique au niveau 3 fonctionne le mieux lorsqu’elle est considérée comme une surface mesurable. Capturez un transcript parfait, un cas d’échec et la note de réversion avant d’élargir le périmètre. Considérez cette phase comme un contrat entre les entrées et les sorties validées. Nommez les artefacts, définites des critères de succès et refusez toute complétion partielle silencieuse. Fixez l’interpréteur ainsi que le fichier de verrouillage des dépendances avant d’enseigner la boucle. Les écarts entre l’ordinateur portable et les environnements CI sont la cause la plus fréquente de dysfonctionnement silencieux dans les démos 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
$;
Niveau 4 : Le portail d’appel — RBAC avant exécution
La phase d’appel du Niveau 4 fonctionne le mieux lorsqu’elle est considérée comme une surface mesurable. Capturez un enregistrement idéal, un cas d’échec et la note de réversion avant d’élargir le périmètre. Enregistrez les temps d’exécution ainsi que le coût des tokens ou des requêtes à côté des résultats fonctionnels. Une visibilité précoce des coûts évite les factures inattendues lorsque le processus passe de l’environnement de démonstration à des environnements partagés. Maintenez l’état du graphe plat et typé. Les blocs imbriqués masquent l’identité du nœud qui a écrit tel champ et perturbent la reprise après interruption. La phase d’appel du Niveau 4 fonctionne le mieux lorsqu’elle est considérée comme une surface mesurable. Capturez un enregistrement idéal, un cas d’échec et la note de réversion avant d’élargir le périmètre. Documentez ensemble le parcours réussi et le parcours de récupération. Les tentatives répétées, les contrôles humains et le traitement des messages non livrés font partie intégrante du produit, et non d’une mise en forme ultérieure.
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."}
Niveau 5 : Le serveur de manifeste Streamlit
Pour l’étape Layer 5 de Streamlit, définissez les entrées, le responsable de l’étape et les critères de fin avant de modifier le code. Les opérateurs doivent pouvoir relancer l’étape à partir d’un point de contrôle connu sans deviner l’état caché. Préférez des unités petites et testables à des scripts complexes. Lorsqu’une étape échoue, l’échec doit indiquer une seule responsabilité plutôt qu’un pipeline embrouillé. Faites approuver par des humains les étapes qui entraînent des dépenses ou modifient des données de production. La connexion en temps de compilation ne garantit pas la complétude du processus métier.
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 : Le jeu de tests bout en bout
Pour l’étape bout en bout du niveau 6, définissez les entrées, le responsable de l’étape et les critères de fin avant de modifier le code. Les opérateurs doivent pouvoir relancer l’étape à partir d’un point de contrôle connu sans deviner l’état caché. Considérez cette étape comme un contrat entre les entrées et les sorties validées. Nommez les artefacts, définissez des vérifications de succès et refusez toute mise en œuvre partielle silencieuse. Authentifiez-vous au niveau du gateway et réautorisez-vous au niveau du plan de données. Un token porteur seul ne constitue pas une frontière entre les tenants.
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..."
}
Renforcement de la production : ce qui tombe en panne et comment nous l’avons corrigé
Pour l’étape de renforcement en production visant à identifier ce qui peut tomber en panne, définissez les entrées, le responsable de l’étape et les critères d’arrêt avant de modifier le code. Les opérateurs doivent pouvoir relancer l’étape à partir d’un point de contrôle connu sans deviner l’état caché. Enregistrez les temps d’exécution ainsi que le coût des tokens ou des requêtes à côté des résultats fonctionnels. Une visibilité précoce des coûts évite les factures inattendues lorsque le processus passe de l’environnement de démonstration aux environnements partagés. Faites approuver par un humain les étapes qui entraînent des dépenses ou modifient des données de production. La configuration en temps de compilation ne garantit pas la complétude du processus métier. Pour l’étape de renforcement en production visant à identifier ce qui peut tomber en panne, définissez les entrées, le responsable de l’étape et les critères d’arrêt avant de modifier le code. Les opérateurs doivent pouvoir relancer l’étape à partir d’un point de contrôle connu sans deviner l’état caché. Documentez ensemble le parcours normal et le parcours de récupération. Les tentatives de réexécution, les contrôles humains et la gestion des messages non livrés font partie intégrante du produit, et non pas quelque chose d’accessoire.
Polissage final.
Le serveur de manifeste Streamlit — diffusion d’ARD via HTTP
Lors du travail sur l’étape du serveur de manifeste Streamlit, notez d’abord les exigences : entrées requises, signal de succès et ce qui se passe en cas d’échec partiel. Cette liste de contrôle permet de rester honnête lors des modifications ultérieures du code. Préférez des unités petites et testables plutôt que des scripts volumineux. Lorsqu’une étape échoue, l’échec doit indiquer une seule responsabilité et non un processus embrouillé. Créez des points de contrôle après les étapes coûteuses. Le mécanisme de reprise ne doit pas réutiliser la même appel à l’LLM lorsque un opérateur tente à nouveau un nœud ultérieur.
Déploiement
Lors de la phase de déploiement, notez d’abord les conditions du contrat : les entrées requises, le signal de succès, ainsi que ce qui se passe en cas d’échec partiel. Cette liste de contrôle permet de garantir l’honnêteté des modifications ultérieures du code. Considérez cette phase comme un contrat entre les entrées et les sorties validées. Donnez des noms aux artefacts, définez des vérifications de succès, et refusez toute exécution partielle silencieuse. Faites un point après les étapes coûteuses. Le système de reprise ne doit pas facturer à nouveau la même appel du LLM lorsque l’opérateur réessaie un nœud ultérieur.
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;
Le code source complet de Streamlit
Lorsque vous travaillez sur l’étape complète des sources de Streamlit, notez d’abord les exigences : entrées requises, signal de succès, et ce qui se passe en cas d’échec partiel. Cette liste de contrôle permet de rester honnête lors des modifications ultérieures du code. Enregistrez les temps d’exécution ainsi que le coût des tokens ou des requêtes à côté des résultats fonctionnels. Une visibilité précoce des coûts évite les factures inattendues lorsque le processus passe d’un environnement de démonstration à des environnements partagés. Créez un point de contrôle après les étapes coûteuses. La reprise du processus ne doit pas facturer à nouveau la même appel de LLM lorsque l’opérateur réessaie un nœud ultérieur.
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"
])
Tab 1 : Le manifest brut
Lorsque vous travaillez sur l’étape « Tab 1 : État brut », notez d’abord les exigences du contrat : entrées requises, signal de succès, et ce qui se passe en cas d’échec partiel. Cette liste de contrôle permet de rester honnête lors des modifications ultérieures du code. Conservez la configuration en dehors du code de l’application. Les fichiers d’environnement, les bases de données secrètes et les indicateurs fonctionnels doivent être regroupés en un seul endroit que les opérateurs peuvent auditer sans devoir lire l’ensemble du système. Créez des points de contrôle après les étapes coûteuses. Le mécanisme de reprise ne doit pas facturer à nouveau la même appel du LLM lorsque l’opérateur réessaie un nœud ultérieur.
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"
)
Tab 2 : Recherche sémantique interactive
Lorsque vous travaillez sur l’étape sémantique interactive Tab 2, notez d’abord le contrat : les entrées requises, le signal de succès, ainsi que ce qui se passe en cas d’échec partiel. Cette liste de contrôle permet de rester honnête lors des modifications ultérieures du code. Documentez ensemble le parcours normal et le parcours de récupération. Les tentatives répétées, les contrôles humains et la gestion des messages non traités font partie intégrante du produit, et non d’améliorations apportées ultérieurement. Faites un point après les étapes coûteuses. Le système de reprise ne doit pas facturer à nouveau la même appel du LLM lorsque l’opérateur réessaie un nœud ultérieur.
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 : Exploration par facettes
Lors de l’étape d’exploration par facettes de la Tab 3, notez d’abord le contrat : les entrées requises, le signal de succès et ce qui se passe en cas d’échec partiel. Cette liste de contrôle permet de rester honnête lors des modifications ultérieures du code. Préférez des unités petites et testables plutôt que des scripts volumineux. Lorsqu’une étape échoue, l’échec doit indiquer une seule responsabilité et non un processus complexe et embrouillé. Créez des points de contrôle après les étapes coûteuses. Le système de reprise ne doit pas facturer à nouveau la même appel au LLM lorsque l’opérateur réessaie un nœud ultérieur.
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']})")
Tab 4 : Référence API
Lors de la phase d’étude de la référence API Tab 4, notez d’abord les exigences du contrat : entrées requises, signal de succès et conséquences en cas d’échec partiel. Cette liste de contrôle permet de rester honnête lors des modifications ultérieures du code. Considérez cette phase comme un contrat entre les entrées et les sorties validées. Donnez des noms aux éléments générés, définites des vérifications de succès et refusez les terminations partielles silencieuses. Faites des points de contrôle après les étapes coûteuses. Le système de reprise ne doit pas facturer à nouveau la même appel du LLM lorsque l’opérateur réessaie un nœud ultérieur.
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>
""")
Accès à l’application
Lors de la phase d’accès à l’application, notez d’abord le contrat : les entrées requises, le signal de succès et ce qui se passe en cas d’échec partiel. Cette liste de contrôle permet de rester honnête lors des modifications ultérieures du code. Enregistrez les temps d’exécution ainsi que le coût des tokens ou des requêtes à côté des résultats fonctionnels. Une visibilité précoce des coûts évite des factures inattendues lorsque le processus passe de l’environnement de démonstration à des environnements partagés. Faites un point après les étapes coûteuses. La reprise du processus ne doit pas facturer à nouveau la même appel de LLM lorsque l’opérateur réessaie un nœud ultérieur. Lors de la phase d’accès à l’application, notez d’abord le contrat : les entrées requises, le signal de succès et ce qui se passe en cas d’échec partiel. Cette liste de contrôle permet de rester honnête lors des modifications ultérieures du code. Documentez ensemble le parcours normal et le parcours de récupération. Les tentatives de réessai, les contrôles humains et la gestion des messages non traités font partie intégrante du produit, et non d’améliorations ultérieures.
Résultats des tests en direct
La phase des résultats des tests en temps réel fonctionne le mieux lorsqu’elle est considérée comme une surface mesurable. Capturez un transcript idéal, un cas d’échec et la note de réversion avant d’élargir le périmètre des tests. Préférez des unités petites et testables à des scripts complexes. Lorsqu’une étape échoue, l’échec doit pointer vers une seule responsabilité plutôt que vers un processus embrouillé. Maintenez l’état des graphiques simple et typé. Les blocs imbriqués masquent le fait que tel nœud a écrit telle champ et perturbent la reprise après interruption.
Mot de recherche : « vous devez analyser nos revenus trimestriels »
La recherche que vous devez mettre en œuvre fonctionne le mieux lorsqu’elle est considérée comme une surface mesurable. Capturez un exemplaire idéal, un cas d’échec et la note de réversion avant d’élargir le périmètre. Considérez cette étape comme un contrat entre les entrées et les sorties validées. Donnez des noms aux artefacts, définez des vérifications de succès et refusez toute mise en œuvre partielle silencieuse. Maintenez l’état du graphe plat et typé. Les blocs imbriqués masquent le fait que tel nœud a écrit telle champ et perturbent la reprise après interruption.
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
Recherche : « Quels clients sont susceptibles de partir ? »
La recherche visant à identifier quels clients sont en phase de développement fonctionne le mieux lorsqu’elle est traitée comme une donnée mesurable. Capturez un exemple réussi, un cas d’échec ainsi que la note de réversion avant d’élargir le périmètre. Enregistrez les temps d’exécution ainsi que le coût des tokens ou des requêtes à côté des résultats fonctionnels. Une visibilité précoce des coûts évite les factures inattendues lorsque le processus passe de l’environnement de démonstration à des environnements partagés. Gardez l’état des graphes simple et bien typé ; les blocs imbriqués masquent l’identité du nœud qui a modifié tel champ et perturbent la reprise après interruption.
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
Recherche : « pipeline forecast » avec des capacités de filtrage=[“text-to-sql”]
Le modèle de prévision du pipeline de recherche par étapes fonctionne le mieux lorsqu’il est considéré comme une surface mesurable. Capturez un transcript parfait, un cas d’échec et la note de réversion avant d’élargir le périmètre. Conservez la configuration en dehors du code de l’application. Les fichiers d’environnement, les bases de données secrètes et les indicateurs fonctionnels doivent être regroupés en un seul endroit que les opérateurs peuvent auditer sans devoir lire l’ensemble du graphe. Maintenez l’état du graphe plat et typé. Les blocs imbriqués masquent le fait que tel nœud a écrit telle champ et perturbent la reprise après interruption.
Results: 2 found (filtered from 4 total)
#1 Sales Agent — Score: 8.2
#2 Finance Agent — Score: 2.1
Explorer les facettes
Les facettes d’Explorer fonctionnent le mieux lorsqu’elles sont considérées comme une surface mesurable. Capturez un transcript parfait, un cas d’échec et la note de rollback avant d’élargir le périmètre. Documentez ensemble le parcours réussi et le parcours de récupération. Les tentatives répétées, les contrôles humains et le traitement des messages non livrés font partie du produit, et non d’une mise en forme ultérieure. Maintenez l’état des graphes plat et typé. Les blocs imbriqués cachent le fait que tel nœud a écrit tel champ et perturbent la reprise après interruption.
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)
Test du contrôle d’invocation
La phase de test du portail d’Invocation fonctionne le mieux lorsqu’elle est considérée comme une surface mesurable. Capturez un enregistrement réussi, un cas d’échec et la note de réversion avant d’élargir le périmètre des tests. Préférez des unités petites et testables à des scripts complexes. Lorsqu’une étape échoue, l’erreur doit indiquer une seule responsabilité plutôt qu’un processus embrouillé. Maintenez l’état du graphe plat et typé. Les blocs imbriqués masquent le fait que tel nœud a écrit telle champ et perturbent la reprise après interruption.
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 couche de surveillance
La phase de couche de surveillance fonctionne le mieux lorsqu’elle est considérée comme une surface mesurable. Capturez un exemplaire idéal, un cas d’échec et la note de réversion avant d’élargir le périmètre. Considérez cette phase comme un contrat entre les entrées et les sorties validées. Donnez des noms aux artefacts, définez des vérifications de succès et refusez toute complétion partielle silencieuse. Maintenez l’état du graphe plat et typé. Les blocs imbriqués masquent le fait que tel nœud a écrit telle champ et perturbent la reprise après interruption.
Que cela signifie concrètement
Celui-ci signifie que l’étape pratique fonctionne le mieux lorsqu’elle est considérée comme une surface mesurable. Capturez un enregistrement idéal, un cas d’échec et la note de réversion avant d’élargir le périmètre. Enregistrez les temps d’exécution ainsi que le coût des tokens ou des requêtes à côté des résultats fonctionnels. Une visibilité précoce des coûts évite les factures inattendues lorsque le processus passe de la démonstration aux environnements partagés. Maintenez l’état du graphique plat et typé. Les blocs imbriqués masquent le fait quel nœud a écrit quel champ et perturbent la reprise après interruption. Celui-ci signifie que l’étape pratique fonctionne le mieux lorsqu’elle est considérée comme une surface mesurable. Capturez un enregistrement idéal, un cas d’échec et la note de réversion avant d’élargir le périmètre. Documentez ensemble le parcours réussi et le parcours de récupération. Les tentatives répétées, les contrôles humains et la gestion des messages non livrés font partie du produit, et non d’une mise en forme ultérieure.
"I need to analyze our quarterly revenue figures"
Finance Agent — Score: 15.8
Executive Agent — Score: 3.5
Sales Agent — Score: 3.2
Outils pour les implementateurs
Pour l’étape « Outils pour les implementeurs », définissez les entrées, le responsable de l’étape et les critères de fin avant de modifier du code. Les opérateurs doivent pouvoir relancer l’étape à partir d’un point de contrôle connu sans deviner l’état caché. Préférez des unités petites et testables aux scripts complexes. Lorsqu’une étape échoue, l’échec doit indiquer une seule responsabilité plutôt qu’un processus embrouillé. Authentifiez à l’entrée du système et réautorisez au niveau du plan de données. Un jeton porteur seul ne constitue pas une frontière entre les tenants.
Que faire ensuite
Pour l’étape « Que faire ensuite », définissez les entrées, le responsable de l’étape et les critères de fin avant de modifier du code. Les opérateurs doivent pouvoir relancer l’étape à partir d’un point de contrôle connu sans deviner l’état caché. Considérez cette étape comme un contrat entre les entrées et les sorties validées. Donnez des noms aux artefacts, définites des vérifications de succès et refusez les terminaisons partielles silencieuses. Faites approuver par un humain les cas où de l’argent est dépensé ou des données de production sont modifiées. La connexion en temps de compilation ne revient pas à une complétude opérationnelle.
Début
Pendant la phase de démarrage, définissez les entrées, le responsable de l’étape et les critères d’arrêt avant de modifier du code. Les opérateurs doivent pouvoir relancer l’étape à partir d’un point de contrôle connu sans deviner l’état caché. Enregistrez les temps d’exécution ainsi que le coût des tokens ou des requêtes à côté des résultats fonctionnels. Une visibilité précoce des coûts évite les factures inattendues lorsque le processus passe d’un environnement de démonstration à des environnements partagés. Faites approuver par un humain les étapes qui entraînent des dépenses ou modifient des données de production. La configuration en temps de compilation ne garantit pas la complétude du processus métier. Pendant la phase de démarrage, définissez les entrées, le responsable de l’étape et les critères d’arrêt avant de modifier du code. Les opérateurs doivent pouvoir relancer l’étape à partir d’un point de contrôle connu sans deviner l’état caché. Documentez ensemble le parcours normal et les scénarios de récupération. Les tentatives de réexécution, les contrôles humains et la gestion des messages échoués font partie intégrante du produit, et non d’améliorations apportées ultérieurement.
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%)
Liste de contrôle opérationnelle
Pour l’étape de la liste de contrôle opérationnelle, définissez les entrées, le responsable de chaque étape ainsi que les critères d’achèvement avant de modifier du code. Les opérateurs doivent pouvoir relancer l’étape à partir d’un point de contrôle connu sans deviner l’état caché.
Gardez la configuration en dehors du code de l’application. Les fichiers d’environnement, les bases de données secrètes et les indicateurs fonctionnels doivent être regroupés en un seul endroit que les opérateurs peuvent auditer sans avoir à lire l’ensemble du système.
Mettez en place une approbation humaine pour les actions qui entraînent des dépenses ou modifient des données de production. Une connexion réalisée en temps de compilation ne garantit pas une couverture complète des besoins métier.
Rédigez un guide de fonctionnement succinct : comment rotationner les clés, comment vider la file d’attente, comment annuler la dernière ingestion.
Dokumentez à la fois le parcours normal et les procédures de récupération. Les tentatives répétées, les contrôles humains et le traitement des messages échoués font partie intégrante du produit, et non d’améliorations ultérieures.
Apportez une validation humaine pour les étapes qui engagent des dépenses ou modifient les données de production. L’automatisation en temps de compilation ne garantit pas une couverture complète des besoins métier.
Au préalable de promouvoir l’ensemble technique, figez les versions, conservez une transcription exemplaire pour le parcours critique, et vérifiez les étapes de réversion. Les environnements partagés nécessitent des limites de fréquence, des contrôles d’attribution et un responsable clair pour la rotation des secrets. Préférez une fiabilité solide à des démonstrations brillantes mais ponctuelles.
Note de batch pour ba61be007942 : gardez les clés du fournisseur hors du répertoire de code, fixez un plafond pour les tokens par session, et stockez les transcriptions à côté des fichiers d’évaluation afin que les remplacements ultérieurs de modèles restent comparables.