Cortex Agents REST API¶

Use esta API para simplificar a criação de um aplicativo de bate-papo interativo.

Execute o agente¶

POST <account_url>/api/v2/cortex/agent:run

Envia uma consulta do usuário ao serviço Cortex Agents fornecido no corpo de solicitação e retorna sua resposta.

Solicitação¶

Parâmetros de caminho¶

Parâmetro	Descrição
`account_url`	(Obrigatório) Seu URL da conta Snowflake. Para obter instruções sobre como localizar seu URL de conta, consulte Como encontrar o nome da conta e organização de uma conta.

Cabeçalhos de solicitação¶

Cabeçalho	Descrição
`Authorization`	Token de autorização (obrigatório). Para obter mais informações, consulte Configuração de autenticação de RESTAPI.
`Content-Type`	Aplicativo/json (obrigatório)

Corpo da solicitação¶

O corpo de solicitação contém o modelo, a instrução de resposta, os campos experimentais, as ferramentas, os recursos da ferramenta e as mensagens.

Campo	Tipo	Descrição
`model`	string	O nome do modelo usado pelo Agent para gerar uma resposta. Para obter uma lista dos modelos compatíveis, consulte Modelos compatíveis.
`response_instruction`	string	As instruções que o modelo segue ao gerar a resposta.
`experimental`	objeto	Sinalizadores experimentais passados ao agente.
`tools`	matriz	Uma matriz de especificações de ferramentas disponíveis para o agente.
`tool_resources`	objeto	Recursos necessários para as ferramentas.
`tool_choice`	objeto	A configuração usada para selecionar a ferramenta.
`messages`	matriz	Matriz de mensagens na conversa.

Instruções de resposta¶

O campo response_instruction é uma cadeia de caracteres que fornece instruções ao modelo para a geração de respostas.

Configuração da ferramenta¶

Esta seção detalha os tipos de ferramentas compatíveis, suas opções de configuração e como especificar os recursos necessários para cada ferramenta.

Especificações da ferramenta¶

O campo tools contém uma matriz de ferramentas disponíveis:

Campo	Tipo	Descrição
`tool_spec.type`	string	O tipo de ferramenta. Uma combinação de tipo e nome é um identificador exclusivo.
`tool_spec.name`	string	O nome da ferramenta. Uma combinação de tipo e nome é um identificador exclusivo.

Os valores compatíveis em tool_spec.type incluem os seguintes:

cortex_search: usado para a funcionalidade de pesquisa do Cortex
cortex_analyst_text_to_sql: usado para a conversão de texto para SQL do Cortex Analyst
sql_exec: usado para executar as consultas SQL. Você é responsável por executar a consulta SQL e fornecer os resultados como resultados da ferramenta. Para obter mais detalhes, consulte Solicitação de respostas de amostra abaixo.
data_to_chart: usado para gerar gráficos

Recursos de ferramenta¶

O objeto tool_resources fornece objetos de configuração para cada ferramenta.

tool_resources: {
    "toolName1": {configuration object for toolName1},
    "toolName2": {configuration object for toolName2},
    // ...
}

Copy

A configuração de cada tipo de ferramenta é descrita a seguir.

cortex_search

O objeto SearchName contém a configuração de uma ferramenta 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

O objeto AnalystName contém a configuração de uma ferramenta de conversão de texto para SQL do Cortex Analyst. A configuração deve incluir o modelo semântico ou a exibição a ser usada. Por exemplo:

"AnalystName": {
    // Stage path to semantic model file in `semantic_model_file`
    "semantic_model_file": "@database.schema.stage/my_semantic_model.yaml"
}

Copy

ou usando Visão geral das exibições semânticas

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

Copy

Escolha da ferramenta¶

O campo tool_choice configura o comportamento de seleção de ferramenta.

Campo	Tipo	Descrição
`type`	string	Como as ferramentas devem ser selecionadas. Valores válidos: `"auto"` ` (padrão) `"required"` (use pelo menos uma ferramenta) `"tool"` (use a ferramenta especificada)
`name`	matriz	Matriz opcional de nomes de ferramenta a serem usados. Válido somente em `type = "tool"`.

Campo

Tipo

Descrição

type

string

Como as ferramentas devem ser selecionadas.

Valores válidos:

"auto" ` (padrão)
"required" (use pelo menos uma ferramenta)
"tool" (use a ferramenta especificada)

name

matriz

Matriz opcional de nomes de ferramenta a serem usados. Válido somente em type = "tool".

Mensagens¶

A matriz messages contém o histórico de conversas entre usuário e assistente:

Campo	Tipo	Descrição
`messages[].role`	string	A função do remetente da mensagem. Valores válidos: `"system"` `"user"` `"assistant"`
`messages[].content`	matriz	Matriz de elementos de conteúdo que compõem a mensagem.

Campo

Tipo

Descrição

messages[].role

string

A função do remetente da mensagem.

Valores válidos:

"system"
"user"
"assistant"

messages[].content

matriz

Matriz de elementos de conteúdo que compõem a mensagem.

Estrutura do conteúdo da mensagem¶

A matriz content de cada mensagem pode conter vários elementos de conteúdo com tipos diferentes.

Campo	Tipo	Descrição
`messages[].content[].type`	string	O tipo de conteúdo. Valores válidos: `"text"` `"chart"` `"table"` `"tool_use"` `"tool_results"`

Campo

Tipo

Descrição

messages[].content[].type

string

O tipo de conteúdo.

Valores válidos:

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

Conteúdo do texto

Quando type é "text":

Campo	Tipo	Descrição
`messages[].content[].text`	string	O conteúdo do texto da mensagem.

Exemplo:

{
  "type": "text",
  "text": "Show me sales by region for Q1 2024"
}

Copy

Conteúdo do gráfico

Quando type é “chart”:

Campo	Tipo	Descrição
`messages[].content[].chart`	objeto	O conteúdo do gráfico da mensagem.
`messages[].content[].chart.chart_spec`	string	Gráfico como uma especificação Vega-Lite.

Exemplo:

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

Conteúdo da tabela

Quando type é “table” (tabela):

Campo	Tipo	Descrição
`messages[].content[].table`	objeto	O conteúdo da tabela da mensagem.
`messages[].content[].table.query_id`	string	O ID da consulta executada.

Exemplo:

{
  "type": "table",
  "table": {
    "query_id": "01bbff92-0304-c8c7-0022-b7869a076c22"
  }
}

Copy

Uso de ferramenta

Quando type é “tool_use”:

Campo	Tipo	Descrição
`messages[].content[].tool_use`	objeto	Contêiner para detalhes da solicitação de uso da ferramenta.
`messages[].content[].tool_use.tool_use_id`	string	Identificador exclusivo para essa solicitação de uso da ferramenta.
`messages[].content[].tool_use.name`	string	Nome da ferramenta a ser executada. Deve corresponder a um nome de ferramenta da matriz de ferramentas.
`messages[].content[].tool_use.input`	objeto	Parâmetros de entrada para a execução da ferramenta.

Exemplo:

{
  "type": "tool_use",
  "tool_use": {
    "tool_use_id": "tu_01",
    "name": "Analyst1",
    "input": {
      "query": "Show me sales by region for Q1 2024"
    }
  }
}

Copy

Resultados da ferramenta

Quando type é "tool_results":

Campo

Tipo

Descrição

messages[].content[].tool_results

objeto

Contêiner para resultados de execução de ferramenta e metadados.

messages[].content[].tool_results.tool_use_id

string

Faz referência ao tool_use_id que gerou esses resultados.

messages[].content[].tool_results.name

string

Nome da ferramenta executada. Deve corresponder a um nome de ferramenta da matriz de ferramentas.

messages[].content[].tool_results.status

string

Status de execução da ferramenta.

Valores válidos:

"success"
"error"

messages[].content[].tool_results.content

matriz

Matriz de elementos de conteúdo produzidos pela execução da ferramenta.

Pode conter elementos dos seguintes tipos:

Tipo	Campos	Descrição
`text`	`type: "text"` `text: string`	Conteúdo de texto simples retornado pela ferramenta.
`json`	`type: "json"` `json: object`	Dados JSON estruturados retornados pela ferramenta.

Exemplo:

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

Exemplo de mensagem completa¶

Este exemplo mostra uma mensagem completa com uma consulta do usuário (role é user) e uma resposta (role é assistant). A resposta inclui um evento de uso de ferramenta para uma ferramenta chamada Analyst1 e um evento de resultados de ferramenta para a mesma ferramenta.

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

Resposta¶

Ao transmitir, cada evento chega em um formato de eventos enviados pelo servidor (SSE), com os seguintes padrões principais:

Eventos message.delta incrementais para partes da saída
Eventos error incrementais se algo der errado.

Evento `message.delta`¶

Campo	Tipo	Descrição
`event`	string	`message.delta` para dados de mensagem parciais.
`data`	objeto	Contém dados de atualização incrementais.
`data.id`	string	Identificador exclusivo da mensagem.
`data.object`	string	`message.delta` ou um descritor semelhante.
`data.delta.content`	matriz	Uma lista de partes ou segmentos parciais de mensagens.
`data.delta.content[].index`	inteiro	A posição dessa parte na mensagem atual.
`data.delta.content[].type`	string	Tipo de conteúdo. Valores válidos: `"text"` `"chart"` `"table"` `"tool_use"` `"tool_results"`
`data.delta.content[].text`	string	Se `type = "text"`, a cadeia de caracteres de texto parcial.
`data.delta.content[].chart`	objeto	Se `type = "chart"`, o conteúdo do gráfico da mensagem.
`data.delta.content[].chart.chart_spec`	string	Gráfico como uma especificação Vega-Lite.
`data.delta.content[].table`	objeto	Se `type = "table"`, o conteúdo da tabela da mensagem.
`data.delta.content[].table.query_id`	string	O ID da consulta executada.
`data.delta.content[].tool_use`	objeto	Se `type = "tool_use"`, indica uma chamada de ferramenta em andamento. Contém tool_use_id, name, input.
`data.delta.content[].tool_use.tool_use_id`	string	O identificador exclusivo da chamada de ferramenta.
`data.delta.content[].tool_use.name`	string	O nome da ferramenta que está sendo chamada.
`data.delta.content[].tool_use.input`	objeto	Carga JSON para a ferramenta.
`data.delta.content[].tool_results`	objeto	Se `type = "tool_results"`, contém a saída da ferramenta.
`data.delta.content[].tool_results.tool_use_id`	string	O identificador exclusivo da saída da ferramenta.
`data.delta.content[].tool_results.status`	string	O status de execução da ferramenta. Valores válidos: `"success"` `"error"`
`data.delta.content[].tool_results.content`	matriz	Uma lista de itens que descreve os dados retornados da ferramenta.
`data.delta.content[].tool_results.content[].type`	string	O tipo de conteúdo retornado pela ferramenta. Valores válidos: `"text/csv"` `"application/json"` `"application/pdf"`
`data.delta.content[].tool_results.content[].json`	objeto	Se `type = "application/json"`, os dados JSON retornados pela ferramenta.
`data.delta.content[].tool_results.content[].text`	string	Se `type = "text"`, os dados de texto retornados pela ferramenta.

Evento `error`¶

Campo	Tipo	Descrição
`event`	string	`error` para eventos de erro.
`data`	objeto	Contém detalhes do erro.
`data.code`	string	O código de erro do Snowflake. Por exemplo, `"399505"`.
`data.message`	string	Uma descrição do que deu errado. Por exemplo, `"Internal server error"`.

Amostra de fluxo de conversa¶

Esta seção exibe uma amostra de fluxo de conversa entre um usuário e um assistente usando a Cortex Agents REST API.

Solicitação de amostra¶

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

Amostra de resposta¶

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

Solicitação de respostas de amostra¶

Os Cortex Agents podem gerar respostas textuais e gráficas com base nas consultas SQL executadas. O exemplo a seguir mostra como usar a Cortex Agents API para gerar essas respostas.

Para obter as respostas, o cliente faz uma solicitação de acompanhamento à Cortex Agent API com o query_id do SQL executado no lado do cliente. O SQL a ser executado é fornecido no evento tool_use do tipo de ferramenta sql_exec na última mensagem de resposta.

As solicitações devem usar as ferramentas cortex_analyst_text_to_sql e sql_exec para obter a resposta textual e, além disso, devem usar a ferramenta data_to_chart para obter a resposta do gráfico. Os gráficos são retornados somente se o agente decidir que os gráficos são uma boa maneira de apresentar a resposta.

Nota

Para conjuntos de resultados com mais de 4 mil células, uma resposta table é retornada em vez das respostas text e 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

Amostras de respostas¶

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

Limitações dos Cortex Agents¶

Como os aplicativos Streamlit in Snowflake (SiS) são executados conforme os direitos do proprietário, não há suporte para a execução de instruções SQL nos aplicativos SiS.
Não há suporte para os modelos do Azure OpenAI.

Cortex Agents REST API¶

Execute o agente¶

Solicitação¶

Parâmetros de caminho¶

Cabeçalhos de solicitação¶

Corpo da solicitação¶

Instruções de resposta¶

Configuração da ferramenta¶

Especificações da ferramenta¶

Recursos de ferramenta¶

Escolha da ferramenta¶

Mensagens¶

Estrutura do conteúdo da mensagem¶

Exemplo de mensagem completa¶

Resposta¶

Evento message.delta¶

Evento error¶

Amostra de fluxo de conversa¶

Solicitação de amostra¶

Amostra de resposta¶

Solicitação de respostas de amostra¶

Amostras de respostas¶

Limitações dos Cortex Agents¶

Evento `message.delta`¶

Evento `error`¶