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

AGENT_RUN (SNOWFLAKE.CORTEX)¶

Executa um Cortex Agent sem um objeto de agente e retorna a resposta como JSON.

É possível usar essa função para interagir diretamente com Cortex Agents sem primeiro criar um objeto de agente. Você fornece a configuração, incluindo o modelo de orquestração e as ferramentas, no corpo da solicitação.

Nota

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

Sintaxe¶

SNOWFLAKE.CORTEX.AGENT_RUN( <request_body> )

Argumentos¶

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.
`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?"
        }
      ]
    }
  ],
  "stream": false,
  "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"
    }
  }
}

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 Cortex Agents. 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.
Ao contrário de DATA_AGENT_RUN (SNOWFLAKE.CORTEX), essa função não exige que você crie um objeto de agente primeiro. Em vez disso, você fornece a configuração diretamente no corpo da solicitação.

Exemplos¶

Execute um agente e analise a resposta JSON:

SELECT
  TRY_PARSE_JSON(
    SNOWFLAKE.CORTEX.AGENT_RUN(
      $${
        "messages": [
          {
            "role": "user",
            "content": [
              {
                "type": "text",
                "text": "What is the total revenue for 2025?"
              }
            ]
          }
        ],
        "models": {
          "orchestration": "claude-4-sonnet"
        }
      }$$
    )
  ) AS resp;

Valor de retorno de amostra:

{
  "content": [
    {
      "text": "The total revenue for 2025 was $100,000.",
      "type": "text"
    }
  ],
  "metadata": {
    "usage": {
      "tokens_consumed": [
        {
          "context_window": 200000,
          "input_tokens": {
            "cache_read": 0,
            "cache_write": 0,
            "total": 67,
            "uncached": 67
          },
          "model_name": "claude-4-sonnet",
          "output_tokens": {
            "total": 38
          }
        }
      ]
    }
  },
  "role": "assistant"
}