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

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.

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"

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_002",
            "result": {
              "query_id": "01bbff92-0304-c8c7-0022-b7869a076c22"
            }
          }
        }
      ]
    }
  ]
}
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.