Cortex Agents¶

Os Cortex Agents orquestram fontes de dados estruturadas e não estruturadas para fornecer insights. Eles planejam tarefas, usam ferramentas para executar essas tarefas e geram respostas. Os Agents usam o Cortex Analyst (estruturado) e o Cortex Search (não estruturado) como ferramentas, juntamente com o LLMs, para analisar os dados. 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.

O fluxo de trabalho envolve quatro componentes principais:

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.
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.
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.
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.

Nota

Embora a Snowflake se esforce para fornecer respostas de alta qualidade, a precisão das respostas do LLM ou as citações fornecidas não são garantidas. Você deve revisar todas as respostas da Agents API antes de apresentá-las aos seus usuários.

Requisitos de controle de acesso¶

O usuário que faz a consulta deve ter:

USAGE no Cortex Search Service referenciado na consulta.
USAGE no banco de dados, no esquema e nas tabelas referenciadas no modelo semântico do Cortex Analyst
Uma função com a função de banco de dados CORTEX_USER concedida. Para obter mais informações, consulte Privilégios obrigatórios.

Como usar a API do Agent¶

Esta seção mostra as etapas para criar um agente usando API do Agent.

Configuração de autenticação de RESTAPI¶

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.

Crie um modelo semântico para o Cortex Analyst¶

Você pode usar o Cortex Analyst para criar consultas SQL a partir de linguagem natural. Para usar o Cortex Analyst, você deve criar um modelo semântico. Para obter mais informações, consulte Criar um modelo semântico.

Crie um Cortex Search Service¶

Use o Cortex Search para pesquisar seus dados. Para obter mais informações, consulte CREATE CORTEX SEARCH SERVICE.

Nota

O DEFAULT_ROLE do usuário que faz a consulta deve ter o privilégio USAGE no Cortex Search Service, bem como no banco de dados e no esquema em que ele reside.

Chamando a API¶

Primeiro, localize o URL de sua conta Snowflake. Depois de obter o URL e o PAT, você pode consultar a API do Agent na linha de comando com cURL, usando a seguinte sintaxe:

curl -X POST "$SNOWFLAKE_ACCOUNT_BASE_URL/api/v2/cortex/agent:run" \
--header 'Content-Type: application/json' \
--header 'Accept: application/json' \
--header "Authorization: Bearer $PAT" \
--data '{
    "model": "llama3.1-70b",
    "messages": [
        {
            "role": "user",
            "content": [
                {
                    "type": "text",
                    "text": "what are the top 3 customers by revenue"
                }
            ]
        }
    ],
    "tools": [
        {
            "tool_spec": {
                "type": "cortex_search",
                "name": "transcript_search"
            }
        },
        {
            "tool_spec": {
                "type": "cortex_analyst_text_to_sql",
                "name": "data_model"
            }
        }
    ],
    "tool_resources": {
        "transcript_search": {"name": "testdb.testschema.transcript_search_service"},
        "data_model": {"semantic_model_file": "@testdb.testschema.stage/sample_data_model.yaml"}
    }
}'

Copy

A resposta é transmitida de forma incremental ao cliente.

Modelos compatíveis¶

Você pode usar os seguintes modelos com os Cortex Agents para gerar a resposta. Observe que o modelo não é usado para orquestração.

llama3.1-70b
llama3.3-70b
mistral-large2
claude-3-5-sonnet

Você também pode especificar uma instrução de resposta para personalizar as respostas do agente.

{
    "response_instruction": "You will always maintain a friendly tone and provide concise response"
}

Copy

Importante

Os Cortex Agents usam modelos que podem não estar disponíveis em todas as regiões. Para obter mais informações, consulte Disponibilidade.

Disponibilidade de região¶

O recurso dos Cortex Agents está disponível nas seguintes regiões:

Função (Modelo)	AWS US West 2 (Oregon)	AWS US East 1 (N. Virginia)	AWS Europe Central 1 (Frankfurt)	AWS Europe West 1 (Ireland)	AWS AP Southeast 2 (Sidney)	AWS AP Northeast 1 (Tokyo)	Azure East US 2 (Virginia)	Azure West Europe (Países Baixos)	AWS (Entre regiões)
COMPLETE (`claude-3-5-sonnet`)	✔	✔							✔
COMPLETE (`llama3.2-1b`)	✔								✔
COMPLETE (`llama3.2-3b`)	✔								✔
COMPLETE (`llama3.1-8b`)	✔	✔	✔	✔		✔	✔	✔	✔
`llama3.1-70b`	✔	✔	✔	✔	✔	✔	✔	✔	✔
`llama3.3-70b`	✔					✔			✔
`snowflake-llama-3.3-70b`	✔								✔
`llama3.1-405b`	✔	✔					✔		✔
`snowflake-llama-3.1-405b`	✔								✔
`snowflake-arctic`	✔						✔		✔
`deepseek-r1`									✔
`reka-core`		✔							✔
`reka-flash`	✔	✔				✔			✔
`mistral-large2`	✔	✔	✔	✔	✔	✔	✔	✔	✔
`mixtral-8x7b`	✔	✔	✔	✔	✔	✔	✔	✔	✔
`mistral-7b`	✔	✔	✔	✔	✔	✔	✔	✔	✔
`jamba-instruct`	✔		✔			✔			✔
`jamba-1.5-mini`	✔		✔			✔			✔
`jamba-1.5-large`	✔								✔
`gemma-7b`	✔	✔	✔				✔	✔	✔
`e5-base-v2`	✔	✔	✔			✔	✔	✔	✔
`snowflake-arctic-embed-m`	✔	✔	✔	✔	✔	✔	✔	✔	✔
`snowflake-arctic-embed-m-v1.5`	✔	✔	✔	✔	✔	✔	✔	✔	✔
`snowflake-arctic-embed-l-v2.0`	✔	✔	✔	✔	✔	✔	✔	✔	✔
`nv-embed-qa-4`	✔								✔
`multilingual-e5-large`	✔	✔	✔	✔	✔	✔	✔	✔	✔
`voyage-multilingual-2`	✔	✔	✔	✔	✔	✔	✔	✔	✔

Considerações sobre custo¶

Na visualização, os serviços Cortex Search incorrem em custos de acordo com os detalhes listados na Snowflake Service Consumption Table.

Crie um Cortex Agent¶

Usaremos os Cortex Agents para habilitar um aplicativo de conversação que responda a perguntas de usuários corporativos sobre termos de contratos. Vamos analisar os principais componentes. (Para obter o tutorial completo, consulte Introdução aos Cortex Agents).

Etapa 1. Especifique as ferramentas que deseja usar na solicitação

{
    "tools": [
        {
            "tool_spec": {
                "name": "data_model",
                "type": "cortex_analyst_text_to_sql"
            }
        },
        {
            "tool_spec": {
                "name": "transcript_search",
                "type": "cortex_search"
            }
        },
        {
            "tool_spec": {
                "type": "sql_exec",
                "name": "sql_exec"
            }
        },
        {
            "tool_spec": {
                "type": "data_to_chart",
                "name": "data_to_chart"
            }
        }
    ]
}

Copy

Etapa 2. Forneça argumentos estáticos (recursos) para as ferramentas que o Cortex Agent pode usar para chamar ferramentas.

{
    "tool_resources": {
        "data_model": {
            "semantic_model_file": "@cortex_tutorial_db.public.revenue_semantic_model.yaml"
        },
        "transcript_search": {
            "name": "cortex_tutorial_db.public.contract_terms",
            "max_results": 5,
            "title_column": "TRANSCRIPT_TITLE",
            "id_column": "TRANSCRIPT_ID",
            "filter": {"@eq": {"TRANSCRIPT_TYPE": "ENTERPRISE"} }
        }
    }
}

Copy

Etapa 3. Agora, vamos especificar o modelo e o prompt do sistema para gerar a resposta

{
    "model": "claude-3-5-sonnet",
    "messages": [
        {
            "role": "system",
            "content": {
                "type": "text",
                "text": "You’re a friendly assistant to answer questions."
            }
        }
    ]
}

Copy

Etapa 4. Crie um arquivo de modelo semântico que será usado pela ferramenta Analyst para acessar dados estruturados

Siga as etapas de 1 a 3 deste guia para criar um modelo semântico do Cortex Analyst: Introdução aos Cortex Agents

Etapa 5. Em seguida, configuramos o serviço de pesquisa para que a ferramenta de pesquisa acesse dados não estruturados

Siga as etapas de 4 a 5 deste guia para criar o Cortex Search Service: Introdução aos Cortex Agents

Etapa 6. Agora estamos prontos para interagir com o Agent. Você usará o campo de mensagens para enviar solicitações e receber respostas

{
    "model": "claude-3-5-sonnet",
    "messages": [
        {
            "role": "system",
            "content": [
                {
                    "type": "text",
                    "text": "You’re a friendly assistant to answer questions"
                }
            ]
        },
        {
            "role": "user",
            "content": [
                {
                    "type": "text",
                    "text": "hello"
                }
            ]
        },
        {
            "role": "assistant",
            "content": [
                {
                    "type": "text",
                    "text": "hi there!"
                }
            ]
        },
        {
            "role": "user",
            "content": [
                {
                    "type": "text",
                    "text": "..."
                }
            ]
        }
    ]
}

Copy

Etapa 7. À medida que a interação prossegue, o Agent identifica as ferramentas e as executa (lado do serviço) para cumprir a tarefa. No exemplo abaixo, o Agent identifica Text2SQL como a ferramenta e executa para obter a consulta SQL. Durante a interação, o Agent pode solicitar o uso de uma ferramenta para o aplicativo cliente (lado do cliente). Por exemplo, o Agent especifica a consulta SQL que deve ser executada.

{
    "role": "assistant",
    "content": [
        {
            "type": "tool_use",
            "tool_use": {
                "tool_use_id": "tool_001",
                "name": "cortex_analyst_text_to_sql",
                "input": {
                    "query": "...",
                    "semantic_model_file": "..."
                }
            }
        },
        {
            "type": "tool_results",
            "tool_results": {
                "status": "success",
                "tool_use_id": "tool_001",
                "content": [
                    {
                        "type": "json",
                        "json": {
                            "sql": "select * from table"
                        }
                    }
                ]
            }
        },
        {
            "type": "tool_use",
            "tool_use": {
                "tool_use_id": "tool_002",
                "name": "sql_exec",
                "input": {
                    "sql": "select * from table"
                }
            }
        }
    ]
}

Copy