Créer des agents¶

Structure des agents¶

Un agent se compose des éléments suivants :

• Le modèle de base qui fournit les bases du comportement de l’agent

• Un modèle (l’orchestrateur) qui interprète l’intention, sélectionne les bons outils et planifie la séquence des actions

• Instructions relatives au comportement de l’agent

• Outils à utiliser par l’agent

• Ressources pour les outils

Les sections suivantes fournissent des informations sur la sélection de modèles et la configuration des outils. Cet exemple utilise une vue sémantique, un service Cortex Search et un outil personnalisé pour fournir des réponses. Bien que vous puissiez créer un agent de base qui n’utilise aucun de ces outils, cet agent ne peut s’appuyer que sur le modèle de base pour fournir des réponses. Par conséquent, l’agent n’a pas accès aux données de votre compte Snowflake et dispose d’un contexte limité pour les réponses.

Pour plus d’informations sur les autres composants de l’agent, voir Cortex Agents.

Conditions préalables¶

Pour créer un Agent Cortex, vous devez utiliser un rôle disposant des privilèges suivants :

Le code suivant accorde les privilèges nécessaires pour créer un Agent Cortex :

GRANT USAGE ON DATABASE <database_name> to ROLE <role_name>;
GRANT USAGE ON SCHEMA <database_name>.<schema_name> to ROLE <role_name>;
GRANT CREATE AGENT ON SCHEMA <database_name>.<schema_name> to ROLE <role_name>;

Copy

Outre les privilèges requis pour créer un Agent Cortex, les conditions préalables suivantes sont nécessaires pour connecter l’agent à des outils spécifiques :

• Une vue sémantique pour se connecter à l’agent

  Pour plus d’informations sur la création d’une vue sémantique, voir Aperçu des vues sémantiques.

• Un outil Cortex Analyst pour se connecter à l’agent

  Pour plus d’informations sur la création d’un outil Cortex Analyst, voir Cortex Analyst.

• Données non structurées dans une base de données pour se connecter à l’agent

• Un outil Cortex Search pour se connecter à l’agent

  Pour plus d’informations sur la création d’un outil Cortex Search, voir Cortex Search.

• Un outil personnalisé pour se connecter à l’agent

  Pour plus d’informations sur la création de fonctions définies par l’utilisateur (UDFs) et des procédures stockées à utiliser comme outils personnalisés, voir Extension de Snowflake avec des fonctions et des procédures.

Pour associer des outils à un agent, le rôle utilisé pour créer l’agent doit disposer des privilèges suivants :

Bases de la configuration de l’agent¶

Lorsque vous créez un agent, vous devez spécifier des informations sur l’agent, telles que le nom, la description et le modèle. Vous pouvez également spécifier les outils que l’agent peut utiliser et les ressources auxquelles l’agent peut accéder. Ces ressources sont transmises en tant que spécification YAML dans la clause FROM SPECIFICATION de la commande CREATE AGENT.

Les recommandations suivantes fournissent les bonnes pratiques relatives à cette configuration :

Définissez clairement le champ d’application de l’agent : avant d’ajouter des outils ou de rédiger des instructions, déterminez pourquoi l’agent existe, à qui il s’adresse et à quelles questions spécifiques il doit répondre. Cette étape conditionne tout ce qui suit, du choix des outils à la performance et à la confiance. Snowflake vous recommande de limiter la champ d’application de l’agent à un cas d’utilisation spécifique et à forte valeur ajoutée.

Une fois qu’un agent s’avère fiable dans un domaine, vous pouvez reproduire le modèle pour d’autres. Par exemple, vous pouvez avoir un agent pour analyser les données récentes de ventes et de marketing de votre magasin, et un autre qui recommande les meilleures SKUs à présenter au détaillant.

Sélectionnez soigneusement le nombre d’outils : chaque agent doit avoir accès uniquement aux outils dont il a besoin. Pour déterminer cela, il faut tenir compte des documents ou des données dont l’agent a besoin pour atteindre son objectif. Si l’agent doit accéder à des données non structurées, utilisez Cortex Search. Si l’agent doit accéder à des données structurées, utilisez Cortex Analyst. Si l’agent a besoin d’autres outils, vous pouvez utiliser des outils personnalisés.

Rédigez une description utile de l’outil : ces descriptions sont utilisées pour aider l’agent à comprendre ce que fait l’outil et comment l’utiliser. Des descriptions d’outils imprécises peuvent entraîner des défaillances en chaîne et provoquer des « hallucinations ».

Pour créer une description d’outil utile, suivez les instructions suivantes :

• Ajoutez un nom d’outil clair et spécifique qui précise le domaine de l’outil (« Client », « Ventes ») et la fonction (« Analyses », « Recherche »).

• Rédigez une description d’outil spécifique qui indique à l’agent :

  • Ce que fait l’outil

  • À quelles données il accède

  • Quand l’utiliser

  • Quand ne pas (NOT) l’utiliser ?

• Soyez explicite quant aux entrées attendues de l’outil. Des entrées ambiguës dans vos outils entraînent des appels d’outils incorrects et des erreurs.

  • Soyez précis.

  • Spécifiez le format de données.

  • Donnez des instructions claires sur les données.

  • Fournissez des recommandations par défaut.

  • Utilisez une terminologie cohérente.

Pour plus de recommandations sur la configuration des agents, voir `Bonnes pratiques pour la création d’Agents Cortex<https://www.snowflake.com/en/developers/guides/best-practices-to-building-cortex-agents/>`_.

Sélection de modèles¶

Lorsque vous créez un agent, nous vous recommandons de sélectionner auto pour le modèle. Avec cette option, Cortex sélectionne automatiquement le modèle de la meilleure qualité pour votre compte. La qualité s’améliore automatiquement à mesure que de nouveaux modèles deviennent disponibles. Pour plus d’informations sur les modèles disponibles, voir Modèles et régions pris en charge.

L’exemple suivant montre comment spécifier le modèle pour l’agent :

models:
  orchestration: auto

ALTER ACCOUNT SET CORTEX_ENABLED_CROSS_REGION = 'ANY_REGION';

Connecter les vues sémantiques à l’aide de Cortex Analyst (données structurées)¶

Snowflake Intelligence prend en charge les vues sémantiques, qui sont un type de données structurées avec des instructions indiquant à l’agent comment interroger ou interpréter les données. Les Agents Cortex utilisent Cortex Analyst pour récupérer des données structurées à partir de vues sémantiques en convertissant les requêtes en langage naturel en requêtes SQL. Les agents peuvent effectuer des routages sur plusieurs vues sémantiques pour fournir la réponse.

Chaque vue sémantique doit couvrir un ensemble similaire de tables. Vous pouvez définir des paramètres par défaut spécifiques aux données, par exemple en ajoutant systématiquement un filtre de date couvrant les trois derniers mois si aucune date n’est précisée, ou en excluant systématiquement les comptes internes.

Vous pouvez connecter une vue sémantique à un agent en spécifiant la vue sémantique dans les ressources de l’outil. L’exemple suivant montre comment connecter une vue sémantique à un agent et comment spécifier l’outil Cortex Analyst pour récupérer les données structurées de la vue sémantique :

tools:
  - tool_spec:
      type: "cortex_analyst_text_to_sql"
      name: "<your cortex analyst tool name>"
      description: "<clear and specific tool description>"

tool_resources:
  <your cortex analyst tool name>:
    semantic_view: "<db>.<schema>.<semantic_view>"

Connecter Cortex Search (données non structurées)¶

Pour traiter des données non structurées, vous pouvez connecter un outil Cortex Search à un agent en spécifiant l’outil Cortex Search dans la spécification YAML dans le cadre des ressources de l’outil. Les services Cortex Search récupèrent des documents et des enregistrements dans des sources de données non structurées à l’aide de la recherche sémantique. Les deux principaux cas d’utilisation de Cortex Search sont la génération augmentée par récupération (RAG) et la recherche en entreprise. Pour plus d’informations sur la création d’un Cortex Search Service, voir Cortex Search. Vous pouvez également utiliser une Cortex Knowledge Extension (CKE) qui est partagée avec vous.

Lorsque vous connectez un outil Cortex Search à un agent, il est particulièrement important d’inclure les informations suivantes sur les paramètres et leurs valeurs attendues :

• Type et format (avec des exemples)

• Si obligatoire ou facultatif (avec valeurs par défaut).

• Valeurs ou contraintes valides (énumérations, plages, formats)

• Relation avec d’autres paramètres (dépendances, conflits)

• Comment obtenir la valeur (en particulier pour les IDs)

L’exemple suivant montre comment connecter un outil Cortex Search à un agent et comment spécifier l’outil Cortex Search dans la spécification YAML :

tools:
  - tool_spec:
      type: "cortex_search"
      name: "<your cortex search tool name>"
      description: "<clear and specific tool description>"

tool_resources:
  <your cortex search tool name>:
    name: "<db>.<schema>.<search_service_name>"
    max_results: "5"
    filter:
      "@eq":
        region: "North America"
    title_column: "<title_name>"
    id_column: "<column_name>"

Ajouter des outils personnalisés¶

Snowflake Intelligence prend en charge les outils personnalisés, qui sont des fonctions définies par l’utilisateur ou des procédures stockées pouvant être utilisées pour mettre en œuvre une logique métier personnalisée. Vous pouvez connecter un outil personnalisé à un agent en spécifiant l’outil personnalisé dans la spécification YAML dans le cadre des ressources de l’outil.

L’exemple suivant montre comment connecter un outil personnalisé à un agent et comment spécifier l’outil personnalisé dans la spécification YAML :

tools:
  - tool_spec:
      type: "custom_tool"
      name: "<your custom tool name>"
      description: "<clear and specific tool description>"

tool_resources:
  <your custom tool name>:
    user-defined-function-argument: "argument1"

Créer un agent¶

• Combiner tous les outils et composants pour créer un agent à l’aide de SQL :

  CREATE OR REPLACE AGENT <agent_name>
      COMMENT = 'agent level comment'
      PROFILE = '{"display_name": "My Business Assistant", "avatar":  "business-icon.png", "color": "blue"}'
      FROM SPECIFICATION
      $$
      models:
      orchestration: claude-4-sonnet
  
      orchestration:
      budget:
          seconds: 30
          tokens: 16000
  
      instructions:
      response: "You will respond in a friendly but concise manner"
      orchestration: "For any revenue question, use Analyst; for policy questions, use Search"
      system: "You are a friendly agent that helps with business questions"
      sample_questions:
          - question: "What was our revenue last quarter?"
          answer: "I'll analyze the revenue data using our financial database."
  
      tools:
      - tool_spec:
          type: "cortex_analyst_text_to_sql"
          name: "<your cortex analyst tool name>"
          description: "<clear and specific tool description>"
      - tool_spec:
          type: "cortex_search"
          name: "<your cortex search tool name>"
          description: "<clear and specific tool description>"
      - tool_spec:
          type: "data_to_chart"
          name: "data_to_chart"
          description: "Generates visualizations from data"
  
      tool_resources:
      <your cortex analyst tool name>:
          semantic_view: "<db>.<schema>.<semantic_view>"
      <your cortex search tool name>:
          name: "<db>.<schema>.<search_service_name>"
          max_results: "5"
          filter:
          "@eq":
              region: "North America"
          title_column: "<title_name>"
          id_column: "<column_name>"
      $$;
  

  Copy

Modification d’un agent existant¶

Pour obtenir des instructions sur la modification de la configuration d’un agent existant, y compris l’ajout d’outils et la mise à jour d’autres détails, voir Ajouter des outils.