API d’exécution des Agents Cortex¶

Il existe deux méthodes pour interagir avec un agent :

Créer un objet d’agent et référencer cet objet d’agent dans une requête adressée à l’API agent:run.
Appeler agent:run directement, sans objet d’agent. Vous fournissez la configuration dans le corps de requête de agent:run.

Ces deux méthodes utilisent des APIs de diffusion qui répondent avec les événements envoyés par le serveur spécifiés sous Streaming Responses.

Requête d’exécution d’agent avec objet d’agent¶

POST /api/v2/databases/{database}/schemas/{schema}/agents/{name}:run

Envoie une requête utilisateur à l’objet d’agent et renvoie sa réponse sous forme de flux d’événements.

Paramètres de chemin¶

Paramètre	Description
`database`	(Obligatoire) Base de données contenant l’agent. Vous pouvez utiliser la requête GET `/api/v2/databases` pour obtenir une liste des bases de données disponibles.
`schema`	(Obligatoire) Schéma contenant l’agent. Vous pouvez utiliser la requête GET `/api/v2/databases/{database}/schemas` pour obtenir une liste des schémas disponibles pour la base de données spécifiée.
`name`	(Obligatoire) Nom de l’agent.

En-têtes de requête¶

En-tête	Description
`Authorization`	(Obligatoire) Jeton d’autorisation. Voir Authentification.
`Content-Type`	(Obligatoire) application/json

Corps de 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.
`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?"
        }
      ]
    }
  ],
  "tool_choice": {
    "type": "auto",
    "name": [
      "analyst_tool",
      "search_tool"
    ]
  }
}

Copy

Exécution d’agent sans objet d’agent¶

POST /api/v2/cortex/agent:run

Envoie une requête utilisateur au service d’Agents Cortex fourni dans le corps de requête et renvoie sa réponse. Interagit avec l’agent sans créer d’objet d’agent.

Note

Avant le 1er septembre 2025, les schémas de requête et de réponse pour l’API agent:run étaient différents du schéma listé dans ce document. Auparavant, l’orchestration était statique et la même séquence d’outils était utilisée pour générer une réponse. agent:run dispose désormais d’un schéma mis à jour pour la requête et la réponse. En outre, l’API orchestre et itère désormais dynamiquement pour parvenir à la réponse finale. Nous recommandons d’utiliser le schéma décrit dans ce document pour améliorer l’expérience de l’utilisateur final.

Pour utiliser le schéma et le comportement hérités, utilisez le schéma suivant :

{
  "model": "claude-4-sonnet",
  "messages": [
     {"role":"user", "content": [] }
  ]
}

Copy

En-têtes de requête¶

En-tête	Description
`Authorization`	(Obligatoire) Jeton d’autorisation. Voir Authentification.
`Content-Type`	(Obligatoire) application/json

Corps de 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.
`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.
`models`	ModelConfig	Configuration du modèle pour l’agent. Inclut le modèle d’orchestration (par exemple, claude-4-sonnet). S’il n’est pas fourni, un modèle est automatiquement sélectionné. Actuellement disponible uniquement pour l’étape d’`orchestration`.
`instructions`	AgentInstructions	Instructions relatives au comportement de l’agent, y compris la réponse, l’orchestration, le système et les exemples de questions.
`orchestration`	OrchestrationConfig	Configuration de l’orchestration, y compris les contraintes budgétaires (par exemple, secondes, jetons).
`tools`	tableau d”Tool	Liste des outils disponibles pour l’agent à utiliser. Chaque outil inclut une tool_spec avec un type, un nom, une description et un schéma d’entrée. Les outils peuvent avoir une configuration correspondante dans tool_resources.
`tool_resources`	carte de ToolResource	Configuration pour chaque outil référencé dans le tableau des outils. Les clés doivent correspondre au nom de l’outil correspondant.

Exemple

{
  "thread_id": 0,
  "parent_message_id": 0,
  "messages": [
    {
      "role": "user",
      "content": [
        {
          "type": "text",
          "text": "What is the total revenue for 2023?"
        }
      ]
    }
  ],
  "tool_choice": {
    "type": "auto",
    "name": [
      "analyst_tool",
      "search_tool"
    ]
  },
  "models": {
    "orchestration": "claude-4-sonnet"
  },
  "instructions": {
    "response": "You will respond in a friendly but concise manner",
    "orchestration": "For any query related to revenue we should use Analyst; For all policy questions we should use Search",
    "system": "You are a friendly agent ..."
  },
  "orchestration": {
    "budget": {
      "seconds": 30,
      "tokens": 16000
    }
  },
  "tools": [
    {
      "tool_spec": {
        "type": "generic",
        "name": "get_revenue",
        "description": "Fetch the delivery revenue for a location.",
        "input_schema": {
          "type": "object",
          "properties": {
            "location": {
              "type": "string",
              "description": "The city and state, e.g. San Francisco, CA"
            }
          }
        },
        "required": [
          "location"
        ]
      }
    }
  ],
  "tool_resources": {
    "get_revenue": {
      "type": "function",
      "execution_environment": {
        "type": "warehouse",
        "warehouse": "MY_WH"
      },
      "identifier": "DB.SCHEMA.UDF"
    }
  }
}

Copy

Réponses en continu¶

L’API agent:run fournit des réponses en continu. Le serveur renvoie les événements. Cela vous permet d’afficher les réponses dans votre application, jeton par jeton, à mesure qu’elles sont générées par l’agent. Chaque événement diffusé dans la réponse de l’API possède un schéma strictement typé. Vous pouvez trouver une liste de tous les événements dans la section suivante et sélectionner ceux auxquels vous souhaitez vous abonner.

Le dernier événement envoyé par l’API est un événement response. Cet événement contient la totalité de la sortie de l’agent. Vous pouvez l’utiliser comme réponse finale de l’agent. Pour tous les clients hors diffusion, vous pouvez vous abonner à cet événement, car il s’agit de l’agrégation logique de tous les événements précédents. Si vous ne voulez pas utiliser les réponses en continu, attendez l’événement response et ignorez tous les événements précédents.

La majorité des autres événements diffusés peuvent être répartis en deux catégories : Delta et Éléments de contenu.

Les événements Delta représentent un jeton unique généré par l’agent. En écoutant ces événements, vous pouvez créer un effet de type machine à écrire. Les principaux événements Delta sont response.thinking.delta, qui représente un jeton de raisonnement, et response.text.delta, qui représente un jeton de réponse.

Les événements Éléments de contenu représentent des éléments du tableau de contenu dans la réponse finale de l’agent.

Note

Assurez-vous que votre application peut gérer des types d’événements inconnus.

Exemple de réponse

event: response.status
data: {"message":"Planning the next steps","status":"planning"}

event: response.thinking.delta
data: {"content_index":0,"text":"\nThe user is asking for a"}

event: response.thinking.delta
data: {"content_index":0,"text":" chart showing the"}

...
...
...

event: response.status
data: {"message":"Reviewing the results","status":"reasoning_agent_stop"}

event: response.status
data: {"message":"Forming the answer","status":"proceeding_to_answer"}

Copy

`response`¶

Événement diffusé lorsque la réponse finale est disponible. Il s’agit du dernier événement émis, qui représente l’agrégation de tous les autres événements précédemment diffusés.

Champ	Type	Description
`role`	string	Rôle du message. Correspond toujours à `assistant` dans la réponse d’API.
`content`	tableau d”MessageContentItem	Contenu généré par l’agent.

Exemple

{
  "role": "assistant",
  "content": [
    {
      "type": "chart",
      "chart": {
        "tool_use_id": "toolu_123",
        "chart_spec": "{\"$schema\":\"https://vega.github.io/schema/vega-lite/v5.json\",\"data\":{...},\"mark\":\"bar\"}"
      }
    }
  ]
}

Copy

`response.text`¶

Événement diffusé lorsqu’un bloc de contenu textuel a fini d’être diffusé, y compris tous les deltas agrégés pour un index de contenu particulier.

Champ	Type	Description
`content_index`	entier	Index dans le tableau de contenu de la réponse que cet événement représente.
`text`	string	Résultat textuel provenant de l’agent.
`annotations`	tableau d”Annotation	Toute annotation jointe au résultat textuel (par exemple, des citations).
`is_elicitation`	booléen	Indique si ce contenu textuel correspond à une demande d’informations supplémentaires de la part de l’agent adressée à l’utilisateur final.

Exemple

{
  "content_index": 0,
  "text": "Lorem ipsum dolor...",
  "annotations": [
    {
      "type": "cortex_search_citation",
      "index": 0,
      "search_result_id": "cs_61987ff6-6d56-4695-83c0-1e7cfed818c7",
      "doc_id": "4ac085cb-82d0-4eb4-94f3-2672aa0599a2",
      "doc_title": "Earnings Report",
      "text": "The revenue for 2025 was..."
    }
  ],
  "is_elicitation": false
}

Copy

`response.text.delta`¶

Événement diffusé lorsqu’un nouveau delta de texte de sortie est généré.

Champ	Type	Description
`content_index`	entier	Index dans le tableau de contenu de la réponse que cet événement représente.
`text`	string	Delta de texte.
`is_elicitation`	booléen	Indique si ce contenu textuel correspond à une demande d’informations supplémentaires de la part de l’agent adressée à l’utilisateur final.

Exemple

{
  "content_index": 0,
  "text": "Hello",
  "is_elicitation": false
}

Copy

`response.text.annotation`¶

Événement diffusé lorsqu’une annotation est ajoutée à un contenu textuel.

Champ	Type	Description
`content_index`	entier	Index dans le tableau de contenu de la réponse que cet événement représente.
`annotation_index`	entier	Index dans le tableau d’annotations auquel cette `annotation` appartient.
`annotation`	Annotation	Objet d’annotation en cours d’ajout.

Exemple

{
  "content_index": 0,
  "annotation_index": 0,
  "annotation": {
    "type": "cortex_search_citation",
    "index": 0,
    "search_result_id": "cs_61987ff6-6d56-4695-83c0-1e7cfed818c7",
    "doc_id": "4ac085cb-82d0-4eb4-94f3-2672aa0599a2",
    "doc_title": "Earnings Report",
    "text": "The revenue for 2025 was..."
  }
}

Copy

`response.thinking`¶

Événement diffusé lorsqu’un bloc de contenu de réflexion a fini d’être diffusé, y compris tous les deltas agrégés pour un index de contenu particulier.

Champ	Type	Description
`content_index`	entier	Index dans le tableau de contenu de la réponse que cet événement représente.
`text`	string	Jetons de réflexion de l’agent.

Exemple

{
  "content_index": 0,
  "text": "To answer your question I must..."
}

Copy

`response.thinking.delta`¶

Événement diffusé lorsqu’un delta de réflexion est généré.

Champ	Type	Description
`content_index`	entier	Index dans le tableau de contenu de la réponse que cet événement représente.
`text`	string	Jeton de réflexion.

Exemple

{
  "content_index": 0,
  "text": "lorem ipsum"
}

Copy

`response.tool_use`¶

Événement diffusé lorsque l’agent requiert l’utilisation d’un outil.

Champ	Type	Description
`content_index`	entier	Index dans le tableau de contenu de la réponse que cet événement représente.
`tool_use_id`	string	Identificateur unique pour cette utilisation d’outil. Peut être utilisé pour associer les résultats de l’outil.
`type`	string	Type de l’outil (par exemple, cortex_search ou cortex_analyst_text2sql).
`name`	string	Identificateur unique de cette instance d’outil.
`input`	objet	Entrée structurée de cet outil. Le schéma de cet objet devrait varier en fonction de la spécification de l’outil.
`client_side_execute`	booléen	Indique si l’utilisation de l’outil est exécutée du côté du client.

Exemple

{
  "content_index": 0,
  "tool_use_id": "toolu_123",
  "type": "cortex_analyst_text2sql",
  "name": "my_cortex_analyst_semantic_view",
  "input": {
    "location": "San Francisco, CA"
  },
  "client_side_execute": "true"
}

Copy

`response.tool_result`¶

Événement diffusé lorsqu’un outil termine de s’exécuter, y compris le résultat de l’outil.

Champ	Type	Description
`content_index`	entier	Index dans le tableau de contenu de la réponse que cet événement représente.
`tool_use_id`	string	Identificateur unique pour cette utilisation d’outil. Peut être utilisé pour associer les résultats de l’outil.
`type`	string	Type de l’outil (par exemple, cortex_search ou cortex_analyst_text2sql).
`name`	string	Identificateur unique de cette instance d’outil.
`content`	tableau d”ToolResultContent	Contenu du résultat de l’outil.
`status`	string	État d’exécution de l’outil.

Exemple

{
  "content_index": 0,
  "tool_use_id": "toolu_123",
  "type": "cortex_analyst_text2sql",
  "name": "my_cortex_analyst_semantic_view",
  "content": [
    {
      "type": "json",
      "json": {
        "answer": 42
      }
    }
  ],
  "status": "success"
}

Copy

`response.tool_result.status`¶

Mise à jour de l’état pour une utilisation spécifique de l’outil.

Champ	Type	Description
`tool_use_id`	string	Identificateur unique pour cette utilisation d’outil.
`tool_type`	string	Type de l’outil (par exemple, cortex_search ou cortex_analyst_text2sql).
`status`	string	Énumération pour l’état actuel.
`message`	string	Message plus descriptif expliquant l’état actuel.

Exemple

{
  "tool_use_id": "toolu_123",
  "tool_type": "cortex_analyst_text2sql",
  "status": "Executing SQL",
  "message": "Executing query 'SELECT * FROM my_table'"
}

Copy

`response.tool_result.analyst.delta`¶

Événement delta diffusé pour l’exécution de l’outil Cortex Analyst.

Champ	Type	Description
`content_index`	entier	Index dans le tableau de contenu de la réponse que cet événement représente.
`tool_use_id`	string	Identificateur unique pour cette utilisation d’outil. Peut être utilisé pour associer les résultats de l’outil.
`tool_type`	string	Type de l’outil (toujours cortex_analyst_text2sql pour cet événement).
`tool_name`	string	Identificateur unique de cette instance d’outil.
`delta`	CortexAnalystToolResultDelta	Delta de contenu.

Exemple

{
  "content_index": 0,
  "tool_use_id": "toolu_123",
  "tool_type": "cortex_analyst_text2sql",
  "tool_name": "my_cortex_analyst_semantic_view",
  "delta": {
    "text": "The...",
    "think": "Thinking...",
    "sql": "SELECT...",
    "sql_explanation": "This...",
    "query_id": "707787a0-a684-4ead-adb0-3c3b62b043d9",
    "verified_query_used": false,
    "result_set": {
      "statementHandle": "707787a0-a684-4ead-adb0-3c3b62b043d9",
      "resultSetMetaData": {
        "partition": 0,
        "numRows": 0,
        "format": "jsonv2",
        "rowType": [
          {
            "name": "my_column",
            "type": "VARCHAR",
            "length": 0,
            "precision": 0,
            "scale": 0,
            "nullable": false
          }
        ]
      },
      "data": [
        [
          "row1 col1",
          "row1 col2"
        ],
        [
          "row2 col1",
          "row2 col2"
        ]
      ]
    },
    "suggestions": {
      "index": 0,
      "delta": "What..."
    }
  }
}

Copy

`response.table`¶

Événement diffusé lorsqu’un bloc de contenu de table est ajouté.

Champ	Type	Description
`content_index`	entier	Index dans le tableau de contenu de la réponse que cet événement représente.
`tool_use_id`	string	ID de l’utilisation d’outil qui a généré cette table.
`query_id`	string	Identifiant de requête de la requête SQL qui a généré ces données.
`result_set`	ResultSet	Résultats SQL pour afficher une table. Correspond au schéma du ResultSet de l’API SQL de Snowflake (https://docs.snowflake.com/fr/developer-guide/sql-api/reference#resultset).
`title`	string	Titre de cette table.

Exemple

{
  "content_index": 0,
  "tool_use_id": "toolu_123",
  "query_id": "6ac75378-6337-48a6-80ab-6de48dd680eb",
  "result_set": {
    "statementHandle": "707787a0-a684-4ead-adb0-3c3b62b043d9",
    "resultSetMetaData": {
      "partition": 0,
      "numRows": 0,
      "format": "jsonv2",
      "rowType": [
        {
          "name": "my_column",
          "type": "VARCHAR",
          "length": 0,
          "precision": 0,
          "scale": 0,
          "nullable": false
        }
      ]
    },
    "data": [
      [
        "row1 col1",
        "row1 col2"
      ],
      [
        "row2 col1",
        "row2 col2"
      ]
    ]
  },
  "title": "Revenue by Month"
}

Copy

`response.chart`¶

Événement diffusé lorsqu’un bloc de contenu graphique est ajouté.

Champ	Type	Description
`content_index`	entier	Index dans le tableau de contenu de la réponse que cet événement représente.
`tool_use_id`	string	ID de l’utilisation d’outil qui a généré ce graphique.
`chart_spec`	string	Spécification du graphique vega-lite sérialisée en tant que chaîne.

Exemple

{
  "content_index": 0,
  "tool_use_id": "toolu_123",
  "chart_spec": "{\"$schema\":\"https://vega.github.io/schema/vega-lite/v5.json\",\"data\":{...},\"mark\":\"bar\"}"
}

Copy

`response.status`¶

Mise à jour de l’état pour l’exécution de l’agent.

Champ	Type	Description
`status`	string	Énumération pour l’état actuel.
`message`	string	Message plus descriptif expliquant l’état actuel.

Exemple

{
  "status": "executing_tool",
  "message": "Executing tool `my_analyst_tool`"
}

Copy

`error`¶

Envoyé lorsqu’une erreur fatale est rencontrée.

Champ	Type	Description
`code`	string	Code d’erreur de Snowflake.
`message`	string	Message d’erreur.
`request_id`	string	Identificateur unique de la requête.

Exemple

{
  "code": "399504",
  "message": "Error during execution",
  "request_id": "61987ff6-6d56-4695-83c0-1e7cfed818c7"
}

Copy

Événement `metadata`¶

Métadonnées de la requête. Cet événement est envoyé lorsqu’un message est ajouté au thread. Il est utile pour obtenir le parent_message_id à utiliser dans les requêtes suivantes adressées à l’API d’agents.

Champ	Type	Description
`role`	string	Identifie qui a envoyé le message : soit l’utilisateur, soit l’assistant.
`message_id`	entier	ID du message du thread. Utilisez cet ID (lorsque le rôle est `assistant`) pour poser une question de suivi sur le thread.

Exemple

{
  "role": "user",
  "message_id": 0
}

Copy

Schémas¶

`AgentInstructions`¶

Champ	Type	Description
`response`	string	Instructions pour la génération de la réponse.
`orchestration`	string	Ces instructions personnalisées sont utilisées lorsque l’agent planifie les outils à utiliser.
`system`	string	Instructions système pour l’agent.

Exemple

{
  "response": "You will respond in a friendly but concise manner",
  "orchestration": "For any query related to revenue we should use Analyst; For all policy questions we should use Search",
  "system": "You are a friendly agent ..."
}

Copy

`Annotation`¶

Champ

Type

Description

type

string

Type de citation (toujours cortex_search_citation).

index

entier

Index de la citation dans les résultats de la recherche.

search_result_id

string

Identificateur unique du résultat de la recherche.

doc_id

string

Identificateur unique du document.

doc_title

string

Le titre du document.

text

string

Extrait textuel du document utilisé comme citation.

Exemple
{
  "type": "cortex_search_citation",
  "index": 0,
  "search_result_id": "cs_61987ff6-6d56-4695-83c0-1e7cfed818c7",
  "doc_id": "4ac085cb-82d0-4eb4-94f3-2672aa0599a2",
  "doc_title": "Earnings Report",
  "text": "The revenue for 2025 was..."
}
Copy

Champ	Type	Description
`type`	string	Type de citation (toujours `cortex_search_citation`).
`index`	entier	Index de la citation dans les résultats de la recherche.
`search_result_id`	string	Identificateur unique du résultat de la recherche.
`doc_id`	string	Identificateur unique du document.
`doc_title`	string	Le titre du document.
`text`	string	Extrait textuel du document utilisé comme citation.

`BudgetConfig`¶

Champ	Type	Description
`seconds`	entier	Budget temporel en secondes.
`tokens`	entier	Budget du jeton.

Exemple

{
  "seconds": 30,
  "tokens": 16000
}

Copy

`ChartContent`¶

Champ	Type	Description
`tool_use_id`	string	ID de l’utilisation d’outil qui a généré ce graphique.
`chart_spec`	string	Spécification du graphique vega-lite sérialisée en tant que chaîne.

Exemple

{
  "tool_use_id": "toolu_123",
  "chart_spec": "{\"$schema\":\"https://vega.github.io/schema/vega-lite/v5.json\",\"data\":{...},\"mark\":\"bar\"}"
}

Copy

`CortexAnalystSuggestionDelta`¶

Champ	Type	Description
`index`	entier	Index du tableau de suggestions que ce Delta représente.
`delta`	string	Delta textuel pour la suggestion dans cet index.

Exemple

{
  "index": 0,
  "delta": "What..."
}

Copy

`CortexAnalystToolResultDelta`¶

Champ	Type	Description
`text`	string	Delta textuel de la réponse finale de Cortex Analyst.
`think`	string	Delta textuel des étapes de raisonnement de Cortex Analyst.
`sql`	string	Delta de la sortie SQL de Cortex Analyst. Actuellement, l’ensemble de la requête SQL arrive dans un seul événement, mais il se peut que nous diffusions la requête SQL jeton par jeton à l’avenir.
`sql_explanation`	string	Delta de l’explication de Cortex Analyst sur le fonctionnement de la requête SQL.
`query_id`	string	ID de requête une fois que l’exécution SQL commence.
`verified_query_used`	booléen	Indique si une requête vérifiée a été utilisée pour générer cette réponse.
`result_set`	ResultSet	Résultats de l’exécution SQL. Correspond au schéma du ResultSet de l’API SQL de Snowflake (https://docs.snowflake.com/fr/developer-guide/sql-api/reference#resultset).
`suggestions`	CortexAnalystSuggestionDelta	Delta des questions suggérées par Cortex Analyst. Celui-ci est envoyé lorsque Cortex Analyst ne peut pas répondre à la question à cause d’informations manquantes ou d’autres défaillances.

Exemple

{
  "text": "The...",
  "think": "Thinking...",
  "sql": "SELECT...",
  "sql_explanation": "This...",
  "query_id": "707787a0-a684-4ead-adb0-3c3b62b043d9",
  "verified_query_used": false,
  "result_set": {
    "statementHandle": "707787a0-a684-4ead-adb0-3c3b62b043d9",
    "resultSetMetaData": {
      "partition": 0,
      "numRows": 0,
      "format": "jsonv2",
      "rowType": [
        {
          "name": "my_column",
          "type": "VARCHAR",
          "length": 0,
          "precision": 0,
          "scale": 0,
          "nullable": false
        }
      ]
    },
    "data": [
      [
        "row1 col1",
        "row1 col2"
      ],
      [
        "row2 col1",
        "row2 col2"
      ]
    ]
  },
  "suggestions": {
    "index": 0,
    "delta": "What..."
  }
}

Copy

`ExecutionEnvironment`¶

Configuration pour les outils exécutés par le serveur.

Champ	Type	Description
`type`	string	Type d’environnement d’exécution. Actuellement, seul `warehouse` est pris en charge.
`warehouse`	string	Nom de l’entrepôt. Sensible à la casse. S’il s’agit d’un identificateur sans guillemets, indiquez le nom en majuscules.
`query_timeout`	entier	Délai d’attente de la requête en secondes.

Exemple

{
  "type": "warehouse",
  "warehouse": "MY_WAREHOUSE",
  "query_timeout": 60
}

Copy

`Message`¶

Représente un seul message dans la conversation. Peut provenir de l’utilisateur ou de l’assistant.

Champ	Type	Description
`role`	string	Identifie qui a envoyé le message : soit l’utilisateur, soit l’assistant. Les messages de l’utilisateur contiennent généralement des requêtes, tandis que les messages de l’assistant contiennent des réponses et des résultats d’outils.
`content`	tableau d”MessageContentItem	Tableau d’éléments de contenu qui composent le message. Peut inclure du texte, des résultats d’outils, ou des types de contenu personnalisés.

Exemple

{
  "role": "user",
  "content": [
    {
      "type": "text",
      "text": "What is the total revenue for 2023?"
    }
  ]
}

Copy

`MessageContentItem`¶

Champ	Type	Description
`type`	string	Type de contenu (toujours `chart`).
`chart`	ChartContent	Graphique.

Exemple

{
  "type": "chart",
  "chart": {
    "tool_use_id": "toolu_123",
    "chart_spec": "{\"$schema\":\"https://vega.github.io/schema/vega-lite/v5.json\",\"data\":{...},\"mark\":\"bar\"}"
  }
}

Copy

Champ	Type	Description
`type`	string	Type de contenu (toujours `table`).
`table`	TableContent	Table.

Exemple

{
  "type": "table",
  "table": {
    "tool_use_id": "toolu_123",
    "query_id": "6ac75378-6337-48a6-80ab-6de48dd680eb",
    "result_set": {
      "statementHandle": "707787a0-a684-4ead-adb0-3c3b62b043d9",
      "resultSetMetaData": {
        "partition": 0,
        "numRows": 0,
        "format": "jsonv2",
        "rowType": [
          {
            "name": "my_column",
            "type": "VARCHAR",
            "length": 0,
            "precision": 0,
            "scale": 0,
            "nullable": false
          }
        ]
      },
      "data": [
        [
          "row1 col1",
          "row1 col2"
        ],
        [
          "row2 col1",
          "row2 col2"
        ]
      ]
    },
    "title": "Revenue by Month"
  }
}

Copy

Champ	Type	Description
`text`	string	Résultat textuel provenant de l’agent.
`annotations`	tableau d”Annotation	Toute annotation jointe au résultat textuel (par exemple, des citations).
`is_elicitation`	booléen	Indique si ce contenu textuel correspond à une demande d’informations supplémentaires de la part de l’agent adressée à l’utilisateur final.
`type`	string	Type de contenu (toujours `text`).

Exemple

{
  "text": "Lorem ipsum dolor...",
  "annotations": [
    {
      "type": "cortex_search_citation",
      "index": 0,
      "search_result_id": "cs_61987ff6-6d56-4695-83c0-1e7cfed818c7",
      "doc_id": "4ac085cb-82d0-4eb4-94f3-2672aa0599a2",
      "doc_title": "Earnings Report",
      "text": "The revenue for 2025 was..."
    }
  ],
  "is_elicitation": false,
  "type": "text"
}

Copy

Champ	Type	Description
`type`	string	Type de contenu (toujours `thinking`).
`thinking`	ThinkingContent	Contenu de la réflexion.

Exemple

{
  "type": "thinking",
  "thinking": {
    "text": "To answer your question I must..."
  }
}

Copy

Champ	Type	Description
`type`	string	Type de contenu (toujours `tool_result`).
`tool_result`	ToolResult	Résultat de l’outil.

Exemple

{
  "type": "tool_result",
  "tool_result": {
    "tool_use_id": "toolu_123",
    "type": "cortex_analyst_text2sql",
    "name": "my_cortex_analyst_semantic_view",
    "content": [
      {
        "type": "json",
        "json": {
          "answer": 42
        }
      }
    ],
    "status": "success"
  }
}

Copy

Champ	Type	Description
`type`	string	Type de contenu (toujours `tool_use`).
`tool_use`	ToolUse	Utilisation de l’outil.

Exemple

{
  "type": "tool_use",
  "tool_use": {
    "tool_use_id": "toolu_123",
    "type": "cortex_analyst_text2sql",
    "name": "my_cortex_analyst_semantic_view",
    "input": {
      "location": "San Francisco, CA"
    },
    "client_side_execute": "true"
  }
}

Copy

`ModelConfig`¶

Champ	Type	Description
`orchestration`	string	Modèle à utiliser pour l’orchestration. S’il n’est pas fourni, un modèle est automatiquement sélectionné.

Exemple

{
  "orchestration": "claude-4-sonnet"
}

Copy

`OrchestrationConfig`¶

Champ	Type	Description
`budget`	BudgetConfig	Contraintes budgétaires pour l’agent. Si plus d’une contrainte est spécifiée, la première contrainte atteinte mettra fin à la requête.

Exemple

{
  "budget": {
    "seconds": 30,
    "tokens": 16000
  }
}

Copy

`ResultSet`¶

Champ	Type	Description
`statementHandle`	string	ID de la requête.
`resultSetMetaData`	ResultSetMetaData	Métadonnées du jeu de résultats.
`data`	array of array	Tableau 2D représentant les données.

Exemple

{
  "statementHandle": "707787a0-a684-4ead-adb0-3c3b62b043d9",
  "resultSetMetaData": {
    "partition": 0,
    "numRows": 0,
    "format": "jsonv2",
    "rowType": [
      {
        "name": "my_column",
        "type": "VARCHAR",
        "length": 0,
        "precision": 0,
        "scale": 0,
        "nullable": false
      }
    ]
  },
  "data": [
    [
      "row1 col1",
      "row1 col2"
    ],
    [
      "row2 col1",
      "row2 col2"
    ]
  ]
}

Copy

`ResultSetMetaData`¶

Champ	Type	Description
`partition`	entier	Numéro d’index de la partition.
`numRows`	entier	Le nombre total de lignes de résultats.
`format`	string	Format des données dans le jeu de résultats.
`rowType`	tableau d”RowType	Description des colonnes dans le résultat.

Exemple

{
  "partition": 0,
  "numRows": 0,
  "format": "jsonv2",
  "rowType": [
    {
      "name": "my_column",
      "type": "VARCHAR",
      "length": 0,
      "precision": 0,
      "scale": 0,
      "nullable": false
    }
  ]
}

Copy

`RowType`¶

Champ	Type	Description
`name`	string	Nom de la colonne.
`type`	string	Type de données Snowflake de la colonne (https://docs.snowflake.com/en/sql-reference/intro-summary-data-types).
`length`	entier	Longueur de la colonne.
`precision`	entier	Précision de la colonne.
`scale`	entier	Échelle de la colonne.
`nullable`	booléen	Spécifie si la colonne peut avoir le critère Null ou non.

Exemple

{
  "name": "my_column",
  "type": "VARCHAR",
  "length": 0,
  "precision": 0,
  "scale": 0,
  "nullable": false
}

Copy

`TableContent`¶

Champ	Type	Description
`tool_use_id`	string	ID de l’utilisation d’outil qui a généré cette table.
`query_id`	string	Identifiant de requête de la requête SQL qui a généré ces données.
`result_set`	ResultSet	Résultats SQL pour afficher une table. Correspond au schéma du ResultSet de l’API SQL de Snowflake (https://docs.snowflake.com/fr/developer-guide/sql-api/reference#resultset).
`title`	string	Titre de cette table.

Exemple

{
  "tool_use_id": "toolu_123",
  "query_id": "6ac75378-6337-48a6-80ab-6de48dd680eb",
  "result_set": {
    "statementHandle": "707787a0-a684-4ead-adb0-3c3b62b043d9",
    "resultSetMetaData": {
      "partition": 0,
      "numRows": 0,
      "format": "jsonv2",
      "rowType": [
        {
          "name": "my_column",
          "type": "VARCHAR",
          "length": 0,
          "precision": 0,
          "scale": 0,
          "nullable": false
        }
      ]
    },
    "data": [
      [
        "row1 col1",
        "row1 col2"
      ],
      [
        "row2 col1",
        "row2 col2"
      ]
    ]
  },
  "title": "Revenue by Month"
}

Copy

`ThinkingContent`¶

Champ	Type	Description
`text`	string	Jetons de réflexion de l’agent.

Exemple

{
  "text": "To answer your question I must..."
}

Copy

`Tool`¶

Définit un outil qui peut être utilisé par l’agent. Les outils offrent des capacités spécifiques telles que l’analyse des données, la recherche ou des fonctions génériques.

Champ	Type	Description
`tool_spec`	ToolSpec	Spécification du type, de la configuration et des exigences d’entrée de l’outil.

Exemple

{
  "tool_spec": {
    "type": "generic",
    "name": "get_revenue",
    "description": "Fetch the delivery revenue for a location.",
    "input_schema": {
      "type": "object",
      "properties": {
        "location": {
          "type": "string",
          "description": "The city and state, e.g. San Francisco, CA"
        }
      }
    },
    "required": [
      "location"
    ]
  }
}

Copy

`ToolChoice`¶

Champ	Type	Description
`type`	string	Détermine la façon dont les outils sont sélectionnés : - automatique - Sélection automatique des outils (par défaut) - obligatoire - Doit utiliser au moins un outil - outil - Utilisation d’outils nommés spécifiques
`name`	array of string	Liste de noms d’outils spécifiques à utiliser lorsque le type est « tool ».

Exemple

{
  "type": "auto",
  "name": [
    "analyst_tool",
    "search_tool"
  ]
}

Copy

`ToolInputSchema`¶

Champ	Type	Description
`type`	string	Le type de l’objet du schéma d’entrée.
`description`	string	Description de ce qu’est l’entrée.
`properties`	carte de ToolInputSchema	Si le type est `object`, définitions de chaque paramètre d’entrée.
`items`	ToolInputSchema	Si le type est `array`, schéma des éléments du tableau.
`required`	array of string	Si le type est `object`, liste des noms de paramètres d’entrée requis.

Exemple

{
  "type": "object",
  "description": "Input for my custom tool",
  "properties": {
    "location": {
      "type": "string",
      "description": "The city and state, e.g. San Francisco, CA"
    }
  },
  "items": {},
  "required": [
    "location"
  ]
}

Copy

`ToolResource`¶

Configuration pour l’outil d’analyse text-to-SQL. Fournit des paramètres pour la génération et l’exécution de requêtes SQL. Un seul semantic_model_file ou semantic_view précisément doit être fourni.

Champ

Type

Description

semantic_model_file

string

Chemin d’accès à un fichier stocké dans une zone de préparation Snowflake contenant le modèle sémantique yaml.

semantic_view

string

Nom de l’objet du modèle sémantique natif de Snowflake.

execution_environment

ExecutionEnvironment

Configuration de l’exécution de la requête SQL générée.

Exemple
{
  "semantic_model_file": "@db.schema.stage/semantic_model.yaml",
  "semantic_view": "db.schema.semantic_view",
  "execution_environment": {
    "type": "warehouse",
    "warehouse": "MY_WAREHOUSE",
    "query_timeout": 60
  }
}
Copy
Configuration de la fonctionnalité de recherche. Définit comment la recherche et la récupération de documents doivent être effectuées.

Champ

Type

Description

search_service

string

Nom entièrement qualifié du service de recherche.

title_column

string

Colonne de titres du document.

id_column

string

Colonne d’ID du document.

filter

objet

Filtre la requête pour les résultats de la recherche.

Exemple
{
  "search_service": "database.schema.service_name",
  "title_column": "account_name",
  "id_column": "account_id",
  "filter": {
    "@eq": {
      "<column>": "<value>"
    }
  }
}
Copy
Champ

Type

Description

type

string

Indique si l’outil est exécuté côté serveur, qu’il s’agisse d’une procédure stockée ou d’une UDF.

execution_environment

ExecutionEnvironment

identifier

string

Nom entièrement qualifié de la procédure stockée ou de la UDF.

Exemple
{
  "type": "function",
  "execution_environment": {
    "type": "warehouse",
    "warehouse": "MY_WAREHOUSE",
    "query_timeout": 60
  },
  "identifier": "MY_DB.MY_SCHEMA.MY_UDF"
}
Copy

Champ	Type	Description
`semantic_model_file`	string	Chemin d’accès à un fichier stocké dans une zone de préparation Snowflake contenant le modèle sémantique yaml.
`semantic_view`	string	Nom de l’objet du modèle sémantique natif de Snowflake.
`execution_environment`	ExecutionEnvironment	Configuration de l’exécution de la requête SQL générée.

Champ	Type	Description
`search_service`	string	Nom entièrement qualifié du service de recherche.
`title_column`	string	Colonne de titres du document.
`id_column`	string	Colonne d’ID du document.
`filter`	objet	Filtre la requête pour les résultats de la recherche.

Champ	Type	Description
`type`	string	Indique si l’outil est exécuté côté serveur, qu’il s’agisse d’une procédure stockée ou d’une UDF.
`execution_environment`	ExecutionEnvironment
`identifier`	string	Nom entièrement qualifié de la procédure stockée ou de la UDF.

`ToolResult`¶

Champ	Type	Description
`tool_use_id`	string	Identificateur unique pour cette utilisation d’outil. Peut être utilisé pour associer les résultats de l’outil.
`type`	string	Type de l’outil (par exemple, cortex_search ou cortex_analyst_text2sql).
`name`	string	Identificateur unique de cette instance d’outil.
`content`	tableau d”ToolResultContent	Contenu du résultat de l’outil.
`status`	string	État d’exécution de l’outil.

Exemple

{
  "tool_use_id": "toolu_123",
  "type": "cortex_analyst_text2sql",
  "name": "my_cortex_analyst_semantic_view",
  "content": [
    {
      "type": "json",
      "json": {
        "answer": 42
      }
    }
  ],
  "status": "success"
}

Copy

`ToolResultContent`¶

Champ

Type

Description

type

string

Type de résultat (toujours json).

json

objet

Sortie structurée d’un outil. Le schéma varie en fonction du type d’outil.

Exemple
{
  "type": "json",
  "json": {
    "answer": 42
  }
}
Copy
Champ

Type

Description

type

string

Type de résultat (toujours text).

text

string

Texte du résultat.

Exemple
{
  "type": "text",
  "text": "The answer is 42"
}
Copy

Champ	Type	Description
`type`	string	Type de résultat (toujours `json`).
`json`	objet	Sortie structurée d’un outil. Le schéma varie en fonction du type d’outil.

Champ	Type	Description
`type`	string	Type de résultat (toujours `text`).
`text`	string	Texte du résultat.

`ToolSpec`¶

Spécification du type, de la configuration et des exigences d’entrée de l’outil.

Champ	Type	Description
`type`	string	Type de capacité de l’outil. Il peut s’agir de types spécialisés comme « cortex_analyst_text_to_sql » ou « generic » pour les outils à usage général.
`name`	string	Identificateur unique pour référencer cette instance d’outil. Utilisé pour faire correspondre la configuration dans tool_resources.
`description`	string	Description de l’outil à prendre en compte pour l’utilisation d’outil.
`input_schema`	ToolInputSchema	Définition du schéma JSON des paramètres d’entrée attendus pour cet outil. Ces informations seront transmises à l’agent pour qu’il ait connaissance de la structure qu’il doit suivre lors de la génération de l’entrée pour ToolUses. Requis pour permettre aux outils génériques de spécifier leurs paramètres d’entrée.

Exemple

{
  "type": "generic",
  "name": "get_weather",
  "description": "lorem ipsum",
  "input_schema": {
    "type": "object",
    "properties": {
      "location": {
        "type": "string",
        "description": "The city and state, e.g. San Francisco, CA"
      }
    },
    "required": [
      "location"
    ]
  }
}

Copy

`ToolUse`¶

Champ	Type	Description
`tool_use_id`	string	Identificateur unique pour cette utilisation d’outil. Peut être utilisé pour associer les résultats de l’outil.
`type`	string	Type de l’outil (par exemple, cortex_search ou cortex_analyst_text2sql).
`name`	string	Identificateur unique de cette instance d’outil.
`input`	objet	Entrée structurée de cet outil. Le schéma de cet objet devrait varier en fonction de la spécification de l’outil.
`client_side_execute`	booléen	Indique si l’utilisation de l’outil est exécutée du côté du client.

Exemple

{
  "tool_use_id": "toolu_123",
  "type": "cortex_analyst_text2sql",
  "name": "my_cortex_analyst_semantic_view",
  "input": {
    "location": "San Francisco, CA"
  },
  "client_side_execute": "true"
}

Copy

API d’exécution des Agents Cortex¶

Requête d’exécution d’agent avec objet d’agent¶

Paramètres de chemin¶

En-têtes de requête¶

Corps de requête¶

Exécution d’agent sans objet d’agent¶

En-têtes de requête¶

Corps de requête¶

Réponses en continu¶

response¶

response.text¶

response.text.delta¶

response.text.annotation¶

response.thinking¶

response.thinking.delta¶

response.tool_use¶

response.tool_result¶

response.tool_result.status¶

response.tool_result.analyst.delta¶

response.table¶

response.chart¶

response.status¶

error¶

Événement metadata¶

Schémas¶

AgentInstructions¶

Annotation¶

BudgetConfig¶

ChartContent¶

CortexAnalystSuggestionDelta¶

CortexAnalystToolResultDelta¶

ExecutionEnvironment¶

Message¶

MessageContentItem¶

ModelConfig¶

OrchestrationConfig¶

ResultSet¶

ResultSetMetaData¶

RowType¶

TableContent¶

ThinkingContent¶

Tool¶

ToolChoice¶

ToolInputSchema¶

ToolResource¶

ToolResult¶

ToolResultContent¶

ToolSpec¶

ToolUse¶

`response`¶

`response.text`¶

`response.text.delta`¶

`response.text.annotation`¶

`response.thinking`¶

`response.thinking.delta`¶

`response.tool_use`¶

`response.tool_result`¶

`response.tool_result.status`¶

`response.tool_result.analyst.delta`¶

`response.table`¶

`response.chart`¶

`response.status`¶

`error`¶

Événement `metadata`¶

`AgentInstructions`¶

`Annotation`¶

`BudgetConfig`¶

`ChartContent`¶

`CortexAnalystSuggestionDelta`¶

`CortexAnalystToolResultDelta`¶

`ExecutionEnvironment`¶

`Message`¶

`MessageContentItem`¶

`ModelConfig`¶

`OrchestrationConfig`¶

`ResultSet`¶

`ResultSetMetaData`¶

`RowType`¶

`TableContent`¶

`ThinkingContent`¶

`Tool`¶

`ToolChoice`¶

`ToolInputSchema`¶

`ToolResource`¶

`ToolResult`¶

`ToolResultContent`¶

`ToolSpec`¶

`ToolUse`¶