Categorias:: Funções de cadeia de caracteres e binários (funções de AI)

DATA_AGENT_RUN (SNOWFLAKE.CORTEX)¶

Executa um Cortex Agent e retorna a resposta como JSON.

É possível usar essa função para executar um Cortex Agent, que orquestra fontes de dados estruturadas e não estruturadas para fornecer insights. Isso inclui planejar tarefas, usar ferramentas para executar essas tarefas e gerar respostas.

Nota

SNOWFLAKE.CORTEX.DATA_AGENT_RUN é um wrapper utilitário em torno do Cortex Agents Run API. Para a maioria das integrações de aplicativos, a Snowflake recomenda chamar o streaming REST API diretamente.

Consulte também:: CREATE AGENT , SHOW AGENTS , DESCRIBE AGENT , DROP AGENT

Sintaxe¶

SNOWFLAKE.CORTEX.DATA_AGENT_RUN( '<agent_name>', <request_body> )

Copy

Argumentos¶

'agent_name'

Nome totalmente qualificado do agente a ser executado, no formato database.schema.agent_name.

request_body

Corpo da solicitação JSON a ser enviado ao agente. Esse valor deve ser uma cadeia de caracteres (por exemplo, um literal $$...$$).

Os seguintes campos são compatíveis no 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.
`stream`	booleano	Seja para retornar uma resposta de streaming (`text/event-stream`) ou uma resposta JSON sem streaming (`application/json`). Se for verdadeiro, a resposta será transmitida como eventos enviados pelo servidor. Se for falso, a resposta será retornada como JSON.
`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?"
        }
      ]
    }
  ],
  "stream": false,
  "tool_choice": {
    "type": "auto",
    "name": [
      "analyst_tool",
      "search_tool"
    ]
  }
}

Copy

Importante

O campo stream é ignorado. Uma resposta não streaming é sempre retornada.

Retornos¶

Retorna uma cadeia de caracteres JSON contendo a resposta do agente.

Requisitos de controle de acesso¶

Para executar um agente, você deve usar uma função que possa acessar os Cortex Agents e o objeto do agente que você está chamando. Para obter mais detalhes, consulte Requisitos de controle de acesso.

Notas de uso¶

A função retorna uma cadeia de caracteres JSON. Passe essa cadeia de caracteres para TRY_PARSE_JSON para converter a resposta em um valor VARIANT.

Exemplos¶

Execute um agente e analise a resposta JSON:

SELECT
  TRY_PARSE_JSON(
    SNOWFLAKE.CORTEX.DATA_AGENT_RUN(
      'MY_DB.MY_SCHEMA.MY_AGENT',
      $${
        "parent_message_id": 1234,
        "thread_id": 5678,
        "messages": [
          {
            "role": "user",
            "content": [
              { "type": "text", "text": "What are some types of products?" }
            ]
          }
        ]
      }$$
    )
  ) AS resp;

Copy

Valor de retorno de amostra:

{
  "role": "assistant",
  "content": [
    {
      "thinking": {
        "text": "\n...\n"
      },
      "type": "thinking"
    },
    {
      "tool_use": {
        "input": {
          "...": "..."
        },
        "name": "<tool_name>",
        "tool_use_id": "<tool_use_id>",
        "type": "<tool_type>"
      },
      "type": "tool_use"
    },
    {
      "text": "Based on the data available, there are two main types of products...",
      "type": "text"
    }
  ],
  "metadata": {
    "run_id": "<run_id>"
  }
}

Copy