Cortex Agents REST API¶

É possível usar a API REST Cortex Agent para criar, gerenciar e interagir com os objetos Cortex Agent em sua conta Snowflake.

Criação do Cortex Agent¶

POST /api/v2/databases/{database}/schemas/{schema}/agents

Cria um novo objeto Cortex Agent com os atributos e especificação especificados.

Solicitação¶

Parâmetros de caminho¶

Parâmetro	Descrição
`database`	(Obrigatório) URL da sua conta Snowflake.
`schema`	(Obrigatório) Identificador do esquema.

Parâmetros de consulta¶

Parâmetro	Descrição
`createMode`	(Opcional) Modo de criação de recurso. Valores válidos: `errorIfExists` `orReplace` `ifNotExists`

Parâmetro

Descrição

createMode

(Opcional) Modo de criação de recurso. Valores válidos:

errorIfExists

orReplace

ifNotExists

Cabeçalhos de solicitação¶

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

Corpo da solicitação¶

Campo	Tipo	Descrição
`name`	string	Nome do agente.
`comment`	string	Comentário opcional sobre o agente.
`profile`	AgentProfile	Informações de perfil do agente (nome de exibição, avatar, cor etc.).
`models`	ModelConfig	Configuração do modelo para o agente. Inclui o modelo de orquestração (por exemplo, claude-4-sonnet). Se não for fornecido, um modelo será selecionado automaticamente. Atualmente disponível apenas para a etapa `orchestration`.
`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

{
  "name": "MY_AGENT",
  "comment": "An agent to answer questions about all my data",
  "profile": {
    "display_name": "My Agent"
  },
  "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

Resposta¶

Uma resposta bem-sucedida retorna um objeto JSON com detalhes sobre o status da criação do Cortex Agent.

Corpo da resposta¶

{"status": "Agent xxxx successfully created."}

Copy

Descrição do Cortex Agent¶

GET /api/v2/databases/{database}/schemas/{schema}/agents/{name}

Descreve um Cortex Agent.

Solicitação¶

Parâmetros de caminho¶

Parâmetro	Descrição
`database`	(Obrigatório) Identificador do banco de dados ao qual o recurso pertence. Você pode usar a solicitação /api/v2/databases GET para obter uma lista de bancos de dados disponíveis.
`schema`	Identificador (obrigatório) do esquema ao qual o recurso pertence. É possível 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) Identificador do agente.

Cabeçalhos de solicitação¶

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

Resposta¶

Uma resposta bem-sucedida retorna um objeto JSON que descreve o Cortex Agent.

Cabeçalhos de resposta¶

Cabeçalho	Descrição
`X-Snowflake-Request-ID`	ID único da solicitação da API.
`Link`	Links para a página de resultados (por exemplo, a primeira página, a última página, etc.). O cabeçalho pode incluir vários entradas url com diferentes valores do atributo rel que especificam a página a retornar (primeiro, próximo, anterior e último).

Corpo da resposta¶

O corpo da resposta contém os detalhes do Cortex Agent.

{
  "agent_spec": "{\"models\":{\"orchestration\":\"llama3.1-70B\"},\"experimental\":{\"foo\":\"bar\",\"nested\":{\"key\":\"value\"}},\"orchestration\":{\"budget\":{\"seconds\":30,\"tokens\":16000}},\"instructions\":{\"response\":\"You will respond in a friendly but concise manner\",\"orchestration\":\"For any revenue question use Analyst; for policy use Search\",\"system\":\"You are a friendly agent.\",\"sample_questions\":[{\"question\":\"question 1\"},{\"question\":\"question 2\"},{\"question\":\"question 3\"}]},\"tools\":[{\"tool_spec\":{\"type\":\"cortex_analyst_text_to_sql\",\"name\":\"Analyst1\",\"description\":\"test\"}},{\"tool_spec\":{\"type\":\"cortex_analyst_sql_exec\",\"name\":\"SQL_exec1\"}},{\"tool_spec\":{\"type\":\"cortex_search\",\"name\":\"Search1\"}},{\"tool_spec\":{\"type\":\"web_search\",\"name\":\"web_search_1\"}},{\"tool_spec\":{\"type\":\"generic\",\"name\":\"get_weather\",\"input_schema\":{\"type\":\"object\",\"properties\":{\"location\":{\"type\":\"string\",\"description\":\"The city and state\"}},\"required\":[\"Location\"]}}}],\"tool_unable_to_answer\":\"I don't know the answer to that\",\"tool_resources\":{\"Analyst1\":{\"semantic_model_file\":\"stage1\"},\"Analyst2\":{\"semantic_view\":\"db.schema.semantic_view\"},\"Search1\":{\"name\":\"db.schema.service_name\",\"Max_results\":\"5\",\"filter\":{\"@eq\":{\"region\":\"North America\"}},\"Title_column\":\"<title_name>\",\"ID_column\":\"<column_name>\"},\"SQL_exec1\":{\"Name\":\"my_warehouse\",\"Timeout\":\"30\",\"AutoExecute\":\"true\"},\"web_search\":{\"name\":\"web_search_1\",\"Function\":\"db/schema/search_web\"}}}",
  "name": "MY_AGENT1",
  "database_name": "TEST_DATABASE",
  "schema_name": "TEST_SCHEMA",
  "owner": "ACCOUNTADMIN",
  "created_on": "1967-06-23T07:00:00.123+00:00"
}

Copy

Atualização do Cortex Agent¶

PUT /api/v2/databases/{database}/schemas/{schema}/agents/{name}

Atualiza um Cortex Agent existente com os atributos e especificação definidos.

Solicitação¶

Parâmetros de caminho¶

Parâmetro	Descrição
`database`	(Obrigatório) URL da sua conta Snowflake. Você pode usar a solicitação `/api/v2/databases` GET para obter uma lista de bancos de dados disponíveis.
`schema`	(Obrigatório) Identificador do esquema. 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) Nome do agente.

Cabeçalhos de solicitação¶

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

Corpo da solicitação¶

Campo	Tipo	Descrição
`comment`	string	Comentário opcional sobre o agente.
`profile`	AgentProfile	Informações de perfil do agente (nome de exibição, avatar, cor etc.).
`models`	ModelConfig	Configuração do modelo para o agente. Inclui o modelo de orquestração (por exemplo, claude-4-sonnet). Se não for fornecido, um modelo será selecionado automaticamente. Atualmente disponível apenas para a etapa `orchestration`.
`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

{
  "comment": "An agent to answer questions about all my data",
  "profile": {
    "display_name": "My Agent"
  },
  "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

Resposta¶

Uma resposta bem-sucedida retorna um objeto JSON com detalhes sobre o status da atualização do Cortex Agent.

Corpo da resposta¶

{"status": "Agent xxxx successfully updated."}

Copy

Listagem de Cortex Agents¶

GET /api/v2/databases/{database}/schemas/{schema}/agents

Lista os Cortex Agents no banco de dados e esquema especificados.

Solicitação¶

Parâmetros de caminho¶

Parâmetro	Descrição
`database`	(Obrigatório) Identificador do banco de dados ao qual o recurso pertence. Você pode usar a solicitação /api/v2/databases GET para obter uma lista de bancos de dados disponíveis.
`schema`	Identificador (obrigatório) do esquema ao qual o recurso pertence. É possível usar a solicitação /api/v2/databases/{database}/schemas GET para obter uma lista de esquemas disponíveis para o banco de dados especificado.

Parâmetros de consulta¶

Parâmetro	Descrição
`like`	(Opcional) Filtrar a saída pelo nome do recurso. Usa um padrão que não diferencia maiúsculas e minúsculas com suporte para caracteres curinga SQL.
`fromName`	(Opcional) Habilite a busca de linhas seguindo apenas a primeira linha cujo nome do objeto corresponde à string especificada. Diferencia maiúsculas e minúsculas e não precisa ser o nome completo.
`showLimit`	(Opcional) Limite o número máximo de linhas retornadas pelo comando. Mínimo: 1. Máximo: 10000.

Cabeçalhos de solicitação¶

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

Resposta¶

Uma resposta bem-sucedida retorna uma matriz JSON de recursos do Cortex Agent.

Cabeçalhos de resposta¶

Cabeçalho	Descrição
`X-Snowflake-Request-ID`	ID único da solicitação da API.
`Link`	Links para a página de resultados (por exemplo, a primeira página, a última página, etc.). O cabeçalho pode incluir vários entradas url com diferentes valores do atributo rel que especificam a página a retornar (primeiro, próximo, anterior e último).

Corpo da resposta¶

[
 {
  "name": "my_agent",
  "database": "TEST_DB",
  "schema": "TEST_SCHEMA",
  "created_on": "2024-06-01T12:00:00Z",
  "owner": "ACCOUNTADMIN",
  "comment": "Sample agent"
 },
 {
  "name": "another_agent",
  "database": "TEST_DB",
  "schema": "TEST_SCHEMA",
  "created_on": "2024-06-02T08:30:00Z",
  "owner": "SYSADMIN",
  "comment": ""
 }
]

Copy

Exclusão do Cortex Agent¶

DELETE /api/v2/databases/{database}/schemas/{schema}/agents/{name}

Exclui um Cortex Agent com o nome especificado. Se o parâmetro ifExists for definido como true, a operação será bem-sucedida mesmo que o agente não exista. Caso contrário, a operação falhará se não for possível excluir o agente.

Solicitação¶

Parâmetros de caminho¶

Parâmetro	Descrição
`database`	(Obrigatório) Identificador do banco de dados ao qual o recurso pertence. Você pode usar a solicitação /api/v2/databases GET para obter uma lista de bancos de dados disponíveis.
`schema`	Identificador (obrigatório) do esquema ao qual o recurso pertence. É possível 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) Identificador do agente.

Parâmetros de consulta¶

Parâmetro	Descrição
`ifExists`	(Opcional) Especifica como tratar a solicitação se o agente não existir. `true`: o ponto de extremidade não gera um erro se o agente não existir. Ele retorna uma resposta de sucesso 200, mas não executa nenhuma ação. `false`: o ponto de extremidade gera um erro se o agente não existir.

Parâmetro

Descrição

ifExists

(Opcional) Especifica como tratar a solicitação se o agente não existir.

true: o ponto de extremidade não gera um erro se o agente não existir. Ele retorna uma resposta de sucesso 200, mas não executa nenhuma ação.
false: o ponto de extremidade gera um erro se o agente não existir.

Cabeçalhos de solicitação¶

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

Resposta¶

Uma resposta bem-sucedida retorna uma mensagem de confirmação.

Corpo da resposta¶

{
 "status": "Request successfully completed"
}

Copy

Esquemas¶

`AgentInstructions`¶

Campo	Tipo	Descrição
`response`	string	Instruções para geração de respostas.
`orchestration`	string	Estas 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

`AgentProfile`¶

As informações de perfil de um Data Cortex Agent.

Campo	Tipo	Descrição
`display_name`	string	Nome de exibição do agente.

Exemplo

{
  "display_name": "My Agent"
}

Copy

`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

`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

`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

`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

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

`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

Cortex Agents REST API¶

Criação do Cortex Agent¶

Solicitação¶

Parâmetros de caminho¶

Parâmetros de consulta¶

Cabeçalhos de solicitação¶

Corpo da solicitação¶

Resposta¶

Corpo da resposta¶

Descrição do Cortex Agent¶

Solicitação¶

Parâmetros de caminho¶

Cabeçalhos de solicitação¶

Resposta¶

Cabeçalhos de resposta¶

Corpo da resposta¶

Atualização do Cortex Agent¶

Solicitação¶

Parâmetros de caminho¶

Cabeçalhos de solicitação¶

Corpo da solicitação¶

Resposta¶

Corpo da resposta¶

Listagem de Cortex Agents¶

Solicitação¶

Parâmetros de caminho¶

Parâmetros de consulta¶

Cabeçalhos de solicitação¶

Resposta¶

Cabeçalhos de resposta¶

Corpo da resposta¶

Exclusão do Cortex Agent¶

Solicitação¶

Parâmetros de caminho¶

Parâmetros de consulta¶

Cabeçalhos de solicitação¶

Resposta¶

Corpo da resposta¶

Esquemas¶

AgentInstructions¶

AgentProfile¶

BudgetConfig¶

ExecutionEnvironment¶

ModelConfig¶

OrchestrationConfig¶

Tool¶

ToolInputSchema¶

ToolResource¶

ToolSpec¶

`AgentInstructions`¶

`AgentProfile`¶

`BudgetConfig`¶

`ExecutionEnvironment`¶

`ModelConfig`¶

`OrchestrationConfig`¶

`Tool`¶

`ToolInputSchema`¶

`ToolResource`¶

`ToolSpec`¶