Cortex Agents

Les Cortex Agents orchestrent les sources de données structurées et non structurées pour fournir des informations. Ils planifient des tâches, utilisent des outils pour exécuter ces tâches et génèrent des réponses. Les Agents utilisent Cortex Analyst (structurées) et Cortex Search (non structurées) comme outils, ainsi que des LLMs, pour analyser les données. Cortex Search extrait des informations de sources non structurées, tandis que Cortex Analyst génère du SQL pour traiter des données structurées. Un support complet pour l’identification et l’exécution des outils permet de fournir des applications sophistiquées basées sur les données de l’entreprise.

Le flux de travail comprend quatre éléments clés :

  1. Planification : Les applications passent souvent du traitement de données provenant de sources structurées à celui de sources non structurées. Prenons l’exemple d’une appli conversationnelle conçue pour répondre aux requêtes des utilisateurs. Un utilisateur professionnel peut d’abord demander à connaître les principaux distributeurs en fonction de leur chiffre d’affaires (structurées), puis passer à la recherche d’un contrat (non structurées). Les Cortex Agents peuvent analyser une requête pour orchestrer un plan et parvenir à la solution ou à la réponse.

    1. Explorer les options : Lorsque l’utilisateur pose une question ambiguë (par exemple, « Parlez-moi d’Acme Supplies »), l’agent envisage différentes permutations (produits, lieu ou personnel de vente) pour retirer l’ambiguïté et améliorer la précision.

    2. Diviser en sous-tâches : Les Cortex Agents peuvent diviser une tâche ou une requête (par exemple, « Quelles sont les différences entre les conditions contractuelles pour Acme Supplies et Acme Stationery ? ») en plusieurs parties pour une réponse plus précise.

    3. Effectuer un routage entre les outils : L’agent sélectionne l’outil adéquat, Cortex Analyst ou Cortex Search, pour garantir un accès régi et la conformité aux politiques de l’entreprise.

  2. Utilisation de l’outil : Grâce à la mise en place d’un plan, l’agent récupère les données de manière efficace. Cortex Search extrait des informations de sources non structurées, tandis que Cortex Analyst génère du SQL pour traiter des données structurées. Un support complet pour l’identification et l’exécution des outils permet de fournir des applications sophistiquées basées sur les données de l’entreprise.

  3. Réflexion : Après chaque utilisation de l’outil, l’agent évalue les résultats pour déterminer les étapes suivantes, à savoir demander des éclaircissements, itérer ou générer une réponse finale. Cette orchestration lui permet de traiter des requêtes de données complexes tout en garantissant l’exactitude et la conformité dans le périmètre sécurisé de Snowflake.

  4. Surveillance et adaptation : Après le déploiement, les clients peuvent suivre les métriques, analyser les performances et affiner les comportements pour des améliorations continues. Sur l’application client, les développeurs peuvent utiliser TruLens pour contrôler l’interaction avec l’Agent. En surveillant et en affinant en permanence les contrôles de gouvernance, les entreprises peuvent en toute confiance faire évoluer les agents AI tout en maintenant la sécurité et la conformité.

Pour consulter des tutoriels afin de vous aider pour la prise en main, voir Tutoriels des Cortex Agents.

Note

Bien que Snowflake s’efforce de fournir des réponses de haute qualité, l’exactitude des réponses LLM ou des citations fournies n’est pas garantie. Vous devez examiner toutes les réponses de l’API des Agents avant de les proposer à vos utilisateurs.

Exigences en matière de contrôle d’accès

L’utilisateur effectuant la requête doit avoir :

  • USAGE sur le Cortex Search Service référencé dans la requête.

  • USAGE sur la base de données, le schéma et les tables référencés dans le modèle sémantique de Cortex Analyst

  • Un rôle auquel a été attribué le rôle de base de données CORTEX_USER. Pour plus d’informations, voir Privilèges requis.

Comment utiliser l’API de l’Agent

Cette section présente les étapes de création d’un agent à l’aide de l’API de l’Agent.

Configurer l’authentification de l’API REST

Les APIs REST de Snowflake prennent en charge l’authentification par jeton d’accès programmatique (PATs), l’authentification par paire de clés à l’aide de JSON Web Tokens (JWTs), et OAuth. Pour plus de détails, voir Authentification d”Snowflake REST APIs avec Snowflake.

Créer un modèle sémantique pour Cortex Analyst

Vous pouvez utiliser Cortex Analyst pour créer des requêtes SQL à partir de la langue naturelle. Pour utiliser Cortex Analyst, vous devez créer un modèle sémantique. Pour plus d’informations, voir Créer un modèle sémantique.

Créer un Cortex Search Service

Utilisez Cortex Search pour rechercher dans vos données. Pour plus d’informations, voir CREATE CORTEX SEARCH SERVICE.

Note

Le DEFAULT_ROLE de l’utilisateur effectuant la requête doit avoir le privilège USAGE sur le Cortex Search Service, ainsi que sur la base de données et le schéma dans lesquels il réside.

Appeler l’API

Tout d’abord, localisez l’URL de votre compte Snowflake. Une fois que vous avez votre URL et votre PAT, vous pouvez interroger l’API d’Agents à partir de la ligne de commande avec cURL, en utilisant la syntaxe suivante :

curl -X POST "$SNOWFLAKE_ACCOUNT_BASE_URL/api/v2/cortex/agent:run" \
--header 'Content-Type: application/json' \
--header 'Accept: application/json' \
--header "Authorization: Bearer $PAT" \
--data '{
    "model": "llama3.1-70b",
    "messages": [
        {
            "role": "user",
            "content": [
                {
                    "type": "text",
                    "text": "what are the top 3 customers by revenue"
                }
            ]
        }
    ],
    "tools": [
        {
            "tool_spec": {
                "type": "cortex_search",
                "name": "transcript_search"
            }
        },
        {
            "tool_spec": {
                "type": "cortex_analyst_text_to_sql",
                "name": "data_model"
            }
        }
    ],
    "tool_resources": {
        "transcript_search": {"name": "testdb.testschema.transcript_search_service"},
        "data_model": {"semantic_model_file": "@testdb.testschema.stage/sample_data_model.yaml"}
    }
}'
Copy

La réponse est transmise au client sous forme de flux incrémentiel.

Modèles pris en charge

Vous pouvez utiliser les modèles suivants avec les Cortex Agents pour générer la réponse. Veuillez noter que le modèle n’est pas utilisé pour l’orchestration.

  • llama3.1-70b

  • llama3.3-70b

  • mistral-large2

  • claude-3-5-sonnet

Vous pouvez également spécifier une instruction de réponse pour personnaliser les réponses de l’agent.

{
    "response_instruction": "You will always maintain a friendly tone and provide concise response"
}
Copy

Important

Les Cortex Agents utilisent des modèles qui peuvent ne pas être disponibles dans toutes les régions. Pour plus d’informations, voir Disponibilité.

Disponibilité de la région

Les Cortex Agents sont disponibles dans les régions suivantes :

Fonction
(Modèle)
AWS US West 2
(Oregon)
AWS US East 1
(Virginie du Nord)
AWS Europe Central 1
(Francfort)
AWS Europe Ouest 1
(Irlande)
AWS AP Sud-Est 2
(Sydney)
AWS AP Nord-Est 1
(Tokyo)
Azure Est US 2
(Virginie)
Azure Europe de l’Ouest
(Pays-Bas)
AWS
(inter-régionale)
COMPLETE
(claude-3-5-sonnet)

✔

✔

✔
COMPLETE
(llama3.2-1b)

✔

✔
COMPLETE
(llama3.2-3b)

✔

✔
COMPLETE
(llama3.1-8b)

✔

✔

✔

✔

✔

✔

✔

✔
llama3.1-70b

✔

✔

✔

✔

✔

✔

✔

✔

✔
llama3.3-70b

✔

✔

✔
snowflake-llama-3.3-70b

✔

✔
llama3.1-405b

✔

✔

✔

✔
snowflake-llama-3.1-405b

✔

✔
snowflake-arctic

✔

✔

✔
deepseek-r1

✔
reka-core

✔

✔
reka-flash

✔

✔

✔

✔
mistral-large2

✔

✔

✔

✔

✔

✔

✔

✔

✔
mixtral-8x7b

✔

✔

✔

✔

✔

✔

✔

✔

✔
mistral-7b

✔

✔

✔

✔

✔

✔

✔

✔

✔
jamba-instruct

✔

✔

✔

✔
jamba-1.5-mini

✔

✔

✔

✔
jamba-1.5-large

✔

✔
gemma-7b

✔

✔

✔

✔

✔

✔
e5-base-v2

✔

✔

✔

✔

✔

✔

✔
snowflake-arctic-embed-m

✔

✔

✔

✔

✔

✔

✔

✔

✔
snowflake-arctic-embed-m-v1.5

✔

✔

✔

✔

✔

✔

✔

✔

✔
snowflake-arctic-embed-l-v2.0

✔

✔

✔

✔

✔

✔

✔

✔

✔
nv-embed-qa-4

✔

✔
multilingual-e5-large

✔

✔

✔

✔

✔

✔

✔

✔

✔

voyage-multilingual-2

✔

✔

✔

✔

✔

✔

✔

✔

✔

Considérations relatives aux clients

En aperçu, les Cortex Search Services engendrent des coûts selon les détails annoncés dans la Snowflake Service Consumption Table.

Créer un Cortex Agent

Nous allons utiliser les Cortex Agents pour mettre en place une application conversationnelle qui répond aux questions des utilisateurs professionnels concernant les termes d’un contrat. Passons en revue les principaux éléments. (Pour le tutoriel complet, voir Prise en main des Cortex Agents).

Étape 1. Spécifiez les outils que vous souhaitez utiliser dans la requête

{
    "tools": [
        {
            "tool_spec": {
                "name": "data_model",
                "type": "cortex_analyst_text_to_sql"
            }
        },
        {
            "tool_spec": {
                "name": "transcript_search",
                "type": "cortex_search"
            }
        },
        {
            "tool_spec": {
                "type": "sql_exec",
                "name": "sql_exec"
            }
        },
        {
            "tool_spec": {
                "type": "data_to_chart",
                "name": "data_to_chart"
            }
        }
    ]
}
Copy

Étape 2. Fournissez des arguments statiques (ressources) aux outils que le Cortex Agent peut utiliser pour appeler les outils

{
    "tool_resources": {
        "data_model": {
            "semantic_model_file": "@cortex_tutorial_db.public.revenue_semantic_model.yaml"
        },
        "transcript_search": {
            "name": "cortex_tutorial_db.public.contract_terms",
            "max_results": 5,
            "title_column": "TRANSCRIPT_TITLE",
            "id_column": "TRANSCRIPT_ID",
            "filter": {"@eq": {"TRANSCRIPT_TYPE": "ENTERPRISE"} }
        }
    }
}
Copy

Étape 3. Nous allons maintenant spécifier le modèle et l’invite du système pour générer la réponse

{
    "model": "claude-3-5-sonnet",
    "messages": [
        {
            "role": "system",
            "content": {
                "type": "text",
                "text": "You’re a friendly assistant to answer questions."
            }
        }
    ]
}
Copy

Étape 4. Créez un fichier de modélisation sémantique qui sera utilisé par l’outil Analyst pour accéder aux données structurées

Suivez les étapes 1 à 3 de ce guide pour créer un modèle sémantique Cortex Analyst Prise en main des Cortex Agents

Étape 5. Ensuite, nous avons défini un service de recherche pour que l’outil Search accède aux données non structurées

Suivez les étapes 4 et 5 de ce guide pour créer le service Cortex Search Service Prise en main des Cortex Agents

Étape 6. Nous sommes maintenant prêts à interagir avec l’Agent. Vous utiliserez le champ messages pour envoyer des requêtes et recevoir des réponses

{
    "model": "claude-3-5-sonnet",
    "messages": [
        {
            "role": "system",
            "content": [
                {
                    "type": "text",
                    "text": "You’re a friendly assistant to answer questions"
                }
            ]
        },
        {
            "role": "user",
            "content": [
                {
                    "type": "text",
                    "text": "hello"
                }
            ]
        },
        {
            "role": "assistant",
            "content": [
                {
                    "type": "text",
                    "text": "hi there!"
                }
            ]
        },
        {
            "role": "user",
            "content": [
                {
                    "type": "text",
                    "text": "..."
                }
            ]
        }
    ]
}
Copy

Étape 7. Au fur et à mesure de l’interaction, l’Agent identifie les outils et exécute (côté service) pour accomplir la tâche. Dans l’exemple ci-dessous, l’Agent identifie Text2SQL comme l’outil et exécute pour obtenir la requête SQL. Au cours de l’interaction, l’Agent peut demander l’utilisation d’un outil pour l’application client (côté client). Par exemple, l’Agent spécifie la requête SQL qui doit être exécutée.

{
    "role": "assistant",
    "content": [
        {
            "type": "tool_use",
            "tool_use": {
                "tool_use_id": "tool_001",
                "name": "cortex_analyst_text_to_sql",
                "input": {
                    "query": "...",
                    "semantic_model_file": "..."
                }
            }
        },
        {
            "type": "tool_results",
            "tool_results": {
                "status": "success",
                "tool_use_id": "tool_001",
                "content": [
                    {
                        "type": "json",
                        "json": {
                            "sql": "select * from table"
                        }
                    }
                ]
            }
        },
        {
            "type": "tool_use",
            "tool_use": {
                "tool_use_id": "tool_002",
                "name": "sql_exec",
                "input": {
                    "sql": "select * from table"
                }
            }
        }
    ]
}
Copy
Langage: Français