Configurer des agents et interagir avec¶

Créer un agent¶

Créez un objet d’agent en spécifiant la base de données et le schéma dans lesquels l’agent doit être situé, ainsi qu’un nom et une description pour l’agent. De plus, spécifiez son nom d’affichage, son avatar et sa couleur. Ces attributs sont utilisés par l’application cliente pour afficher l’agent. Le nom d’affichage est également utilisé comme identifiant pour faire référence à l’agent dans les conversations.

For best practices when creating an agent, see Best Practices to Building Cortex Agents.

Les exemples suivants montrent comment créer un objet d’agent à partir de Snowsight ou à l’aide de l’API REST :

Method 1: Snowsight UIMethod 2: REST APIMethod 3: SQL

1. Connectez-vous à Snowsight.

2. Dans le menu de navigation, sélectionnez AI & ML » Agents.

3. Sélectionnez Create agent.

4. Pour Agent object name, indiquez un nom pour l’agent qui est affiché aux utilisateurs dans l’UI.

5. Pour Display name, indiquez le nom de l’agent qui est affiché aux administrateurs dans la liste des agents.

6. Sélectionnez Create agent.

7. Invitez l’agent avec des requêtes de connaissances générales.

Ajouter des outils¶

Après avoir créé l’agent, vous devez ajouter des outils et fournir des instructions sur la manière d’orchestrer les outils. Les agents prennent en charge les types d’outils suivants :

• Cortex Analyst : Vous spécifiez les vues sémantiques afin que Cortex Analyst puisse les utiliser pour récupérer des données structurées. Les agents peuvent effectuer des routages sur plusieurs vues sémantiques pour fournir la réponse.

• Cortex Search : Vous fournissez les indices Cortex Search sous forme d’outils, y compris les informations connexes comme les filtres de recherche, les noms de colonnes et les métadonnées. L’Agent Cortex utilise les indices Cortex Search pour récupérer des données non structurées.

• Outils personnalisés : Vous pouvez implémenter le code d’une logique métier spécifique en tant que procédure stockée ou fonction définie par l’utilisateur (UDF). Vous pouvez également utiliser les outils personnalisés pour récupérer des données à partir de vos systèmes backend à l’aide d’APIs.

Vous indiquez également les ressources utilisées par chaque outil. Par exemple, sur Cortex Analyst, vous spécifiez l’entrepôt ainsi que le délai d’attente pour l’exécution de la requête SQL. De la même manière, pour Cortex Search, vous spécifiez les filtres et les noms de colonnes utilisés dans la requête de recherche, ainsi que les résultats maximums dans la réponse de recherche. Pour les outils personnalisés, vous fournirez les détails de l’entrepôt.

Method 1: Snowsight UIMethod 2: REST APIMethod 3: SQL

To modify the configuration for an existing agent, follow these steps:

1. Dans le menu de navigation, sélectionnez AI & ML » Agents.

2. From the list of agents, select the agent that you want to modify.

   The configuration details for the agent are displayed.

3. Sélectionnez Edit.

4. Pour Description, décrivez l’agent et comment les utilisateurs peuvent interagir avec lui.

5. Pour ajouter des exemples de questions que les utilisateurs peuvent poser à l’agent, saisissez un exemple de questions et sélectionnez Add a question.

6. Sélectionnez Tools. Ajoutez un ou plusieurs des outils suivants.

   • Pour ajouter une vue sémantique dans Cortex Analyst à l’agent : Cette section suppose que vous avez déjà créé une vue sémantique. Pour plus d’informations sur les vues sémantiques et sur la manière de les créer, voir Aperçu des vues sémantiques.

     1. Cherchez Cortex Analyst et sélectionnez le bouton:ui:+ Add respectif.

     2. Pour Name, saisissez un nom pour la vue sémantique.

     3. Sélectionnez Semantic view.

     4. Sélectionnez la vue sémantique utilisée par l’agent.

     5. Pour Warehouse, sélectionnez l’entrepôt que l’agent utilise pour exécuter les requêtes.

     6. Pour Query timeout (seconds), indiquez le temps maximal en secondes pendant lequel l’agent attend une requête pour se terminer avant l’expiration du délai.

     7. Pour Description, décrivez la vue sémantique.

     8. Sélectionnez Add.

   • Pour ajouter un service Cortex Search à l’agent : Cette section suppose que vous avez déjà créé un Cortex Search Service. 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. Pour un tutoriel qui utilise une CKE, voir Résolution des problèmes.

     1. Cherchez Cortex Search Services et sélectionnez le bouton:ui:+ Add respectif.

     2. Pour Name, saisissez un nom pour le Cortex Search Service.

     3. Pour Description, décrivez le Cortex Search Service.

     4. Pour Search service, sélectionnez le Cortex Search Service utilisé par l’agent.

     5. Sélectionnez Add.

   • Pour ajouter un outil personnalisé à l’agent : En ajoutant des outils personnalisés, vous pouvez étendre les fonctionnalités de vos agents. Avec les outils personnalisés, l’agent peut appeler des procédures et des fonctions stockées que vous avez définies pour effectuer des actions ou des calculs. Cette section suppose que vous avez déjà créé un outil personnalisé. Pour des informations sur les procédures et les fonctions, voir Extension de Snowflake avec des fonctions et des procédures.

     1. Cherchez Custom tools et sélectionnez le bouton:ui:+ Add respectif.

     2. Pour Name, saisissez un nom pour l’outil personnalisé.

     3. Pour Resource type, sélectionnez si l’outil personnalisé est une fonction ou une procédure. Pour plus d’informations sur l’utilisation d’une fonction ou d’une procédure, voir Choisir d’écrire une procédure stockée ou une fonction définie par l’utilisateur.

     4. Pour Custom tool identifier, sélectionnez la fonction existante ou la procédure que vous souhaitez ajouter comme outil personnalisé.

     5. Les paramètres relatifs à la fonction ou à la procédure apparaissent automatiquement. Vous pouvez ajouter manuellement des paramètres pour l’outil personnalisé en ajoutant un nom, un type, une description et en indiquant si le paramètre est obligatoire. Vous pouvez également modifier les paramètres qui sont automatiquement renseignés.

        Note

        Snowflake Cortex ne prend pas en charge les procédures stockées et les outils personnalisés avec un paramètre de type object.

     6. Pour Warehouse, sélectionnez l’entrepôt que l’agent utilise pour exécuter l’outil personnalisé. Vous devez sélectionner manuellement un entrepôt.

     7. Pour Description, décrivez l’outil personnalisé et comment l’utiliser.

     8. Sélectionnez Add.

     9. Après avoir créé l’outil personnalisé, assurez-vous que les utilisateurs disposent des privilèges USAGE pour la fonction ou la procédure que vous avez ajoutée en tant qu’outil personnalisé. Lorsque vous utilisez des procédures stockées, les agents déterminent si la procédure s’exécute avec les droits du propriétaire ou ceux de l’appelant. Pour plus d’informations sur les droits du propriétaire et de l’appelant, voir Présentation des procédures stockées des droits de l’appelant et des droits du propriétaire.

7. Sélectionnez Save.

Spécifier l’orchestration¶

Les Agents Cortex orchestrent la tâche en la divisant en une séquence de sous-tâches et en identifiant l’outil approprié pour chaque sous-tâche. Vous spécifiez le LLM que l’agent doit utiliser pour effectuer cette orchestration. Vous pouvez également influencer l’orchestration en fournissant des instructions. Prenons l’exemple d’un agent conçu pour répondre à des questions sur des produits vendus au détail. Vous pouvez utiliser l’instruction d’orchestration "Use the search tool for all requests related to refunds" pour vous assurer que l’agent ne fournit que des détails sur la politique de remboursement (à l’aide de Cortex Search) et ne calcule pas réellement le montant des remboursement (à l’aide de Cortex Analyst). Vous pouvez également spécifier des instructions pour aligner la réponse sur une forme ou une tonalité, comme "Always provide provide a concise response; maintain a friendly tone".

Configurer l’accès à l’agent¶

GRANT USAGE ON AGENT <database_name>.<schema_name>.<agent_name> TO ROLE <role_name>;

Configurez des politiques d‘accès depuis l’UI de Snowsight ou à l’aide de SQL pour que les utilisateurs puissent accéder à l’agent. Spécifiez le rôle permettant d’accéder à l’agent.

GRANT USAGE ON AGENT myagent TO ROLE test_rl;

Examiner l’agent¶

Après avoir créé l’agent, vous pouvez l’examiner pour vérifier tous les paramètres.

Tester l’agent¶

Après avoir créé l’agent, vous pouvez le tester pour voir comment il répond aux requêtes des utilisateurs. Vous pouvez également tester l’agent à l’aide de l’Requête d’exécution d’agent avec objet d’agent.

Pour tester l’agent, suivez les étapes suivantes :

1. Connectez-vous à Snowsight.

2. Dans le menu de navigation, sélectionnez AI & ML » Agents.

3. Sélectionnez l’agent dans la liste des agents.

4. Sur la page des détails de l’agent, saisissez une requête dans le playground de l’agent.

5. Vérifiez que l’agent répond à la requête comme attendu. Si l’agent ne répond pas comme attendu, modifiez la configuration de l’agent en suivant les étapes à la section Ajouter des outils.

Interagir avec l’agent¶

Après avoir créé l’objet d’agent, vous pouvez intégrer l’agent directement dans votre application à l’aide de l’API REST. Pour maintenir le contexte lors de l’interaction, utilisez un thread. La combinaison de l’objet d’agent et du thread simplifie le code de l’application cliente.

curl -X POST "$SNOWFLAKE_ACCOUNT_BASE_URL/api/v2/cortex/threads" \
--header 'Content-Type: application/json' \
--header 'Accept: application/json' \
--header "Authorization: Bearer $PAT" \
--data '{
    "origin_application": <application_name>,
}'

curl -X POST "$SNOWFLAKE_ACCOUNT_BASE_URL/api/v2/databases/{database}/schemas/{schema}/agents/{name}:run" \
 --header 'Content-Type: application/json' \
 --header 'Accept: application/json' \
 --header "Authorization: Bearer $PAT" \
 --data '{
     "thread_id": <thread id for context>,
     "parent_message_id": <parent message id>,
     "messages": [
      {
         "role": "user",
         "content": [
           {
            "type": "text",
             "text": "What are the projected transportation costs for the next three quarters? "
             }
         ]
       }
     ],
     "tool_choice": {
       "type": "required",
       "name": [
         "Analyst1",
         "Search1"
       ]
     }
 }'

Recueillir des commentaires sur l’agent¶

Vous pouvez recueillir les commentaires des utilisateurs sur les réponses données par l’agent. Ces commentaires peuvent vous aider à affiner l’agent au fur et à mesure que vous itérez sur votre cas d’utilisation. Les utilisateurs peuvent fournir une évaluation objective (positive ou négative), ainsi que des détails plus subjectifs dans un message. Les utilisateurs peuvent également catégoriser les commentaires dans l’une des nombreuses catégories.

curl -X POST "$SNOWFLAKE_ACCOUNT_BASE_URL/api/v2/databases/<database-name>/schemas/<schema-name>/agents/<agent-name>:feedback:" \
--header 'Content-Type: application/json' \
--header 'Accept: application/json' \
--header "Authorization: Bearer $PAT" \
--data '{
    "request_id": "<request-id>",
    "positive": true
    "feedback_message": "This answer was great",
    "categories":[
        "category1", "category2", "category3"
    ],
    "thread_id": "<thread-id>"
}'

Interagir sans objet d’agent¶

Dans certains cas, vous souhaiterez peut-être commencer à utiliser des Agents Cortex en utilisant l’agent:run sans objet d’agent. Par exemple, cela peut être utile lorsque vous souhaitez tester rapidement un cas d’utilisation. Pour plus d’informations sur l’API REST, consultez Exécution d’agent sans objet d’agent.