Cortex Agents¶

Visão geral¶

Os Cortex Agents orquestram fontes de dados estruturados e não estruturados para fornecer insights. Eles planejam tarefas, usam ferramentas para executar essas tarefas e gerar respostas. Os agentes usam Cortex Analyst (estruturado) e Cortex Search (não estruturado) como ferramentas, junto com LLMs, para analisar dados. O Cortex Search extrai insights de fontes não estruturadas, enquanto o Cortex Analyst gera SQL para processar dados estruturados. Além disso, você pode usar procedimentos armazenados e funções definidas pelo usuário (UDFs) para implementar ferramentas personalizadas. Um suporte abrangente para identificação e execução de ferramentas permite a entrega de aplicativos sofisticados baseados em dados corporativos.

O fluxo de trabalho envolve quatro componentes principais:

1. Planejamento: os aplicativos geralmente alternam entre o processamento de dados de fontes estruturadas e não estruturadas. Por exemplo, considere um aplicativo de conversação projetado para responder a consultas de usuários. Um usuário comercial pode primeiro solicitar os principais distribuidores por receita (estruturado) e, em seguida, mudar para a consulta sobre um contrato (não estruturado). Os Cortex Agents podem analisar uma solicitação para orquestrar um plano e chegar à solução ou resposta.

   1. Exploração das opções: quando o usuário faz uma pergunta ambígua (por exemplo, “Fale sobre a Acme Supplies”), o agente considera diferentes permutações – produtos, local ou equipe de vendas – para desambiguar e melhorar a precisão.

   2. Divisão em subtarefas: os Cortex Agents podem dividir uma tarefa ou solicitação (por exemplo, “Quais são as diferenças entre os termos do contrato da Acme Supplies e da Acme Stationery?”) em várias partes para obter uma resposta mais precisa.

   3. Roteamento entre ferramentas: o agente seleciona a ferramenta certa – Cortex Analyst ou Cortex Search – para garantir o acesso controlado e a conformidade com as políticas da empresa.

2. Uso da ferramenta: com um plano em vigor, o agente recupera os dados de forma eficiente. O Cortex Search extrai insights de fontes não estruturadas, enquanto o Cortex Analyst gera SQL para processar dados estruturados. Um suporte abrangente para identificação e execução de ferramentas permite o fornecimento de aplicativos sofisticados baseados em dados corporativos.

3. Reflexão: após cada uso da ferramenta, o agente avalia os resultados para determinar as próximas etapas: pedir esclarecimentos, iterar ou gerar uma resposta final. Essa orquestração permite lidar com consultas de dados complexas e, ao mesmo tempo, garantir a precisão e a conformidade dentro do perímetro seguro da Snowflake.

4. Monitoramento e iteração: após a implementação, os clientes podem acompanhar as métricas, analisar o desempenho e refinar o comportamento para obter melhorias contínuas. No aplicativo cliente, os desenvolvedores podem usar TruLens para monitorar a interação do Agent. Ao monitorar e refinar continuamente os controles de governança, as empresas podem dimensionar com confiança os agentes de AI e, ao mesmo tempo, manter a segurança e a conformidade.

Para obter tutoriais que o ajudarão a começar, consulte Tutoriais dos Cortex Agents.

Requisitos de controle de acesso¶

Para fazer uma solicitação ao Cortex Agent via API agent:run, é possível usar uma função que tenha a função SNOWFLAKE.CORTEX_USER ou SNOWFLAKE.CORTEX_AGENT_USER concedida. A CORTEX_USER fornece acesso a todos os recursos de AI cobertos, incluindo Cortex Agents, enquanto a CORTEX_AGENT_USER fornece acesso ao recurso de agentes.

GRANT USAGE ON DATABASE <database_name> to ROLE <role_name>;
GRANT USAGE ON SCHEMA <database_name>.<schema_name> to ROLE <role_name>;
GRANT USAGE ON AGENT <database_name>.<schema_name>.<agent_name> to ROLE <role_name>;

Para usar Cortex Agents com um modelo semântico, você também precisa dos seguintes privilégios:

Solicitações à API Cortex Agents deve incluir um token de autorização. Para obter detalhes sobre como se autenticar na API, consulte Autenticando o Snowflake REST APIs com Snowflake. Observe que o exemplo deste tópico usa um token de sessão para se autenticar em uma conta Snowflake.

Limitação do acesso a funções específicas

Por padrão, a função CORTEX_USER é concedida à função PUBLIC. A função PUBLIC é concedida automaticamente a todos os usuários e funções. Se não quiser que todos os usuários tenham esse privilégio, você pode revogar o acesso à função PUBLIC e conceder acesso a funções específicas. Para obter mais informações, consulte Privilégios de LLM do Cortex.

Para fornecer acesso seletivo aos Cortex Agents para que apenas um subconjunto de usuários tenha acesso ao recurso, use a função CORTEX_AGENTS_USER.

Limitação do acesso usando a função de usuário de Cortex Agents

Para fornecer acesso seletivo aos Cortex Agents para usuários específicos, use a função de banco de dados SNOWFLAKE.CORTEX_AGENT_USER. Essa função inclui os privilégios necessários para chamar a API Cortex Agent.

REVOKE DATABASE ROLE SNOWFLAKE.CORTEX_USER FROM ROLE agent;

Para fornecer acesso aos Cortex Agents, use a função ACCOUNTADMIN para fazer o seguinte:

1. Concessão da função de banco de dados SNOWFLAKE.CORTEX_AGENT_USER para uma função personalizada.

2. Atribua essa função personalizada aos usuários.

O exemplo a seguir:

1. Cria a função personalizada, cortex_agent_user_role.

2. Concede a ela a função de banco de dados CORTEX_AGENT_USER.

3. Atribui essa função a example_user.

USE ROLE ACCOUNTADMIN;
CREATE ROLE cortex_agent_user_role;
GRANT DATABASE ROLE SNOWFLAKE.CORTEX_AGENT_USER TO ROLE cortex_agent_user_role;

GRANT ROLE cortex_agent_user_role TO USER example_user;

Você também pode conceder acesso aos Cortex Agents por meio das funções existentes. Por exemplo, se você tem uma função agent usada pelos agentes em sua organização, é possível conceder acesso com uma única instrução GRANT:

GRANT DATABASE ROLE SNOWFLAKE.CORTEX_AGENT_USER TO ROLE agent;

Autenticação¶

As Snowflake REST APIs oferecem suporte à autenticação por meio de tokens de acesso programático (PATs), autenticação de par de chaves usando tokens Web JSON (JWTs) e OAuth. Para obter mais detalhes, consulte Autenticando o Snowflake REST APIs com Snowflake.

Considerações sobre custo¶

Cortex Agents incur charges for the orchestration and use of tools.

• The orchestration usage is charged based on the tokens used.

• Cortex Analyst is charged per token.

• Cortex Search charges depend on the size of the index and the time it has persisted.

• Warehouse charges depend on the size of the warehouse and how long it runs.

For more information, see the Snowflake Service Consumption Table. Also, use of custom tools may incur warehouse costs.

Modelos¶

É possível usar os seguintes modelos com o Cortex Agents. Se o modelo não estiver disponível na região local, você deverá usar a inferência entre regiões.

• automático

• claude-sonnet-4-5

• claude-4-sonnet

• claude-3-7-sonnet

• claude-3-5-sonnet

• openai-gpt-5

• openai-gpt-4-1

Ao criar um agente, recomendamos selecionar auto para o modelo. Com esta opção, o Cortex seleciona automaticamente o modelo de mais alta qualidade para sua conta, e a qualidade melhora automaticamente à medida que novos modelos ficam disponíveis.

Conceitos do Cortex Agents¶

O Cortex Agents usa o Cortex Analyst, o Cortex Search e ferramentas personalizadas para planejar tarefas e gerar respostas. Você pode influenciar a orquestração com instruções. Também é possível especificar atributos para selecionar dinamicamente uma ferramenta com base na lógica de negócios.

Durante uma interação, o Agents usa um thread para manter o contexto. Um thread fornece uma fácil recuperação de todo o contexto da conversa para uso na lógica do aplicativo.

Você pode coletar feedback dos usuários finais à medida que itera e refina continuamente o agente. Um mecanismo de feedback explícito (classificação positiva/negativa) juntamente com feedback subjetivo (texto) permite capturar entradas do usuário durante todo o ciclo de vida do agente.

Interação com os agentes¶

O Cortex Agents oferece suporte a dois métodos distintos de interagir com agentes por meio da API REST:

• Configure um objeto de agente para interagir com o agente: com esse método, primeiro você configurar um objeto de agente que pode ser reutilizado para toda a interação. A configuração de um objeto agente simplifica o código do cliente e habilita o CI/CD para aplicativos prontos para empresas.

• Interagir sem um objeto de agente: com esse método, você deve passar a configuração do agente como parte de cada solicitação de interação. A interação sem um objeto de agente permite que você experimente rapidamente casos de uso e experimente diferentes cenários.

Para obter informações sobre esses métodos, consulte Configuração e interação com Agents.

Legal notices¶

Where your configuration of Cortex Agents uses a model provided on the Model and Service Flow-down Terms, your use of that model is further subject to the terms for that model on that page.

The data classification of inputs and outputs are as set forth in the following table.

For additional information, refer to AI e ML Snowflake.