API REST des Cortex Agents¶
Utilisez cette API pour simplifier la création d’une application de chat interactive.
Exécuter l’agent¶
POST <account_url>/api/v2/cortex/agent:run
Envoie une requête de l’utilisateur au service Cortex Agents fourni dans le corps de la requête et renvoie sa réponse.
Requête¶
Paramètres de chemin¶
Paramètre |
Description |
---|---|
|
(Obligatoire) L’URL de votre compte Snowflake. Pour obtenir des instructions sur la façon de trouver l’URL de votre compte, voir Recherche de l’organisation et du nom de compte pour un compte. |
En-têtes de requête¶
En-tête |
Description |
---|---|
|
(Obligatoire) Jeton d’autorisation. Pour plus d’informations, voir Configurer l’authentification de l’API REST. |
|
(Obligatoire) application/json |
Corps de requête¶
Le corps de la requête contient le modèle, l’instruction de réponse, les champs d’expérimentation, les outils, les ressources d’outils et les messages.
Champ |
Type |
Description |
---|---|---|
|
string |
Le nom du modèle utilisé par l’Agent pour générer une réponse. Pour obtenir la liste des modèles pris en charge, voir Modèles pris en charge. |
|
string |
Les instructions que le modèle suit lorsqu’il génère la réponse. |
|
objet |
Les indicateurs expérimentaux transmis à l’Agent. |
|
tableau |
Un tableau de spécifications d’outils à la disposition de l’Agent. |
|
objet |
Les ressources requises par les outils. |
|
objet |
La configuration utilisée pour sélectionner l’outil. |
|
tableau |
Le tableau des messages de la conversation. |
Response instruction¶
Le champ response_instruction
est une chaîne qui fournit des instructions au modèle pour la génération de réponses.
Configuration de l’outil¶
Cette section détaille les types d’outils pris en charge, leurs options de configuration et la manière de spécifier les ressources nécessaires pour chaque outil.
Spécifications de l’outil¶
Le champ tools
contient un tableau des outils disponibles :
Champ |
Type |
Description |
---|---|---|
|
string |
Le type d’outil. La combinaison du type et du nom constitue un identifiant unique. |
|
string |
Le nom de l’outil. La combinaison du type et du nom constitue un identifiant unique. |
Les valeurs prises en charge par tool_spec.type
sont les suivantes :
cortex_search
: Utilisé pour la fonctionnalité de recherche de Cortexcortex_analyst_text_to_sql
: Utilisé pour la conversion de texte en SQL de Cortex Analystsql_exec
: Utilisé pour l’exécution des requêtes SQL. Vous êtes chargé d’exécuter la requête SQL et de fournir les résultats sous forme de résultats d’outils. Pour plus de détails, voir Exemple de réponses à la requête ci-dessous.data_to_chart
: Utilisé pour générer des graphiques
Tool resources¶
L’objet tool_resources
fournit des objets de configuration pour chaque outil.
tool_resources: {
"toolName1": {configuration object for toolName1},
"toolName2": {configuration object for toolName2},
// ...
}
La configuration pour chaque type d’outil est décrite ci-dessous.
cortex_search
L’objet
SearchName
contient la configuration d’un outil Cortex Search."SearchName": { // Required: The Snowflake search service identifier "name": "database.schema.service_name", // Optional: Number of search results to include "max_results": 5, // Optional: Column to use as document title "title_column": "title", // Optional: Column to use as document identifier "id_column": "id", // Optional: Filters to apply to search results (such as @eq for equality) "filter": { "@eq": {"<column>": "<value>"} } }
cortex_analyst_text_to_sql
L’objet
AnalystName
contient la configuration d’un outil de conversion de texte en SQL de Cortex Analyst. La configuration doit inclure le modèle sémantique ou la vue à utiliser. Par exemple :"AnalystName": { // Stage path to semantic model file in `semantic_model_file` "semantic_model_file": "@database.schema.stage/my_semantic_model.yaml" }
ou via Aperçu des vues sémantiques
"AnalystName": { // Fully qualified name of the semantic view object "semantic_view": "@database.schema.semantic_view" }
Tool choice¶
Le champ tool_choice
configure le comportement de sélection des outils.
Champ |
Type |
Description |
---|---|---|
|
string |
Manière de sélectionner les outils. Valeurs valides :
|
|
tableau |
Tableau facultatif de noms d’outils à utiliser. Valable uniquement lorsque |
Messages¶
Le tableau messages
contient l’historique des conversations entre l’utilisateur et l’assistant :
Champ |
Type |
Description |
---|---|---|
|
string |
Le rôle de l’expéditeur du message. Valeurs valides :
|
|
tableau |
Le tableau des éléments de contenu composant le message. |
Structure du contenu du message¶
Le tableau content
de chaque message peut contenir plusieurs éléments de contenu de types différents.
Champ |
Type |
Description |
---|---|---|
|
string |
Le type de contenu. Valeurs valides :
|
- Contenu du texte
Lorsque
type
est"text"
:Champ
Type
Description
messages[].content[].text
string
Le contenu du texte du message.
Exemple :
{ "type": "text", "text": "Show me sales by region for Q1 2024" }
- Contenu du graphique
Lorsque
type
est « chart » :Champ
Type
Description
messages[].content[].chart
objet
Le contenu graphique du message.
messages[].content[].chart.chart_spec
string
Graphique en tant que spécification Vega-Lite.
Exemple :
{ "type": "chart", "chart": { "chart_spec": "{\"$schema\":\"https://vega.github.io/schema/vega-lite/v5.json\",\"data\":{\"values\":[{\"REGION\":\"NORTH_AMERICA\",\"SUM(SALES)\":\"2000.00\"},{\"REGION\":\"EUROPE\",\"SUM(SALES)\":\"1700.00\"},{\"REGION\":\"SAUTH_AMERICA\",\"SUM(SALES)\":\"1500.00\"}]},\"encoding\":{\"x\":{\"field\":\"REGION\",\"sort\":null,\"type\":\"nominal\"},\"y\":{\"field\":\"SUM(SALES)\",\"sort\":null,\"type\":\"quantitative\"}},\"mark\":\"bar\"}", } }
- Contenu de la table
Lorsque
type
est « table » :Champ
Type
Description
messages[].content[].table
objet
Le contenu de la table du message.
messages[].content[].table.query_id
string
L’ID de la requête exécutée.
Exemple :
{ "type": "table", "table": { "query_id": "01bbff92-0304-c8c7-0022-b7869a076c22" } }
- Tool use
Lorsque
type
est « tool_use » :Champ
Type
Description
messages[].content[].tool_use
objet
Conteneur pour les détails de la requête d’utilisation de l’outil.
messages[].content[].tool_use.tool_use_id
string
Identifiant unique pour cette requête d’utilisation de l’outil.
messages[].content[].tool_use.name
string
Nom de l’outil à exécuter. Doit correspondre à un nom d’outil du tableau des outils.
messages[].content[].tool_use.input
objet
Paramètres d’entrée pour l’exécution de l’outil.
Exemple :
{ "type": "tool_use", "tool_use": { "tool_use_id": "tu_01", "name": "Analyst1", "input": { "query": "Show me sales by region for Q1 2024" } } }
- Tool results
Lorsque
type
est"tool_results"
:Champ
Type
Description
messages[].content[].tool_results
objet
Conteneur pour les résultats de l’exécution de l’outil et les métadonnées.
messages[].content[].tool_results.tool_use_id
string
Fait référence au tool_use_id qui a généré ces résultats.
messages[].content[].tool_results.name
string
Nom de l’outil qui a été exécuté. Doit correspondre à un nom d’outil du tableau des outils.
messages[].content[].tool_results.status
string
Statut d’exécution de l’outil.
Valeurs valides :
"success"
"error"
messages[].content[].tool_results.content
tableau
Tableau des éléments de contenu produits par l’exécution de l’outil.
Peut contenir des éléments des types suivants :
Type
Champs
Description
text
type: "text"
text: string
Contenu en texte brut renvoyé par l’outil.
json
type: "json"
json: object
Données JSON structurées renvoyées par l’outil.
Exemple :
{ "type": "tool_results", "tool_results": { "tool_use_id": "tu_01", "status": "success", "content": [ { "type": "json", "json": { "sql": "SELECT region, SUM(sales) FROM sales_data WHERE quarter='Q1' AND year=2024 GROUP BY region" "text": "This is our interpretation of your question: Show me sales by region for Q1 2024. We have generated the following SQL query for you: SELECT region, SUM(sales) FROM sales_data WHERE quarter='Q1' AND year=2024 GROUP BY region" } } ] } }
Exemple de message complet¶
Cet exemple montre un message complet avec une requête de l’utilisateur (role
est user
) et une réponse (role
est assistant
). La réponse comprend un événement d’utilisation d’outil pour un outil nommé Analyst1
et un événement de résultats d’outil pour le même outil.
{
"messages": [
{
"role": "user",
"content": [
{
"type": "text",
"text": "Show me sales by region for Q1 2024"
}
]
},
{
"role": "assistant",
"content": [
{
"type": "tool_use",
"tool_use": {
"tool_use_id": "tu_01",
"name": "Analyst1",
"input": {
"query": "Show me sales by region for Q1 2024"
}
}
},
{
"type": "tool_results",
"tool_results": {
"tool_use_id": "tu_01",
"name": "Analyst1",
"status": "success",
"content": [
{
"type": "json",
"json": {
"sql": "SELECT region, SUM(sales) FROM sales_data WHERE quarter='Q1' AND year=2024 GROUP BY region"
"text": "This is our interpretation of your question: Show me sales by region for Q1 2024. We have generated the following SQL query for you: SELECT region, SUM(sales) FROM sales_data WHERE quarter='Q1' AND year=2024 GROUP BY region"
}
}
]
}
}
]
}
]
}
Réponse¶
Lors du flux, chaque événement arrive dans un format d’événements envoyés par le serveur (SSE), avec les principaux modèles suivants :
Événements
message.delta
incrémentiels pour des fragments de la sortieÉvénements
error
en cas de problème.
Événement message.delta
¶
Champ |
Type |
Description |
---|---|---|
|
string |
|
|
objet |
Contient des données de mise à jour incrémentielle. |
|
string |
Identifiant unique du message. |
|
string |
|
|
tableau |
Une liste de fragments ou de segments de messages partiels. |
|
entier |
La position de ce fragment dans le message actuel. |
|
string |
Type de contenu. Valeurs valides :
|
|
string |
Si |
|
objet |
Si |
|
string |
Graphique en tant que spécification Vega-Lite. |
|
objet |
Si |
|
string |
L’ID de la requête exécutée. |
|
objet |
Si |
|
string |
L’identifiant unique de l’appel d’outil. |
|
string |
Le nom de l’outil appelé. |
|
objet |
La charge utile JSON de l’outil. |
|
objet |
Si |
|
string |
L’identifiant unique de la sortie de l’outil. |
|
string |
Le statut d’exécution de l’outil. Valeurs valides :
|
|
tableau |
Une liste d’éléments décrivant les données renvoyées par l’outil. |
|
string |
Le type de contenu renvoyé par l’outil. Valeurs valides :
|
|
objet |
Si |
|
string |
Si |
Événement error
¶
Champ |
Type |
Description |
---|---|---|
|
string |
|
|
objet |
Contient les détails de l’erreur. |
|
string |
Le code d’erreur Snowflake. Par exemple, |
|
string |
Une description de ce qui n’a pas fonctionné. Par exemple, |
Exemple de déroulement d’une conversation¶
Cette section présente un échantillon de conversation entre un utilisateur et un assistant utilisant l’API REST des Cortex Agents.
Requête d’échantillon¶
{
"model": "llama3.3-70b",
"response_instruction": "You will always maintain a friendly tone and provide concise response.",
"experimental": {},
"tools": [
{
"tool_spec": {
"type": "cortex_analyst_text_to_sql",
"name": "Analyst1"
}
},
{
"tool_spec": {
"type": "cortex_analyst_text_to_sql",
"name": "Analyst2"
}
},
{
"tool_spec": {
"type": "sql_exec",
"name": "sql_execution_tool"
}
},
{
"tool_spec": {
"type": "data_to_chart",
"name": "data_to_chart"
}
},
{
"tool_spec": {
"type": "cortex_search",
"name": "Search1"
}
}
],
"tool_resources": {
"Analyst1": { "semantic_model_file": "stage1"},
"Analyst2": { "semantic_model_file": "stage2"},
"Search1": {
"name": "db.schema.service_name",
"filter": {"@eq": {"region": "North America"} }
}
},
"tool_choice": {
"type": "auto"
},
"messages": [
{
"role": "user",
"content": [
{
"type": "text",
"text": "What are the top three customers by revenue?"
}
]
}
]
}
Exemple de réponse¶
{
"id": "msg_001",
"object": "message.delta",
"delta": {
"content": [
{
"index": 0,
"type": "tool_use",
"tool_use": {
"tool_use_id": "toolu_XXXXXX",
"name": "analyst1",
"input": {
"messages": [
"role:USER content:{text:{text:\"What are the top three customers by revenue?\"}}"
],
"model": "snowflake-hosted-semantic",
"experimental": ""
}
}
},
{
"index": 0,
"type": "tool_results",
"tool_results": {
"tool_use_id": "toolu_XXXXXX",
"content": [
{
"type": "json",
"json": {
"suggestions": [],
"sql": "WITH __customers AS (\n SELECT\n customer_id,\n revenue\n FROM user_database.user_schema.user_table\n)\nSELECT\n customer_id, revenue FROM __customers ORDER BY revenue DESC LIMIT 3\n -- Generated by Cortex Analyst\n;",
"text": "This is our interpretation of your question:\n\n__What are the top three customers by revenue?\n\n"
}
}
],
"status": "success"
}
},
{
"type": "tool_use",
"tool_use": {
"tool_use_id": "tool_002",
"name": "sql_execution_tool",
"input": {
"sql": "WITH __customers AS (SELECT customer_id, revenue FROM user_database.user_schema.user_table) SELECT customer_id, revenue FROM __customers ORDER BY revenue DESC LIMIT 3"
}
}
}
]
}
}
Demande d’échantillons de réponses¶
Les Cortex Agents peuvent générer des réponses textuelles et graphiques sur la base des requêtes SQL exécutées. L’exemple suivant montre comment utiliser l’API des Cortex Agents pour générer de telles réponses.
Pour obtenir les réponses, le client adresse une requête complémentaire à l’API du Cortex Agent avec le query_id
du SQL exécuté du côté du client. Le SQL à exécuter est fourni dans l’événement tool_use
du type d’outil sql_exec
dans le dernier message de réponse.
Les requêtes doivent utiliser les outils cortex_analyst_text_to_sql
et sql_exec
pour obtenir la réponse textuelle, et doivent en outre utiliser l’outil data_to_chart
pour obtenir la réponse graphique. Les graphiques ne sont renvoyés que si l’agent décide que les graphiques sont un bon moyen de présenter la réponse.
Note
Pour les jeux de résultats de plus de 4 000 cellules, une réponse table
est renvoyée à la place des réponses text
et chart
.
{
"model": "llama3.3-70b",
"response_instruction": "You will always maintain a friendly tone and provide concise response.",
"experimental": {},
"tools": [
{
"tool_spec": {
"type": "cortex_analyst_text_to_sql",
"name": "Analyst1"
}
},
{
"tool_spec": {
"type": "cortex_analyst_text_to_sql",
"name": "Analyst2"
}
},
{
"tool_spec": {
"type": "sql_exec",
"name": "sql_execution_tool"
}
},
{
"tool_spec": {
"type": "data_to_chart",
"name": "data_to_chart"
}
},
{
"tool_spec": {
"type": "cortex_search",
"name": "Search1"
}
}
],
"tool_resources": {
"Analyst1": { "semantic_model_file": "stage1"},
"Analyst2": { "semantic_model_file": "stage2"},
"Search1": {
"name": "db.schema.service_name",
"filter": {"@eq": {"region": "North America"} }
}
},
"tool_choice": {
"type": "auto"
},
"messages": [
{
"role": "user",
"content": [
{
"type": "text",
"text": "What are the top three customers by revenue?"
}
]
},
{
"role": "assistant",
"content": [
{
"type": "tool_use",
"tool_use": {
"tool_use_id": "tool_001",
"name": "Analyst1",
"input": {
"messages": [
"role:USER content:{text:{text:\"What are the top three customers by revenue?\"}}"
],
"model": "snowflake-hosted-semantic",
}
}
},
{
"type": "tool_results",
"tool_results": {
"status": "success",
"tool_use_id": "tool_001",
"content": [
{
"type": "json",
"json": {
"sql": "select * from table",
"text": "This is our interpretation of your question: What are the top three customers by revenue? \n\n"
}
}
]
}
}
]
},
{
"role": "user",
"content": [
{
"type": "tool_results",
"tool_results": {
"tool_use_id": "tool_002",
"result": {
"query_id": "01bbff92-0304-c8c7-0022-b7869a076c22"
}
}
}
]
}
]
}
Exemple de réponse¶
{
"id": "msg_001",
"object": "message.delta",
"delta": {
"content": [
{
"index": 0,
"type": "text",
"text": "This is a textual answer to your question"
},
{
"index": 0,
"type": "chart",
"chart": {
"chart_spec": "{\"$schema\": \"https://vega.github.io/schema/vega-lite/v5.json\", \"title\": \"Example chart\", \"mark\": \"bar\", \"encoding\": {\"x\": {\"field\": \"column_x\", \"type\": \"nominal\", \"sort\": null}, \"y\": {\"field\": \"column_y\", \"type\": \"quantitative\"}}, \"data\": {\"values\": [{\"column_x\": \"A\", \"column_y\": \"1\"}, {\"column_x\": \"A\", \"column_y\": \"1\"}]}}"
}
}
]
}
}
Limites des Cortex Agents¶
Les applications Streamlit in Snowflake (SiS) étant exécutées sous les droits du propriétaire, l’exécution des instructions SQL dans les applications SiS n’est pas prise en charge.
Les modèles Azure OpenAI ne sont pas pris en charge.