API de execução de Cortex Agents¶

Existem dois métodos para interagir com um agente:

Criar um objeto de agente e fazer referência a ele em uma solicitação para a API agent:run.
Chamar a agent:run diretamente sem um objeto de agente. Você fornece a configuração no corpo da solicitação de agent:run.

Ambos os métodos usam APIs de streaming que respondem com os eventos enviados pelo servidor especificados em Streaming Responses.

Solicitação de execução do agente com objeto de agente¶

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

Envia uma consulta do usuário ao objeto de agente e retorna sua resposta como um fluxo de eventos.

Parâmetros de caminho¶

Parâmetro	Descrição
`database`	(Obrigatório) O banco de dados que contém o agente. Você pode usar a solicitação `/api/v2/databases` GET para obter uma lista de bancos de dados disponíveis.
`schema`	(Obrigatório) O esquema que contém o agente. Você pode usar a solicitação `/api/v2/databases/{database}/schemas` GET para obter uma lista de esquemas disponíveis para o banco de dados especificado.
`name`	(Obrigatório) O nome do agente.

Cabeçalhos de solicitação¶

Cabeçalho	Descrição
`Authorization`	Token de autorização (obrigatório). Consulte Autenticação.
`Content-Type`	Aplicativo/json (obrigatório)

Corpo da solicitação¶

Campo	Tipo	Descrição
`thread_id`	inteiro	O ID do thread da conversa. Se thread_id for usado, então parent_message_id também deve ser passado.
`parent_message_id`	inteiro	O ID da mensagem pai no thread. Se essa for a primeira mensagem, parent_message_id deve ser 0.
`messages`	Matriz de Message	Se thread_id e parent_message_id forem passados na solicitação, as mensagens incluirão a mensagem do usuário atual na conversa. Caso contrário, as mensagens incluem o histórico da conversa e a mensagem atual. As mensagens contêm consultas do usuário e respostas do assistente em ordem cronológica.
`tool_choice`	ToolChoice	Configura como o agente deve selecionar e usar as ferramentas durante a interação. Controla se o uso de ferramentas é automático, obrigatório ou se ferramentas específicas devem ser usadas.

Exemplo

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

Execução do agente sem um objeto de agente¶

POST /api/v2/cortex/agent:run

Envia uma consulta de usuário ao serviço Cortex Agents fornecido no corpo da solicitação e retorna sua resposta. Interage com o agente sem criar um objeto de agente.

Nota

Antes de 1º de setembro de 2025, os esquemas de solicitação e resposta para a API agent:run eram diferentes do esquema listado neste documento. Anteriormente, a orquestração era estática e a mesma sequência de ferramentas era usada para gerar uma resposta. agent:run agora tem um esquema atualizado tanto para a solicitação quanto para a resposta. Além disso, a API agora orquestra e itera dinamicamente para chegar à resposta final. Recomendamos usar o esquema descrito neste documento para uma melhor experiência do usuário final.

Para usar o esquema e o comportamento legados, use o seguinte esquema:

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

Copy

Cabeçalhos de solicitação¶

Cabeçalho	Descrição
`Authorization`	Token de autorização (obrigatório). Consulte Autenticação.
`Content-Type`	Aplicativo/json (obrigatório)

Corpo da solicitação¶

Campo	Tipo	Descrição
`thread_id`	inteiro	O ID do thread da conversa. Se thread_id for usado, então parent_message_id também deve ser passado.
`parent_message_id`	inteiro	O ID da mensagem pai no thread. Se essa for a primeira mensagem, parent_message_id deve ser 0.
`messages`	Matriz de Message	Se thread_id e parent_message_id forem passados na solicitação, as mensagens incluirão a mensagem do usuário atual na conversa. Caso contrário, as mensagens incluem o histórico da conversa e a mensagem atual. As mensagens contêm consultas do usuário e respostas do assistente em ordem cronológica.
`tool_choice`	ToolChoice	Configura como o agente deve selecionar e usar as ferramentas durante a interação. Controla se o uso de ferramentas é automático, obrigatório ou se ferramentas específicas devem ser usadas.
`models`	ModelConfig	Configuração do modelo para o agente. Inclui o modelo de orquestração (por exemplo, cláusula-4-sonnet). Se não for fornecido, um modelo será selecionado automaticamente. Atualmente disponível apenas para a etapa de `orquestração`.
`instructions`	AgentInstructions	Instruções para o comportamento do agente, incluindo resposta, orquestração, sistema e perguntas de amostra.
`orchestration`	OrchestrationConfig	Configuração da orquestração, incluindo restrições orçamentárias (por exemplo, segundos, tokens).
`tools`	Matriz de Tool	Lista de ferramentas disponíveis para o agente usar. Cada ferramenta inclui uma Tool_spec com tipo, nome, descrição e esquema de entrada. As ferramentas podem ter uma configuração correspondente em Tool_resources.
`tool_resources`	Mapa de ToolResource	Configuração de cada ferramenta referenciada na matriz de ferramentas. As chaves devem corresponder ao nome da respectiva ferramenta.

Exemplo

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

Respostas de streaming¶

A API agent:run fornece respostas de streaming. O servidor transmite eventos de retorno. Isso permite que você exiba as respostas em seu aplicativo, token por token, à medida que são geradas pelo Agent. Cada evento transmitido na resposta da API tem um esquema estritamente digitado. Você pode encontrar uma lista de todos os eventos na seção a seguir e selecionar quais deseja se inscrever.

O último evento enviado pela API é um evento response. Esse evento contém toda a saída do agente. Você pode usar isso como a resposta final do agente. Para qualquer cliente que não seja de streaming, você pode se inscrever nesse evento porque ele é a agregação lógica de todos os eventos anteriores. Se você não quiser usar respostas de streaming, aguarde o evento response e ignore todos os eventos anteriores.

A maioria dos outros eventos transmitidos podem ser divididos em duas categorias: Delta e Content Item.

Os eventos Delta representam um único token gerado pelo agente. Ao detectar esses eventos, você pode criar um efeito de máquina de escrever. Os principais eventos delta são response.thinking.delta, que representa um token de raciocínio, e response.text.delta, que representam um token de resposta.

Os eventos Content Item representam elementos da matriz content na resposta final do agente.

Nota

Certifique-se de que seu aplicativo possa lidar com tipos de eventos desconhecidos.

Exemplo de resposta:

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`¶

Evento transmitido quando a resposta final está disponível. Esse é o último evento emitido, ele representa a agregação de todos os outros eventos transmitidos anteriormente.

Campo	Tipo	Descrição
`role`	string	A função para a mensagem. Sempre `assistant` na resposta da API.
`content`	Matriz de MessageContentItem	O conteúdo gerado pelo agente.

Exemplo

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

Um evento transmitido quando um bloco de conteúdo de texto é feito de streaming, incluindo todos os deltas agregados para um determinado índice de conteúdo.

Campo	Tipo	Descrição
`content_index`	inteiro	O índice na matriz de conteúdo de resposta que este evento representa
`text`	string	Um resultado de texto do agente
`annotations`	Matriz de Annotation	Quaisquer anotações anexadas ao resultado de texto (por exemplo, citações)
`is_elicitation`	booleano	Se esse conteúdo de texto é o agente que solicita mais informações do usuário final.

Exemplo

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

Evento transmitido quando um novo delta de texto de saída é gerado.

Campo	Tipo	Descrição
`content_index`	inteiro	O índice na matriz de conteúdo de resposta que este evento representa
`text`	string	O texto delta
`is_elicitation`	booleano	Se esse conteúdo de texto é o agente que solicita mais informações do usuário final.

Exemplo

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

Copy

`response.text.annotation`¶

Evento transmitido quando uma anotação é adicionada a um conteúdo de texto.

Campo	Tipo	Descrição
`content_index`	inteiro	O índice na matriz de conteúdo de resposta que este evento representa
`annotation_index`	inteiro	O índice na matriz de anotação ao qual essa `annotation` pertence.
`annotation`	Annotation	O objeto de anotação que está sendo adicionado.

Exemplo

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

Um evento transmitido quando um bloco de conteúdo de raciocínio termina de transmitir, incluindo todos os deltas agregados para um índice de conteúdo específico.

Campo	Tipo	Descrição
`content_index`	inteiro	O índice na matriz de conteúdo de resposta que este evento representa
`text`	string	Tokens de raciocínio do agente

Exemplo

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

Copy

`response.thinking.delta`¶

Evento transmitido quando um delta de raciocínio é gerado.

Campo	Tipo	Descrição
`content_index`	inteiro	O índice na matriz de conteúdo de resposta que este evento representa
`text`	string	O token de raciocínio

Exemplo

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

Copy

`response.tool_use`¶

Um evento transmitido quando o agente solicita o uso de uma ferramenta.

Campo	Tipo	Descrição
`content_index`	inteiro	O índice na matriz de conteúdo de resposta que este evento representa
`tool_use_id`	string	Identificador exclusivo para esse uso de ferramenta. Pode ser usado para associar resultados de ferramenta.
`type`	string	O tipo da ferramenta (por exemplo, cortex_search, cortex_analyst_text2sql)
`name`	string	O identificador único para essa instância de ferramenta
`input`	objeto	A entrada estruturada para essa ferramenta. O esquema desse objeto deve variar de acordo com a especificação da ferramenta.
`client_side_execute`	booleano	Se o uso da ferramenta é executado no lado do cliente.

Exemplo

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

Evento transmitido quando uma ferramenta termina de ser executada, incluindo o resultado da ferramenta.

Campo	Tipo	Descrição
`content_index`	inteiro	O índice na matriz de conteúdo de resposta que este evento representa
`tool_use_id`	string	Identificador exclusivo para esse uso de ferramenta. Pode ser usado para associar resultados de ferramenta.
`type`	string	O tipo da ferramenta (por exemplo, cortex_search, cortex_analyst_text2sql)
`name`	string	O identificador único para essa instância de ferramenta
`content`	Matriz de ToolResultContent	O conteúdo no resultado da ferramenta
`status`	string	O status de execução da ferramenta

Exemplo

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

Atualização de status para um uso de ferramenta específico.

Campo	Tipo	Descrição
`tool_use_id`	string	Identificador exclusivo para esse uso de ferramenta.
`tool_type`	string	O tipo da ferramenta (por exemplo, cortex_search, cortex_analyst_text2sql)
`status`	string	Enumeração para o estado atual.
`message`	string	Uma mensagem mais descritiva expandindo o status atual.

Exemplo

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

Um evento delta transmitido para a execução da ferramenta Cortex Analyst

Campo	Tipo	Descrição
`content_index`	inteiro	O índice na matriz de conteúdo de resposta que este evento representa
`tool_use_id`	string	Identificador exclusivo para esse uso de ferramenta. Pode ser usado para associar resultados de ferramenta.
`tool_type`	string	O tipo da ferramenta (sempre cortex_analyst_text2sql para esse evento)
`tool_name`	string	O identificador único para essa instância de ferramenta
`delta`	CortexAnalystToolResultDelta	O delta de conteúdo

Exemplo

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

Um evento transmitido quando um bloco de conteúdo de tabela é adicionado.

Campo	Tipo	Descrição
`content_index`	inteiro	O índice na matriz de conteúdo de resposta que este evento representa
`tool_use_id`	string	O ID do uso da ferramenta que gerou essa tabela
`query_id`	string	O ID da consulta SQL que gerou esses dados
`result_set`	ResultSet	Os resultados de SQL para renderizar uma tabela. Corresponde ao esquema do ResultSet da API SQL do Snowflake (https://docs.snowflake.com/en/developer-guide/sql-api/reference#resultset)
`title`	string	O título dessa tabela

Exemplo

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

Um evento transmitido quando um bloco de conteúdo de gráfico é adicionado.

Campo	Tipo	Descrição
`content_index`	inteiro	O índice na matriz de conteúdo de resposta que este evento representa
`tool_use_id`	string	O ID do uso da ferramenta que gerou esse gráfico
`chart_spec`	string	A especificação do gráfico vega-lite serializada como uma string

Exemplo

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

Atualização de status da execução do agente.

Campo	Tipo	Descrição
`status`	string	Enumeração para o estado atual.
`message`	string	Uma mensagem mais descritiva expandindo o status atual.

Exemplo

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

Copy

`error`¶

Enviado quando um erro fatal é encontrado.

Campo	Tipo	Descrição
`code`	string	O código de erro do Snowflake
`message`	string	A mensagem de erro
`request_id`	string	O identificador único dessa solicitação.

Exemplo

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

Copy

Evento `metadata`¶

Metadados sobre a solicitação. Esse evento é enviado quando uma mensagem é adicionada ao thread. É útil para obter o parent_message_id para usar nas seguintes solicitações à API Agents.

Campo	Tipo	Descrição
`role`	string	Identifica quem enviou a mensagem, o usuário ou o assistente.
`message_id`	inteiro	O ID da mensagem do thread. Use esse ID (quando a função for `assistant`) para fazer uma pergunta complementar no thread.

Exemplo

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

Copy

Esquemas¶

`AgentInstructions`¶

Campo	Tipo	Descrição
`response`	string	Instruções para geração de respostas.
`orchestration`	string	Essas instruções personalizadas são usadas quando o agente está planejando quais ferramentas usar.
`system`	string	Instruções do sistema para o agente.

Exemplo

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

Campo

Tipo

Descrição

type

string

O tipo de citação (sempre cortex_search_citation)

index

inteiro

O índice da citação nos resultados da pesquisa.

search_result_id

string

O identificador único do resultado da pesquisa.

doc_id

string

O identificador único do documento.

doc_title

string

O título do documento.

text

string

O trecho de texto do documento usado como citação.

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

Campo	Tipo	Descrição
`type`	string	O tipo de citação (sempre `cortex_search_citation`)
`index`	inteiro	O índice da citação nos resultados da pesquisa.
`search_result_id`	string	O identificador único do resultado da pesquisa.
`doc_id`	string	O identificador único do documento.
`doc_title`	string	O título do documento.
`text`	string	O trecho de texto do documento usado como citação.

`BudgetConfig`¶

Campo	Tipo	Descrição
`seconds`	inteiro	Orçamento de tempo em segundos.
`tokens`	inteiro	Orçamento de token.

Exemplo

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

Copy

`ChartContent`¶

Campo	Tipo	Descrição
`tool_use_id`	string	O ID do uso da ferramenta que gerou esse gráfico
`chart_spec`	string	A especificação do gráfico vega-lite serializada como uma string

Exemplo

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

Copy

`CortexAnalystSuggestionDelta`¶

Campo	Tipo	Descrição
`index`	inteiro	O índice da matriz de sugestões que esse delta representa
`delta`	string	O delta de texto para a sugestão nesse índice

Exemplo

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

Copy

`CortexAnalystToolResultDelta`¶

Campo	Tipo	Descrição
`text`	string	Um texto delta da resposta final do Cortex Analyst.
`think`	string	Um texto delta das etapas de raciocínio do Cortex Analyst.
`sql`	string	Um delta da saída SQL do Cortex Analyst. Atualmente, toda a consulta SQL vem em um único evento, mas podemos transmitir o SQL token por token no futuro.
`sql_explanation`	string	Um delta da explicação do Cortex Analyst sobre o que a consulta SQL faz
`query_id`	string	O ID da consulta uma vez que a execução do SQL começa
`verified_query_used`	booleano	Se uma consulta verificada foi usada para gerar essa resposta
`result_set`	ResultSet	Os resultados da execução do SQL. Corresponde ao esquema do ResultSet da API SQL do Snowflake (https://docs.snowflake.com/en/developer-guide/sql-api/reference#resultset)
`suggestions`	CortexAnalystSuggestionDelta	Um delta das perguntas sugeridas pelo Cortex Analyst. Ele é enviado quando o analista não pode responder à pergunta devido à falta de informações ou outras falhas.

Exemplo

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

Configuração de ferramentas executadas pelo servidor.

Campo	Tipo	Descrição
`type`	string	O tipo de ambiente de execução, atualmente apenas `warehouse` tem suporte.
`warehouse`	string	O nome do warehouse. Se for um identificador não delimitado entre aspas, forneça o nome em letras maiúsculas.
`query_timeout`	inteiro	O tempo limite da consulta em segundos

Exemplo

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

Copy

`Message`¶

Representa uma única mensagem na conversa. Pode ser do usuário ou do assistente.

Campo	Tipo	Descrição
`role`	string	Identifica quem enviou a mensagem, o usuário ou o assistente. As mensagens do usuário geralmente contêm consultas, enquanto as mensagens do assistente contêm respostas e resultados de ferramentas.
`content`	Matriz de MessageContentItem	Conjunto de elementos de conteúdo que compõem a mensagem. Pode incluir texto, resultados de ferramentas ou tipos de conteúdo personalizados.

Exemplo

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

Copy

`MessageContentItem`¶

Campo	Tipo	Descrição
`type`	string	O tipo de conteúdo (sempre `chart`).
`chart`	ChartContent	O gráfico.

Exemplo

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

Copy

Campo	Tipo	Descrição
`type`	string	O tipo de conteúdo (sempre `table`).
`table`	TableContent	A tabela.

Exemplo

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

Campo	Tipo	Descrição
`text`	string	Um resultado de texto do agente
`annotations`	Matriz de Annotation	Quaisquer anotações anexadas ao resultado de texto (por exemplo, citações)
`is_elicitation`	booleano	Se esse conteúdo de texto é o agente que solicita mais informações do usuário final.
`type`	string	O tipo de conteúdo (sempre `text`).

Exemplo

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

Campo	Tipo	Descrição
`type`	string	O tipo de conteúdo (sempre `thinking`).
`thinking`	ThinkingContent	O conteúdo de raciocínio.

Exemplo

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

Copy

Campo	Tipo	Descrição
`type`	string	O tipo de conteúdo (sempre `tool_result`).
`tool_result`	ToolResult	O resultado da ferramenta.

Exemplo

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

Campo	Tipo	Descrição
`type`	string	O tipo de conteúdo (sempre `tool_use`).
`tool_use`	ToolUse	O uso da ferramenta.

Exemplo

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

Campo	Tipo	Descrição
`orchestration`	string	Modelo a ser usado para orquestração. Se não for fornecido, um modelo será selecionado automaticamente.

Exemplo

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

Copy

`OrchestrationConfig`¶

Campo	Tipo	Descrição
`budget`	BudgetConfig	Restrições orçamentárias para o agente. Se mais de uma restrição for especificada, o que for atingido primeiro encerrará a solicitação.

Exemplo

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

Copy

`ResultSet`¶

Campo	Tipo	Descrição
`statementHandle`	string	O ID da consulta.
`resultSetMetaData`	ResultSetMetaData	Metadados sobre o conjunto de resultados.
`data`	matriz de matriz	Matriz 2D representando os dados

Exemplo

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

Campo	Tipo	Descrição
`partition`	inteiro	O número de índice da partição.
`numRows`	inteiro	O número total de linhas de resultados.
`format`	string	Formato dos dados no conjunto de resultados.
`rowType`	Matriz de RowType	Descrição das colunas no resultado.

Exemplo

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

Copy

`RowType`¶

Campo	Tipo	Descrição
`name`	string	Nome da coluna.
`type`	string	Tipo de dados do Snowflake da coluna. (https://docs.snowflake.com/en/sql-reference/intro-summary-data-types)
`length`	inteiro	Comprimento da coluna.
`precision`	inteiro	Precisão da coluna.
`scale`	inteiro	Escala da coluna.
`nullable`	booleano	Especifica se a coluna é ou não anulável.

Exemplo

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

Copy

`TableContent`¶

Campo	Tipo	Descrição
`tool_use_id`	string	O ID do uso da ferramenta que gerou essa tabela
`query_id`	string	O ID da consulta SQL que gerou esses dados
`result_set`	ResultSet	Os resultados de SQL para renderizar uma tabela. Corresponde ao esquema do ResultSet da API SQL do Snowflake (https://docs.snowflake.com/en/developer-guide/sql-api/reference#resultset)
`title`	string	O título dessa tabela

Exemplo

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

Campo	Tipo	Descrição
`text`	string	Tokens de raciocínio do agente

Exemplo

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

Copy

`Tool`¶

Define uma ferramenta que pode ser usada pelo agente. As ferramentas fornecem capacidades específicas como análise de dados, pesquisa ou funções genéricas.

Campo	Tipo	Descrição
`tool_spec`	ToolSpec	Especificação do tipo, da configuração e dos requisitos de entrada da ferramenta.

Exemplo

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

Campo	Tipo	Descrição
`type`	string	Determina como as ferramentas são selecionadas: auto - seleção automática de ferramentas (padrão); required - deve usar pelo menos uma ferramenta; tool - usar ferramentas nomeadas específicas
`name`	matriz de string	Lista de nomes de ferramentas específicas a serem usadas quando o tipo for «tool».

Exemplo

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

Copy

`ToolInputSchema`¶

Campo	Tipo	Descrição
`type`	string	O tipo do objeto de esquema de entrada.
`description`	string	Uma descrição do que a entrada faz.
`properties`	Mapa de ToolInputSchema	Se o tipo for `object`, definições de cada parâmetro de entrada.
`items`	ToolInputSchema	Se o tipo for `array`, o esquema para os elementos da matriz.
`required`	matriz de string	Se o tipo for `object`, lista de nomes de parâmetro de entrada necessários.

Exemplo

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

Configuração da ferramenta de análise texto-para-SQL. Fornece parâmetros para geração e execução de consultas SQL. Exatamente um de semantic_model_file ou semantic_view deve ser fornecido.

Campo

Tipo

Descrição

semantic_model_file

string

O caminho para um arquivo armazenado em uma área de preparação do Snowflake com o modelo semântico yaml.

semantic_view

string

O nome do objeto do modelo semântico nativo do Snowflake.

execution_environment

ExecutionEnvironment

Configuração de como executar a consulta SQL gerada.

Exemplo
{
  "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
Configuração da funcionalidade de pesquisa. Define como a pesquisa e recuperação de documentos deve ser realizada.

Campo

Tipo

Descrição

search_service

string

O nome completo e qualificado do serviço de pesquisa.

title_column

string

A coluna de título do documento.

id_column

string

A coluna de ID do documento.

filter

objeto

Filtrar consulta para obter resultados de pesquisa.

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

Tipo

Descrição

type

string

Se a ferramenta for executada no lado do servidor, seja um procedimento armazenado ou uma UDF.

execution_environment

ExecutionEnvironment

identifier

string

Nome totalmente qualificado do procedimento armazenado ou UDF.

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

Campo	Tipo	Descrição
`semantic_model_file`	string	O caminho para um arquivo armazenado em uma área de preparação do Snowflake com o modelo semântico yaml.
`semantic_view`	string	O nome do objeto do modelo semântico nativo do Snowflake.
`execution_environment`	ExecutionEnvironment	Configuração de como executar a consulta SQL gerada.

Campo	Tipo	Descrição
`search_service`	string	O nome completo e qualificado do serviço de pesquisa.
`title_column`	string	A coluna de título do documento.
`id_column`	string	A coluna de ID do documento.
`filter`	objeto	Filtrar consulta para obter resultados de pesquisa.

Campo	Tipo	Descrição
`type`	string	Se a ferramenta for executada no lado do servidor, seja um procedimento armazenado ou uma UDF.
`execution_environment`	ExecutionEnvironment
`identifier`	string	Nome totalmente qualificado do procedimento armazenado ou UDF.

`ToolResult`¶

Campo	Tipo	Descrição
`tool_use_id`	string	Identificador exclusivo para esse uso de ferramenta. Pode ser usado para associar resultados de ferramenta.
`type`	string	O tipo da ferramenta (por exemplo, cortex_search, cortex_analyst_text2sql)
`name`	string	O identificador único para essa instância de ferramenta
`content`	Matriz de ToolResultContent	O conteúdo no resultado da ferramenta
`status`	string	O status de execução da ferramenta

Exemplo

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

Campo

Tipo

Descrição

type

string

O tipo de resultado (sempre json)

json

objeto

Saída estruturada de uma ferramenta. O esquema varia de acordo com o tipo de ferramenta.

Exemplo
{
  "type": "json",
  "json": {
    "answer": 42
  }
}
Copy
Campo

Tipo

Descrição

type

string

O tipo de resultado (sempre text)

text

string

O texto do resultado

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

Campo	Tipo	Descrição
`type`	string	O tipo de resultado (sempre `json`)
`json`	objeto	Saída estruturada de uma ferramenta. O esquema varia de acordo com o tipo de ferramenta.

Campo	Tipo	Descrição
`type`	string	O tipo de resultado (sempre `text`)
`text`	string	O texto do resultado

`ToolSpec`¶

Especificação do tipo, da configuração e dos requisitos de entrada da ferramenta.

Campo	Tipo	Descrição
`type`	string	O tipo de recurso da ferramenta. Podem ser tipos especializados como «cortex_analyst_text_to_sql» ou «generic» para ferramentas de uso geral.
`name`	string	Identificador exclusivo para referenciar esta instância de ferramenta. Usado para corresponder à configuração em tool_resources.
`description`	string	Descrição da ferramenta a ser considerada para o uso da ferramenta.
`input_schema`	ToolInputSchema	Definição do esquema JSON dos parâmetros de entrada esperados para essa ferramenta. Será alimentado ao agente para que ele saiba a estrutura que deve seguir para ao gerar a entrada para ToolUses. Obrigatório para que ferramentas genéricas especifiquem seus parâmetros de entrada.

Exemplo

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

Campo	Tipo	Descrição
`tool_use_id`	string	Identificador exclusivo para esse uso de ferramenta. Pode ser usado para associar resultados de ferramenta.
`type`	string	O tipo da ferramenta (por exemplo, cortex_search, cortex_analyst_text2sql)
`name`	string	O identificador único para essa instância de ferramenta
`input`	objeto	A entrada estruturada para essa ferramenta. O esquema desse objeto deve variar de acordo com a especificação da ferramenta.
`client_side_execute`	booleano	Se o uso da ferramenta é executado no lado do cliente.

Exemplo

{
  "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 de execução de Cortex Agents¶

Solicitação de execução do agente com objeto de agente¶

Parâmetros de caminho¶

Cabeçalhos de solicitação¶

Corpo da solicitação¶

Execução do agente sem um objeto de agente¶

Cabeçalhos de solicitação¶

Corpo da solicitação¶

Respostas de streaming¶

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¶

Evento metadata¶

Esquemas¶

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`¶

Evento `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`¶