Criar agentes¶

Estrutura do agente¶

Um agente consiste nas seguintes partes:

• O modelo base que fornece a base para o comportamento do agente

• Um modelo (o orquestrador) que interpreta a intenção, seleciona as ferramentas certas e planeja a sequência de ações

• Instruções para o comportamento do agente

• Ferramentas para o agente usar

• Recursos para as ferramentas

As seções a seguir fornecem informações sobre a seleção de modelos e a configuração de ferramentas. Este exemplo usa uma exibição semântica, um Cortex Search Service e uma ferramenta personalizada para fornecer respostas. Embora seja possível criar um agente básico que não utilize nenhuma dessas ferramentas, esse agente básico só poderá usar o modelo básico para fornecer respostas. Como resultado, o agente não tem acesso aos dados da sua conta Snowflake e tem contexto limitado para as respostas.

Para obter informações sobre os outros componentes do agente, consulte Cortex Agents.

Pré-requisitos¶

Para criar um Cortex Agent, você deve usar uma função com os seguintes privilégios:

O código a seguir concede os privilégios necessários para criar um Cortex Agent:

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

Copy

Além dos privilégios necessários para criar um Cortex Agent, os seguintes pré-requisitos são necessários para conectar o agente a ferramentas específicas:

• Uma exibição semântica para conectar ao agente

  Para obter informações sobre a criação de uma exibição semântica, consulte Visão geral das exibições semânticas.

• Uma ferramenta Cortex Analyst para conectar-se ao agente

  Para obter informações sobre a criação de uma ferramenta Cortex Analyst, consulte Cortex Analyst.

• Dados não estruturados em um banco de dados para conectar ao agente

• Uma ferramenta Cortex Search para conectar-se ao agente

  Para obter informações sobre a criação de uma ferramenta Cortex Search, consulte Cortex Search.

• Uma ferramenta personalizada para conectar ao agente

  Para obter informações sobre a criação de funções definidas pelo usuário (UDFs ) e procedimentos armazenados para usar como ferramentas personalizadas, consulte Como estender o Snowflake com funções e procedimentos.

Para anexar ferramentas a um agente, a função usada para criar o agente deve ter os seguintes privilégios:

Noções básicas de configuração do agente¶

Ao criar um agente, você deve especificar informações sobre o agente, como nome, descrição e modelo. Você também pode especificar as ferramentas que o agente pode usar e os recursos que o agente pode acessar. Esses recursos são passados como uma especificação YAML na cláusula FROM SPECIFICATION do comando CREATE AGENT.

As recomendações a seguir fornecem práticas recomendadas para essa configuração:

Agentes de escopo restritos: antes de adicionar ferramentas ou escrever instruções, defina por que o agente existe, a quem ele atende e a quais perguntas específicas ele deve responder. Esta etapa molda tudo o que se segue, desde a seleção de ferramentas até o desempenho e a confiança. A Snowflake recomenda que você restrinja o escopo do agente para um caso de uso específico e de alto valor.

Depois que um agente se mostrar confiável em uma área, você poderá replicar o padrão para outras. Por exemplo, você pode ter um agente para analisar os dados recentes de vendas e marketing da sua loja e outro que recomenda os melhores SKUs para oferecer ao varejista.

Selecione cuidadosamente o número de ferramentas: cada agente deve ter acesso somente às ferramentas necessárias. Para determinar isso, considere os documentos ou dados de que o agente precisa para cumprir sua finalidade. Se o agente precisar acessar dados não estruturados, use Cortex Search. Se o agente precisar acessar dados estruturados, use Cortex Analyst. Se o agente precisar de outras ferramentas, você poderá usar ferramentas personalizadas.

Escreva uma descrição útil da ferramenta: essas descrições são usadas para ajudar o agente a entender o que a ferramenta faz e como usá-la. Descrições de ferramentas obsoletas podem criar falhas em cascata e levar a “alucinações”.

Para criar uma descrição de ferramenta útil, siga estas diretrizes:

• Adicione um nome de ferramenta claro e específico que esclareça o domínio (“Cliente”, “Vendas”) e a função (“Análise”, “Pesquisa”).

• Escreva uma descrição de ferramenta orientada por propósitos que informe ao agente:

  • O que a ferramenta faz

  • Quais dados ele acessa

  • Quando usar

  • Quando NOT usar

• Seja explícito sobre as entradas esperadas da ferramenta. Entradas ambíguas em suas ferramentas levam a chamadas de ferramentas incorretas e erros.

  • Seja específico.

  • Especifique o formato de dados.

  • Forneça instruções de dados claras.

  • Forneça orientação padrão.

  • Use terminologia consistente.

Para obter mais recomendações de configuração de agente, consulte Práticas recomendadas para a criação de Cortex Agents.

Seleção do modelo¶

Ao criar um agente, recomendamos que você selecione 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. Para obter mais informações sobre os modelos disponíveis, consulte Modelos e regiões com suporte.

O exemplo a seguir mostra como especificar o modelo para o agente:

models:
  orchestration: auto

ALTER ACCOUNT SET CORTEX_ENABLED_CROSS_REGION = 'ANY_REGION';

Conectar visualizações semânticas usando o Cortex Analyst (dados estruturados)¶

O Snowflake Intelligence oferece suporte a exibições semânticas, que são um tipo de dados estruturados com instruções que informam ao agente como consultar ou interpretar os dados. Os Cortex Agents usam o Cortex Analyst para recuperar dados estruturados de exibições semânticas, convertendo solicitações de linguagem natural em consultas SQL. Os agentes podem ser roteados por vários exibições semânticas para fornecer a resposta.

Cada exibição semântica deve cobrir um conjunto semelhante de tabelas. Você pode definir padrões específicos de dados, como sempre adicionar um filtro de data para os últimos três meses se não especificado ou sempre excluir contas internas.

É possível conectar uma exibição semântica a um agente especificando a exibição semântica como parte dos recursos da ferramenta. O exemplo a seguir mostra como conectar uma exibição semântica a um agente e como especificar a ferramenta Cortex Analyst para recuperar dados estruturados da exibição semântica:

tools:
  - tool_spec:
      type: "cortex_analyst_text_to_sql"
      name: "<your cortex analyst tool name>"
      description: "<clear and specific tool description>"

tool_resources:
  <your cortex analyst tool name>:
    semantic_view: "<db>.<schema>.<semantic_view>"

Conectar o Cortex Search (dados não estruturados)¶

Para processar dados não estruturados, é possível conectar uma ferramenta Cortex Search a um agente especificando a ferramenta Cortex Search na especificação YAML como parte dos recursos da ferramenta. Os serviços Cortex Search recuperam documentos e registros de fontes de dados não estruturadas usando pesquisa semântica. Os dois principais casos de uso do Cortex Search são geração aumentada de recuperação (RAG) e pesquisa empresarial. Para obter informações sobre como criar um Cortex Search Service, consulte Cortex Search. É possível também usar uma Cortex Knowledge Extension (CKE) que seja compartilhada com você.

Ao conectar uma ferramenta Cortex Search a um agente, é especialmente importante incluir as seguintes informações sobre os parâmetros e seus valores esperados:

• Tipo e formato (incluindo exemplos)

• Se é obrigatório ou opcional (com valores padrão)

• Valores ou restrições válidos (enumerações, intervalos, formatos)

• Relação com outros parâmetros (dependências, conflitos)

• Como obter o valor (especialmente para IDs)

O exemplo a seguir mostra como conectar uma ferramenta Cortex Search a um agente e como especificar a ferramenta Cortex Search na especificação YAML:

tools:
  - tool_spec:
      type: "cortex_search"
      name: "<your cortex search tool name>"
      description: "<clear and specific tool description>"

tool_resources:
  <your cortex search tool name>:
    name: "<db>.<schema>.<search_service_name>"
    max_results: "5"
    filter:
      "@eq":
        region: "North America"
    title_column: "<title_name>"
    id_column: "<column_name>"

Adicionar ferramentas personalizadas¶

O Snowflake Intelligence oferece suporte a ferramentas personalizadas, que são funções definidas pelo usuário ou procedimentos armazenados que podem ser usados para implementar lógica comercial personalizada. Você pode conectar uma ferramenta personalizada a um agente especificando a ferramenta personalizada na especificação YAML como parte dos recursos da ferramenta.

O exemplo a seguir mostra como conectar uma ferramenta personalizada a um agente e como especificar a ferramenta personalizada na especificação YAML:

tools:
  - tool_spec:
      type: "custom_tool"
      name: "<your custom tool name>"
      description: "<clear and specific tool description>"

tool_resources:
  <your custom tool name>:
    user-defined-function-argument: "argument1"

Criação de agente¶

• Combinar todas as ferramentas e componentes para criar um agente usando SQL:

  CREATE OR REPLACE AGENT <agent_name>
      COMMENT = 'agent level comment'
      PROFILE = '{"display_name": "My Business Assistant", "avatar":  "business-icon.png", "color": "blue"}'
      FROM SPECIFICATION
      $$
      models:
      orchestration: claude-4-sonnet
  
      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 questions, use Search"
      system: "You are a friendly agent that helps with business questions"
      sample_questions:
          - question: "What was our revenue last quarter?"
          answer: "I'll analyze the revenue data using our financial database."
  
      tools:
      - tool_spec:
          type: "cortex_analyst_text_to_sql"
          name: "<your cortex analyst tool name>"
          description: "<clear and specific tool description>"
      - tool_spec:
          type: "cortex_search"
          name: "<your cortex search tool name>"
          description: "<clear and specific tool description>"
      - tool_spec:
          type: "data_to_chart"
          name: "data_to_chart"
          description: "Generates visualizations from data"
  
      tool_resources:
      <your cortex analyst tool name>:
          semantic_view: "<db>.<schema>.<semantic_view>"
      <your cortex search tool name>:
          name: "<db>.<schema>.<search_service_name>"
          max_results: "5"
          filter:
          "@eq":
              region: "North America"
          title_column: "<title_name>"
          id_column: "<column_name>"
      $$;
  

  Copy

Modificando um agente existente¶

Para obter instruções sobre como modificar a configuração de um agente existente, incluindo a adição de ferramentas e a atualização de outros detalhes, consulte Adição de ferramentas.