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.

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 obrigatórios.

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¶

Na versão preliminar, o Cortex Agents não tem nenhuma consideração de custo além daquelas associadas às funcionalidades subjacentes do Cortex Search e do Cortex Analyst. Os serviços Cortex Search e Cortex Analyst incorrem em custos de acordo com os detalhes listados na tabela de consumo de serviços do Snowflake. Além disso, o uso de ferramentas personalizadas pode gerar custos de warehouse.

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.

• claude-4-sonnet

• claude-3-7-sonnet

• claude-3-5-sonnet

• openai-gpt-5

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.