Configuração e interação com Agents¶

Criação de agente¶

Crie um objeto de agente especificando o banco de dados e o esquema onde o agente deve estar localizado, juntamente com um nome e uma descrição para o agente. Além disso, especifique o nome de exibição, o atalho e a cor. Esses atributos são usados pelo aplicativo cliente para exibir o agente. O nome de exibição também é usado como identificador para fazer referência ao agente nas conversas.

For best practices when creating an agent, see Best Practices to Building Cortex Agents.

Os exemplos a seguir mostram como criar um objeto de agente a partir do Snowsight ou usando a API REST:

Method 1: Snowsight UIMethod 2: REST APIMethod 3: SQL

1. Faça login no Snowsight.

2. No menu de navegação, selecione AI & ML » Agents.

3. Selecione Create agent.

4. Em Agent object name, especifique um nome para o agente, que será exibido aos usuários na UI.

5. Em Display name, especifique um nome para o agente, que será exibido aos administradores na lista de agentes.

6. Selecione Create agent.

7. Envie um prompt ao agente com solicitações de conhecimento geral.

Adição de ferramentas¶

Depois de criar o agente, você precisa adicionar ferramentas e fornecer instruções sobre como orquestrar as ferramentas. Os Agents oferecem suporte aos seguintes tipos de ferramentas:

• Cortex Analyst: você especifica as exibições semânticas para que o Cortex Analyst possa usá-las para recuperar dados estruturados. Os Agents podem ser roteados por vários exibições semânticas para fornecer a resposta.

• Cortex Search: você fornece os índices do Cortex Search como ferramentas, incluindo informações relacionadas, como filtros de pesquisa, nomes de colunas e metadados. O Cortex Agent usa os índices do Cortex Search para recuperar dados não estruturados.

• Ferramentas personalizadas: você pode implementar código para uma lógica de negócios específica como um procedimento armazenado ou função definida pelo usuário (UDF). Como alternativa, você pode usar as ferramentas personalizadas para recuperar dados de seus sistemas de backend usando APIs.

Você também especifica os recursos usados por cada ferramenta. Por exemplo, no Cortex Analyst, você especifica o warehouse junto com o tempo limite para execução da consulta SQL. Da mesma forma para o Cortex Search, você especifica os filtros e nomes de colunas usados na consulta de pesquisa, juntamente com os resultados máximos na resposta da pesquisa. Para ferramentas personalizadas, você fornecerá os detalhes do warehouse.

Method 1: Snowsight UIMethod 2: REST APIMethod 3: SQL

To modify the configuration for an existing agent, follow these steps:

1. No menu de navegação, selecione AI & ML » Agents.

2. From the list of agents, select the agent that you want to modify.

   The configuration details for the agent are displayed.

3. Selecione Edit.

4. Em Description, descreva o agente e como os usuários podem interagir com ele.

5. Para adicionar perguntas de amostra que os usuários podem fazer ao agente, insira uma e selecione Add a question.

6. Selecione Tools. Adicione uma ou mais das seguintes ferramentas:

   • Para adicionar uma exibição semântica no Cortex Analyst ao agente: Esta seção pressupõe que você já tenha criado uma exibição semântica. Para obter informações sobre exibições semânticas e como criá-las, consulte Visão geral das exibições semânticas.

     1. Localize o Cortex Analyst e selecione o respectivo botão + Add.

     2. Em Name, insira um nome para a exibição semântica.

     3. Selecione Semantic view.

     4. Selecione a exibição semântica que o agente usa.

     5. Em Warehouse, selecione o warehouse que o agente usa para executar as consultas.

     6. Em Query timeout (seconds), especifique o tempo máximo em segundos que o agente aguarda para que uma consulta seja concluída antes de atingir o tempo limite.

     7. Em Description, descreva a exibição semântica.

     8. Selecione Add.

   • Para adicionar um Cortex Search Service ao agente: Esta seção pressupõe que você já tenha criado um Cortex Search Service. 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ê. Para acessar o tutorial que usa uma CKE, consulte Solução de problemas.

     1. Localize o Cortex Search Services e selecione o respectivo botão + Add.

     2. Em Name, insira um nome para o Cortex Search Service.

     3. Em Description, descreva o Cortex Search Service.

     4. Em Search service, selecione o Cortex Search Service que o agente usa.

     5. Selecione Add.

   • Para adicionar uma ferramenta personalizada ao agente: Ao adicionar ferramentas personalizadas, você estende a funcionalidade dos agentes. Com ferramentas personalizadas, o agente pode chamar procedimentos armazenados e funções que você definiu para executar ações ou fazer cálculos. Esta seção pressupõe que você já tenha criado uma ferramenta personalizada. Para obter informações sobre procedimentos e funções, consulte Como estender o Snowflake com funções e procedimentos.

     1. Localize o Custom tools e selecione o respectivo botão + Add.

     2. Em Name, insira um nome para a ferramenta personalizada.

     3. Em Resource type, selecione se a ferramenta personalizada é uma função ou um procedimento. Para obter informações de quando usar uma função ou um procedimento, consulte Escolha se deseja escrever um procedimento armazenado ou uma função definida pelo usuário.

     4. Em Custom tool identifier, selecione a função ou o procedimento existente que você quer adicionar como uma ferramenta personalizada.

     5. Os parâmetros relacionados à função ou ao procedimento aparecem automaticamente. Você pode adicionar manualmente os parâmetros para a ferramenta personalizada inserindo nome, tipo, descrição e indicando se o parâmetro é obrigatório. Você também pode modificar os parâmetros que são preenchidos automaticamente.

        Nota

        O Snowflake Cortex não oferece suporte a procedimentos armazenados e ferramentas personalizadas com um parâmetro do tipo object.

     6. Em Warehouse, selecione o warehouse que o agente usa para executar a ferramenta personalizada. Você deve selecionar um warehouse manualmente.

     7. Em Description, descreva a ferramenta personalizada e como usá-la.

     8. Selecione Add.

     9. Depois de criar a ferramenta personalizada, certifique-se de que os usuários recebam os privilégios USAGE para a função ou o procedimento que você adicionou como uma ferramenta personalizada. Ao usar procedimentos armazenados, os agentes mantêm se o procedimento é executado com os direitos do proprietário ou do chamador. Para obter informações sobre direitos do proprietário e do autor da chamada, consulte Procedimentos armazenados com direitos do chamador e direitos do proprietário.

7. Selecione Save.

Especificação da orquestração¶

Os Cortex Agents orquestram a tarefa dividindo-a em uma sequência de subtarefas e identificando a ferramenta certa para cada subtarefa. Você especifica o LLM que o agente deve usar para realizar essa orquestração. Você também pode influenciar a orquestração fornecendo instruções. Por exemplo, considere um agente criado para responder a perguntas sobre produtos de varejo. Você pode usar a instrução de orquestração "Use the search tool for all requests related to refunds" para garantir que o Agent forneça apenas detalhes da política de reembolso (usando o Cortex Search) e não calcule realmente os valores de reembolso (usando o Cortex Analyst). Você também pode especificar instruções para alinhar a resposta a uma marca ou tom, como "Always provide provide a concise response; maintain a friendly tone".

Configuração do acesso ao agente¶

GRANT USAGE ON AGENT <database_name>.<schema_name>.<agent_name> TO ROLE <role_name>;

Configuração de políticas de acesso da UI do Snowsight ou usando SQL para que os usuários possam acessar o agente. Especifique a função para fornecer acesso ao agente.

GRANT USAGE ON AGENT myagent TO ROLE test_rl;

Revisão do agente¶

Depois de criar o Agent, você poderá revisá-lo para verificar todos os parâmetros.

Teste do agente¶

Após criar o agente, você pode testá-lo para ver como ele responde às consultas do usuário. Você também pode testar o agente usando Solicitação de execução do agente com objeto de agente.

Para testar o agente, siga estas etapas:

1. Faça login no Snowsight.

2. No menu de navegação, selecione AI & ML » Agents.

3. Selecione o agente na lista de agentes.

4. Na página de detalhes do agente, insira um de consulta no Playground do agente.

5. Verifique se o agente responde à consulta conforme o esperado. Se o agente não responder como esperado, modificar a configuração do agente seguindo as etapas em Adição de ferramentas.

Interação com o agente¶

Após criar o objeto do agente, você pode integrar o agente diretamente em seu aplicativo usando a API REST. Para manter o contexto durante a interação, use um thread. O objeto do agente e o thread combinados simplificam o código do aplicativo do cliente.

curl -X POST "$SNOWFLAKE_ACCOUNT_BASE_URL/api/v2/cortex/threads" \
--header 'Content-Type: application/json' \
--header 'Accept: application/json' \
--header "Authorization: Bearer $PAT" \
--data '{
    "origin_application": <application_name>,
}'

curl -X POST "$SNOWFLAKE_ACCOUNT_BASE_URL/api/v2/databases/{database}/schemas/{schema}/agents/{name}:run" \
 --header 'Content-Type: application/json' \
 --header 'Accept: application/json' \
 --header "Authorization: Bearer $PAT" \
 --data '{
     "thread_id": <thread id for context>,
     "parent_message_id": <parent message id>,
     "messages": [
      {
         "role": "user",
         "content": [
           {
            "type": "text",
             "text": "What are the projected transportation costs for the next three quarters? "
             }
         ]
       }
     ],
     "tool_choice": {
       "type": "required",
       "name": [
         "Analyst1",
         "Search1"
       ]
     }
 }'

Coleta de feedback sobre o agente¶

Você pode coletar feedback dos usuários sobre as respostas dadas pelo agente. Esse feedback pode ajudar você a refinar o agente à medida que itera no seu caso de uso. Os usuários podem fornecer uma classificação objetivo (positivo/negativo), bem como detalhes mais subjetivos com uma mensagem. Além disso, os usuários podem classificar o feedback em uma das muitas categorias.

curl -X POST "$SNOWFLAKE_ACCOUNT_BASE_URL/api/v2/databases/<database-name>/schemas/<schema-name>/agents/<agent-name>:feedback:" \
--header 'Content-Type: application/json' \
--header 'Accept: application/json' \
--header "Authorization: Bearer $PAT" \
--data '{
    "request_id": "<request-id>",
    "positive": true
    "feedback_message": "This answer was great",
    "categories":[
        "category1", "category2", "category3"
    ],
    "thread_id": "<thread-id>"
}'

Interação sem um objeto de agente¶

Em alguns casos, você pode querer começar a usar os Cortex Agents usando agent:run sem um objeto de agente. Por exemplo, isso pode ser útil quando você deseja experimentar rapidamente um caso de uso. Para obter mais informações sobre a API REST, consulte Execução do agente sem um objeto de agente.