Catégories :: Fonctions de chaîne et fonctions binaires (Fonctions AI)

DATA_AGENT_RUN (SNOWFLAKE.CORTEX)¶

Exécute un Agent Cortex et renvoie la réponse sous la forme JSON.

Vous pouvez utiliser cette fonction pour exécuter un Agent Cortex, qui orchestre les sources de données structurées et non structurées pour fournir des informations. Cela comprend la planification des tâches, l’utilisation des outils pour exécuter ces tâches et la génération des réponses.

Note

SNOWFLAKE.CORTEX.DATA_AGENT_RUN est un utilitaire qui encapsule l’API Cortex Agents Run. Pour la plupart des intégrations d’applications, Snowflake recommande d’appeler directement l’API REST de flux.

Voir aussi :: CREATE AGENT, SHOW AGENTS, DESCRIBE AGENT, DROP AGENT

Syntaxe¶

SNOWFLAKE.CORTEX.DATA_AGENT_RUN( '<agent_name>', <request_body> )

Copy

Arguments¶

'agent_name'

Nom complet de l’agent à exécuter, au format database.schema.agent_name.

request_body

Corps de la requête JSON à envoyer à l’agent. Cette valeur doit être une chaîne (par exemple, un littéral $$...$$).

Les champs suivants sont pris en charge dans le corps de la requête :

Champ	Type	Description
`thread_id`	entier	ID de thread pour la conversation. Si thread_id est utilisé, parent_message_id doit également être transmis.
`parent_message_id`	entier	ID du message parent dans le thread. S’il s’agit du premier message, parent_message_id doit correspondre à 0.
`messages`	tableau d”Message	Si thread_id et parent_message_id sont transmis dans la requête, les messages incluent le message actuel de l’utilisateur dans la conversation. Sinon, les messages comprennent l’historique de la conversation et le message actuel. Les messages contiennent à la fois les requêtes des utilisateurs et les réponses des assistants dans l’ordre chronologique.
`stream`	booléen	Renvoyer une réponse streaming (`texte/flux d’événements`) ou une réponse JSON non-streaming (`application/json`). Si « true », la réponse sera envoyée (stream) en tant qu’événements envoyés par le serveur. Si « false », la réponse sera renvoyée en tant que JSON.
`tool_choice`	ToolChoice	Configure la manière dont l’agent doit sélectionner et utiliser les outils pendant l’interaction. Contrôle si l’utilisation des outils est automatique, obligatoire, ou si des outils spécifiques doivent être utilisés.

Exemple

{
  "thread_id": 0,
  "parent_message_id": 0,
  "messages": [
    {
      "role": "user",
      "content": [
        {
          "type": "text",
          "text": "What is the total revenue for 2023?"
        }
      ]
    }
  ],
  "stream": false,
  "tool_choice": {
    "type": "auto",
    "name": [
      "analyst_tool",
      "search_tool"
    ]
  }
}

Copy

Important

Le champ stream est ignoré. Une réponse sans flux est toujours renvoyée.

Renvoie¶

Renvoie une chaîne JSON contenant la réponse de l’agent.

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

Pour exécuter un agent, vous devez utiliser un rôle qui peut accéder aux Agents Cortex et à l’objet agent que vous appelez. Pour plus de détails, voir Exigences en matière de contrôle d’accès.

Notes sur l’utilisation¶

La fonction renvoie une chaîne JSON. Transmettez cette chaîne à TRY_PARSE_JSON pour convertir la réponse en une valeur VARIANT.

Exemples¶

Exécuter un agent et analyser la réponse JSON :

SELECT
  TRY_PARSE_JSON(
    SNOWFLAKE.CORTEX.DATA_AGENT_RUN(
      'MY_DB.MY_SCHEMA.MY_AGENT',
      $${
        "parent_message_id": 1234,
        "thread_id": 5678,
        "messages": [
          {
            "role": "user",
            "content": [
              { "type": "text", "text": "What are some types of products?" }
            ]
          }
        ]
      }$$
    )
  ) AS resp;

Copy

Exemple de valeur de retour :

{
  "role": "assistant",
  "content": [
    {
      "thinking": {
        "text": "\n...\n"
      },
      "type": "thinking"
    },
    {
      "tool_use": {
        "input": {
          "...": "..."
        },
        "name": "<tool_name>",
        "tool_use_id": "<tool_use_id>",
        "type": "<tool_type>"
      },
      "type": "tool_use"
    },
    {
      "text": "Based on the data available, there are two main types of products...",
      "type": "text"
    }
  ],
  "metadata": {
    "run_id": "<run_id>"
  }
}

Copy