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
`account_url`	(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
`Authorization`	(Obligatoire) Jeton d’autorisation. Pour plus d’informations, voir Configurer l’authentification de l’API REST.
`Content-Type`	(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
`model`	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.
`response_instruction`	string	Les instructions que le modèle suit lorsqu’il génère la réponse.
`experimental`	objet	Les indicateurs expérimentaux transmis à l’Agent.
`tools`	tableau	Un tableau de spécifications d’outils à la disposition de l’Agent.
`tool_resources`	objet	Les ressources requises par les outils.
`tool_choice`	objet	La configuration utilisée pour sélectionner l’outil.
`messages`	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
`tool_spec.type`	string	Le type d’outil. La combinaison du type et du nom constitue un identifiant unique.
`tool_spec.name`	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 Cortex
cortex_analyst_text_to_sql : Utilisé pour la conversion de texte en SQL de Cortex Analyst
sql_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},
    // ...
}

Copy

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>"}
    }
}

Copy

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"
}

Copy

ou via Aperçu des vues sémantiques

"AnalystName": {
    // Fully qualified name of the semantic view object
    "semantic_view": "database.schema.semantic_view"
}

Copy

Tool choice¶

Le champ tool_choice configure le comportement de sélection des outils.

Champ	Type	Description
`type`	string	Manière de sélectionner les outils. Valeurs valides : `"auto"` ` (par défaut) `"required"` (utiliser au moins un outil) `"tool"` (utiliser l’outil spécifié)
`name`	tableau	Tableau facultatif de noms d’outils à utiliser. Valable uniquement lorsque `type = "tool"`.

Champ

Type

Description

type

string

Manière de sélectionner les outils.

Valeurs valides :

"auto" ` (par défaut)
"required" (utiliser au moins un outil)
"tool" (utiliser l’outil spécifié)

name

tableau

Tableau facultatif de noms d’outils à utiliser. Valable uniquement lorsque type = "tool".

Messages¶

Le tableau messages contient l’historique des conversations entre l’utilisateur et l’assistant :

Champ	Type	Description
`messages[].role`	string	Le rôle de l’expéditeur du message. Valeurs valides : `"system"` `"user"` `"assistant"`
`messages[].content`	tableau	Le tableau des éléments de contenu composant le message.

Champ

Type

Description

messages[].role

string

Le rôle de l’expéditeur du message.

Valeurs valides :

"system"
"user"
"assistant"

messages[].content

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
`messages[].content[].type`	string	Le type de contenu. Valeurs valides : `"text"` `"chart"` `"table"` `"tool_use"` `"tool_results"`

Champ

Type

Description

messages[].content[].type

string

Le type de contenu.

Valeurs valides :

"text"
"chart"
"table"
"tool_use"
"tool_results"

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"
}

Copy

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\"}",
  }
}

Copy

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"
  }
}

Copy

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"
    }
  }
}

Copy

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"
        }
      }
    ]
  }
}

Copy

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"
                }
              }
            ]
          }
        }
      ]
    }
  ]
}

Copy

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
`event`	string	`message.delta` pour les données partielles du message.
`data`	objet	Contient des données de mise à jour incrémentielle.
`data.id`	string	Identifiant unique du message.
`data.object`	string	`message.delta` ou un descripteur similaire.
`data.delta.content`	tableau	Une liste de fragments ou de segments de messages partiels.
`data.delta.content[].index`	entier	La position de ce fragment dans le message actuel.
`data.delta.content[].type`	string	Type de contenu. Valeurs valides : `"text"` `"chart"` `"table"` `"tool_use"` `"tool_results"`
`data.delta.content[].text`	string	Si `type = "text"`, la chaîne de texte partielle.
`data.delta.content[].chart`	objet	Si `type = "chart"`, le contenu graphique du message.
`data.delta.content[].chart.chart_spec`	string	Graphique en tant que spécification Vega-Lite.
`data.delta.content[].table`	objet	Si `type = "table"`, le contenu de la table du message.
`data.delta.content[].table.query_id`	string	L’ID de la requête exécutée.
`data.delta.content[].tool_use`	objet	Si `type = "tool_use"`, indique qu’un appel d’outil est en cours. Contient tool_use_id, name, input.
`data.delta.content[].tool_use.tool_use_id`	string	L’identifiant unique de l’appel d’outil.
`data.delta.content[].tool_use.name`	string	Le nom de l’outil appelé.
`data.delta.content[].tool_use.input`	objet	La charge utile JSON de l’outil.
`data.delta.content[].tool_results`	objet	Si `type = "tool_results"`, contient la sortie de l’outil.
`data.delta.content[].tool_results.tool_use_id`	string	L’identifiant unique de la sortie de l’outil.
`data.delta.content[].tool_results.status`	string	Le statut d’exécution de l’outil. Valeurs valides : `"success"` `"error"`
`data.delta.content[].tool_results.content`	tableau	Une liste d’éléments décrivant les données renvoyées par l’outil.
`data.delta.content[].tool_results.content[].type`	string	Le type de contenu renvoyé par l’outil. Valeurs valides : `"text/csv"` `"application/json"` `"application/pdf"`
`data.delta.content[].tool_results.content[].json`	objet	Si `type = "application/json"`, les données JSON renvoyées par l’outil.
`data.delta.content[].tool_results.content[].text`	string	Si `type = "text"`, les données textuelles renvoyées par l’outil.

Événement `error`¶

Champ	Type	Description
`event`	string	`error` pour les événements d’erreur.
`data`	objet	Contient les détails de l’erreur.
`data.code`	string	Le code d’erreur Snowflake. Par exemple, `"399505"`.
`data.message`	string	Une description de ce qui n’a pas fonctionné. Par exemple, `"Internal server error"`.

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?"
        }
      ]
    }
  ]
}

Copy

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"
            }
          }
        }
    ]
  }
}

Copy

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_001", // must match the previous tool use id sent back from the "assistant" role
          "name": "sql_execution_tool", // must match the name of the sql_exec tool previously sent in the request
          "content": [{
            "type": "json",
            "json": {
              "query_id": "01bcfcde-0100-0001-0000-000000102549"
            }
          }]
    }
  ]
}

Copy

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\"}]}}"
        }
      }
    ]
  }
}

Copy

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.

API REST des Cortex Agents¶

Exécuter l’agent¶

Requête¶

Paramètres de chemin¶

En-têtes de requête¶

Corps de requête¶

Response instruction¶

Configuration de l’outil¶

Spécifications de l’outil¶

Tool resources¶

Tool choice¶

Messages¶

Structure du contenu du message¶

Exemple de message complet¶

Réponse¶

Événement message.delta¶

Événement error¶

Exemple de déroulement d’une conversation¶

Requête d’échantillon¶

Exemple de réponse¶

Demande d’échantillons de réponses¶

Exemple de réponse¶

Limites des Cortex Agents¶

Événement `message.delta`¶

Événement `error`¶