Desenvolver uma solução de RAG baseada em agentes

Em um pipeline padrão de RAG (geração aumentada por recuperação), o orquestrador segue uma sequência fixa. Ele aceita uma consulta de usuário, executa uma pesquisa, monta o contexto e chama o modelo de idioma. O orquestrador não decide se deseja pesquisar, quais índices consultar ou quantas etapas de recuperação devem ser tomadas. Você toma essas decisões ao projetar a solução.

O Agentic RAG muda esse modelo. Em vez de um pipeline fixo, um agente de IA trata a recuperação como uma ferramenta que pode invocar sob demanda. O agente raciocina sobre a solicitação do usuário, decide quais ferramentas chamar, avalia os resultados intermediários e itera até ter contexto suficiente para produzir uma resposta fundamentada. Essa abordagem permite o raciocínio em várias etapas, o planejamento dinâmico de consultas e a coordenação entre fontes de dados heterogêneas.

Este artigo descreve quando o RAG agente adiciona valor que o RAG padrão não pode fornecer, como estruturar a recuperação como chamadas de ferramenta e como implementar esse padrão usando Microsoft Agent Framework e o Foundry Agent Service.

Este artigo faz parte de uma série. Leia a introdução.

Quando usar o RAG agêntico

O RAG padrão funciona bem para consultas que correspondem a uma única busca em um único índice. Mas alguns cenários vão além do que um pipeline fixo consegue lidar. Considere o RAG agêntico quando sua carga de trabalho tiver:

• Raciocínio de várias etapas. A consulta do usuário requer que o agente colete informações de uma fonte, analise o resultado e, em seguida, consulte uma fonte diferente com base nessa análise. Por exemplo, um usuário pergunta "Quais dos nossos SKUs de produto têm recalls abertos nos últimos 90 dias?" O agente primeiro recupera a lista de SKUs de um catálogo interno e, em seguida, pesquisa um banco de dados regulatório para cada SKU.

• Seleção de origem dinâmica. O agente deve escolher em runtime qual fonte de dados consultar. A pergunta de um analista financeiro pode exigir dados de mercado de uma API, relatórios de ganhos internos de um índice de pesquisa e arquivos regulatórios de um repositório de documentos. O agente decide quais fontes são relevantes em vez de consultar todas elas.

• Decomposição de consulta. Perguntas complexas precisam ser divididas em consultas subsequentes. Uma solicitação como "Comparar o SLA de confiabilidade de nossas implantações do Leste dos EUA e da Europa Ocidental" requer duas pesquisas independentes e uma etapa de comparação. O agente decompõe a consulta e executa cada parte separadamente.

• Refinamento iterativo. A primeira etapa de recuperação pode não fornecer contexto suficiente. O agente avalia os resultados, identifica lacunas e executa mais consultas com termos ou filtros refinados.

• Ação e recuperação no mesmo fluxo de trabalho. O agente coleta informações e toma medidas. Por exemplo, um agente de suporte recupera o histórico de pedidos de um cliente e, em seguida, inicia um retorno por meio de uma API separada.

Se suas consultas forem simples o suficiente para que uma única pesquisa em um único índice possa resolvê-las, o RAG padrão será o melhor ajuste. Cada etapa de raciocínio do agente adiciona latência, consumo de token e complexidade. Use o RAG agente quando o raciocínio e a flexibilidade justificarem esses custos.

Arquitetura

Os diagramas a seguir comparam um pipeline RAG padrão e uma arquitetura de RAG agêntico.

RAG Padrão:

O diagrama é rotulado como RAG padrão (pipeline fixo). Ele contém seis caixas organizadas em uma linha. Da esquerda para a direita, as caixas são rotuladas como consulta do usuário, orquestrador, busca, prompt de compilação, modelo de linguagem e resposta. A caixa de consulta do usuário contém um ícone de usuário e uma consulta. A caixa do orquestrador contém um ícone de engrenagem e um texto que lê coordenadas do pipeline. A caixa de pesquisa contém um ícone de lupa e o texto “recuperar documentos relevantes”. A caixa de prompt de build contém um ícone de documento e um texto que lê o contexto e as instruções de montagem. O modelo de linguagem mox inclui um ícone de rede neural e um texto que lê gerar resposta. A caixa de resposta contém um ícone de bolha de mensagem e uma resposta para a consulta original. Setas que apontam da esquerda para a direita conectam cada caixa. Uma linha pontilhada se estende da caixa de pesquisa até um ícone rotulado como vetor ou índice de palavra-chave.

RAG agêntico:

O diagrama é intitulado Agentic RAG (ciclo de raciocínio) e mostra um fluxo horizontal de nove componentes organizados da esquerda para a direita, conectados por setas que indicam a direção do processo. Na extrema esquerda, há uma caixa rotulada como "consulta do usuário". Contém um ícone de usuário e a consulta de exemplo: quais dos SKUs dos nossos produtos têm recalls em aberto nos últimos 90 dias? À direita da consulta do usuário, há uma caixa rotulada como agent (loop de raciocínio), que contém um ícone de IA e quatro itens com marcadores que descrevem o processo interno do agente: entender a consulta, decidir a próxima ação, avaliar os resultados e iterar até estar pronto para responder. Uma seta bidirecional tracejada envolve a caixa do agente e tem o rótulo “repita até haver contexto suficiente”. Esta instrução indica que o agente repete seu processo de raciocínio conforme necessário antes de prosseguir para a próxima etapa. À direita do agente, há uma caixa com o rótulo “chamada de ferramenta: Pesquisar A (catálogo de produtos)”, que descreve a ação de encontrar SKUs relevantes. À direita está outra caixa rotulada avaliando os resultados, que pergunta se os resultados são suficientes. Uma seta sólida rotulada como “sim” continua o fluxo para a direita, em direção à próxima chamada de ferramenta. Uma seta tracejada rotulada com “não” aponta de volta para a esquerda, retornando à caixa do agente para indicar que o agente repete o processo se os resultados forem insuficientes. À direita, em seguida, há uma caixa rotulada “chamada de ferramenta: Search B (banco de dados regulatório)”, que descreve a ação de verificar recalls para esses SKUs. À direita dessa caixa há uma segunda caixa de resultados de avaliação. Ele pergunta se os resultados são suficientes. Uma seta sólida rotulada com “sim” continua o fluxo para a direita, e uma seta tracejada rotulada com “não” retorna à caixa do agente. À direita da segunda etapa de avaliação está uma caixa com o rótulo "construir prompt", que contém um ícone de documento e a descrição "monta todo o contexto e todas as instruções relevantes". À direita dessa caixa, há uma caixa rotulada como modelo de linguagem, que contém um ícone de rede neural e a descrição gerar resposta. Na extremidade direita há uma caixa com o rótulo “response”, que contém um ícone de bolha de mensagem e uma resposta de exemplo: Aqui estão os SKUs com recalls em aberto nos últimos 90 dias. O fluxo geral ilustra como o agente chama dinamicamente as ferramentas de recuperação, avalia os resultados intermediários e itera entre várias fontes de dados antes de montar um prompt final e gerar uma resposta fundamentada.

Carrege um arquivo Visio desta arquitetura.

No RAG agente, o modelo de linguagem atua como o mecanismo de raciocínio. Ele recebe a consulta do usuário, inspeciona suas ferramentas disponíveis e gera uma chamada de função que solicita dados específicos. O runtime do agente executa a função e retorna o resultado para o modelo. O modelo decide se deseja chamar outra ferramenta ou produzir uma resposta final. Às vezes, esse loop é chamado de padrão Reason + Act (ReAct ).

Componentes principais

Um sistema RAG agente tem os seguintes componentes:

• Os agentes são entidades de raciocínio que orquestram o fluxo de trabalho. O agente é definido por suas instruções ou prompt do sistema, um modelo de idioma atribuído e um conjunto de ferramentas disponíveis.

• Ferramentas são funções ou APIs que o agente pode invocar. Em um sistema RAG com agentes, pelo menos uma ferramenta realiza a recuperação. Outras ferramentas podem executar cálculos, chamar APIs externas ou disparar ações comerciais.

• Loops de raciocínio são ciclos iterativos nos quais o agente planeja sua próxima ação, chama uma ferramenta e avalia o resultado. O agente controla quando deve parar de iterar e produzir uma resposta final.

Projetar a recuperação como uma ferramenta

A principal decisão de projeto em um RAG com agentes é como expor a recuperação de informações como uma ferramenta que o agente pode invocar. Cada ferramenta de recuperação deve ter uma descrição clara para que o modelo de linguagem entenda quando e como usá-la.

Definir descrições da ferramenta

A qualidade das descrições da ferramenta afeta diretamente a precisão com que o agente seleciona e chama as ferramentas. Siga estas diretrizes:

• Seja específico sobre a fonte de dados. Descreva quais dados a ferramenta acessa. Por exemplo, "Pesquise na base de dados de conhecimento da política interna de RH os benefícios dos funcionários, as políticas de licença e os procedimentos de conformidade" é mais útil do que "Pesquisar documentos".

• Especifique os parâmetros obrigatórios e opcionais. Use parâmetros tipados com descrições. Uma ferramenta de pesquisa pode aceitar uma query cadeia de caracteres (obrigatória), um top_k inteiro (opcional, padrão como 5) e um filter objeto (opcional) para filtragem de metadados.

• Descreva o esquema de retorno. Informe ao modelo qual forma de dados ele pode receber. Os dados podem ser formatados como uma lista de partes de texto com pontuações de relevância ou um objeto estruturado com campos específicos. Essas informações ajudam o agente a raciocinar sobre os resultados.

Ferramenta única versus várias ferramentas

Decida se deve expor uma única ferramenta de recuperação de uso geral ou várias ferramentas especializadas.

Abordagem	Quando usar	Considerations
Ferramenta de recuperação única	Um índice, padrões de consulta uniformes, filtragem simples	Limita a carga de roteamento do modelo. Melhor quando as consultas são semelhantes em estrutura.
Várias ferramentas de recuperação	Índices diferentes, fontes de dados heterogêneas ou estratégias de consulta diferentes para cada fonte	O agente pode selecionar a origem certa para cada pergunta subsequente. Mantenha a contagem total de ferramentas inferior a 20 para manter a precisão do modelo.

Por exemplo, um agente de suporte ao cliente pode ter três ferramentas de recuperação. Uma ferramenta pesquisa a base de dados de conhecimento do produto. Outra ferramenta consulta a API de gerenciamento de pedidos por ID do pedido. A terceira ferramenta consulta runbooks internos de solução de problemas. O agente decide qual ferramenta chamar com base na pergunta do usuário.

Padrões de implementação da ferramenta

Ao implementar ferramentas de recuperação, considere os seguintes padrões:

• Encapsule sua lógica de busca existente. Se você já tiver um pipeline RAG com uma configuração de busca otimizada, como busca híbrida, reranqueamento ou filtros, encapsule essa lógica em uma função. O agente chama a função e a função manipula a mecânica de pesquisa. Para obter diretrizes sobre como configurar esses recursos de pesquisa, consulte a recuperação de informações.

• Retorne a quantidade certa de contexto. Retorne os primeiros N blocos mais relevantes com seus metadados. Retornar muitos resultados consome tokens e pode diluir o sinal. Comece com três a cinco resultados por chamada de ferramenta e ajuste com base na avaliação.

• Inclua metadados nos resultados. Retornar títulos de origem, datas, IDs de documento e pontuações de relevância ao lado do texto. O agente pode usar esses metadados para avaliar a qualidade do resultado e citar fontes na resposta.

• Suporte à filtragem. Exponha filtros de metadados como intervalo de datas, categoria de documento e linha do produto como parâmetros de ferramenta. Esse design permite que o agente restrinja pesquisas sem depender apenas do entendimento semântico do mecanismo de pesquisa.

Implementar RAG agêntico com o Serviço de Agente

O Serviço de Agente fornece uma plataforma gerenciada para criar, implantar e dimensionar agentes de IA. Você pode usar suas ferramentas integradas para recuperação ou registrar funções personalizadas que encapsulam sua própria lógica de pesquisa.

Usar ferramentas de pesquisa internas

O Serviço de Agente fornece as seguintes ferramentas internas que lidam com a recuperação sem código personalizado:

• Pesquisa de arquivo: Carregue documentos em um repositório de vetores e o agente os pesquisa automaticamente. Adequado para coleções de documentos pequenas a médias para as quais você deseja pesquisa de vetor de infraestrutura zero. Para obter mais informações, consulte a ferramenta Pesquisa de Arquivos para agentes.

• Pesquisa de IA do Azure : Conecte um índice existente do Pesquisa de IA do Azure  ao seu agente. Use esta abordagem quando você tiver um pipeline de busca estabelecido que usa analisadores personalizados, perfis de pontuação ou filtragem de segurança. Para obter mais informações, consulte a ferramenta de Pesquisa de IA.

Use chamada de função para recuperação personalizada

Quando a lógica de recuperação for mais complexa do que uma ferramenta interna dá suporte, defina uma ferramenta de função. Descreva o nome, os parâmetros e a finalidade da função. O agente chama a função quando precisa de dados, e seu aplicativo executa a pesquisa e retorna os resultados.

Use essa abordagem quando precisar realizar as seguintes tarefas:

• Consultar vários índices ou armazenamentos de dados em uma única função.
• Aplique o pré-processamento personalizado à consulta do usuário antes de pesquisar.
• Pós-processe ou reordene os resultados da pesquisa antes de retorná-los ao agente.
• Faça chamadas a APIs sem busca, como bancos de dados ou endpoints REST, como parte da etapa de recuperação de dados.

Controle o ciclo de raciocínio

Agentic RAG apresenta um loop de raciocínio que não está presente no RAG padrão. Execute as seguintes ações para gerenciar esse loop e evitar custos e latência descontrolados:

• Definir limites de iteração. Limite o número de chamadas de ferramenta por solicitação de usuário. Um limite de 5 a 10 iterações é típico. Se o agente não convergir nesse ponto, a consulta poderá precisar de assistência humana ou de uma abordagem diferente.

• Monitorar o consumo de token. Cada chamada de ferramenta adiciona tokens de entrada e saída. Acompanhe o uso cumulativo de tokens por solicitação e defina limites de orçamento.

• Use instruções do agente para orientar o comportamento. O prompt do sistema ou as instruções do agente devem informar ao agente quando parar de iterar. Um prompt de exemplo pode ler "Se você coletar informações relevantes de pelo menos duas fontes, sintetize uma resposta. Não pesquise mais de três vezes a mesma pergunta subsequente."

Implementar RAG com agentes usando o Agent Framework

O Agent Framework é o sucessor de Kernel semântico e AutoGen. Ele combina abstrações de agente simples com recursos corporativos, como gerenciamento de estado baseado em sessão, middleware, telemetria e fluxos de trabalho baseados em grafo. Você pode definir a recuperação como uma ferramenta de função que o agente chama durante seu loop de raciocínio.

Definir uma ferramenta de função de recuperação de dados (C#)

Use AIFunctionFactory.Create para transformar qualquer método em uma ferramenta de função. O Description atributo informa ao modelo quando chamar a função e o que cada parâmetro significa.

using System.ComponentModel;
using System.Text;
using Azure.AI.Projects;
using Azure.Identity;
using Azure.Search.Documents;
using Azure.Search.Documents.Models;
using Microsoft.Agents.AI;
using Microsoft.Extensions.AI;

[Description("Search the product documentation knowledge base for technical specifications, user guides, and troubleshooting articles.")]
static async Task<string> SearchProductDocs(
    [Description("The search query that describes what information to find")] string query,
    [Description("Maximum number of results to return")] int topK = 5)
{
    // searchClient is your configured Azure AI Search client. Replace the
    // placeholders with your search endpoint and index name.
    var searchClient = new SearchClient(
        new Uri("<your-search-endpoint>"),
        "<your-index-name>",
        new DefaultAzureCredential());

    // Your search logic: hybrid search, reranking, filtering
    var results = await searchClient.SearchAsync<SearchDocument>(
        query, new SearchOptions { Size = topK });

    var formatted = new StringBuilder();
    await foreach (var result in results.Value.GetResultsAsync())
    {
        formatted.AppendLine($"Source: {result.Document["title"]}");
        formatted.AppendLine($"Content: {result.Document["chunk"]}");
        formatted.AppendLine();
    }
    return formatted.ToString();
}

AIAgent agent = new AIProjectClient(
    new Uri("<your-foundry-project-endpoint>"),
    new DefaultAzureCredential())
    .AsAIAgent(
        model: "gpt-4o-mini",
        instructions: "You are a product support agent. Use search tools to find relevant docs before answering. Cite your sources.",
        tools: new[] { AIFunctionFactory.Create(SearchProductDocs) });

Console.WriteLine(await agent.RunAsync(
    "How do I configure high availability for the gateway appliance?"));

Quando o agente encontra uma questão factual, ele chama SearchProductDocs para recuperar o contexto relevante. Para saudações ou esclarecimentos, ele responde diretamente sem chamadas de ferramenta.

Definir uma ferramenta de função de recuperação (Python)

Em Python, defina uma função comum com dicas de tipo Annotated e passe-a para o construtor Agent. A docstring da função e as anotações de parâmetro indicam ao modelo quando e como chamar a função.

from typing import Annotated
from agent_framework import Agent
from agent_framework.foundry import FoundryChatClient
from azure.identity.aio import DefaultAzureCredential

search_client = SearchClient(
    endpoint="<your-search-service-endpoint>",
    index_name="product-docs",
    credential=DefaultAzureCredential(),
)

async def search_product_docs(
    query: Annotated[str, "The search query that describes what information to find"],
    top_k: Annotated[int, "Maximum number of results to return"] = 5,
) -> str:
    """Search the product documentation knowledge base for technical
    specifications, user guides, and troubleshooting articles."""
    # Your search logic: call Azure AI Search, a vector database, or another index
    results = await search_client.search(query, top=top_k)
    formatted = []
    async for result in results:
        formatted.append(f"Source: {result['title']}\nContent: {result['chunk']}")
    return "\n\n".join(formatted)

agent = Agent(
    client=FoundryChatClient(
        project_endpoint="<your-foundry-project-endpoint>",
        model="gpt-4o-mini",
        credential=DefaultAzureCredential(),
    ),
    name="ProductSupportAgent",
    instructions="You are a product support agent. Use search tools to find relevant docs before answering. Cite your sources.",
    tools=[search_product_docs],
)
response = await agent.run("How do I configure high availability for the gateway appliance?")

Combinar várias ferramentas de função

Você pode passar várias ferramentas de recuperação para o mesmo agente. O agente seleciona a função apropriada com base na pergunta do usuário:

AIAgent agent = new AIProjectClient(
    new Uri("<your-foundry-project-endpoint>"),
    new DefaultAzureCredential())
    .AsAIAgent(
        model: "gpt-4o-mini",
        instructions: "You are a support agent. Use the appropriate search tool for each question.",
        tools: new[] {
            AIFunctionFactory.Create(SearchProductDocs),
            AIFunctionFactory.Create(SearchOrderHistory),
            AIFunctionFactory.Create(SearchRunbooks)] });

Implantar como agente hospedado

Você pode implantar um agente do Agent Framework no Serviço do Agente como um agente hospedado. Empacote o código do agente em uma imagem de contêiner, envie-o por push para Registro de Contêiner do Azure e registre-o por meio do SDK do Foundry ou Azure CLI do Desenvolvedor. O adaptador azure-ai-agentserver-agentframeworkde hospedagem expõe seu agente como uma API REST compatível com o protocolo Foundry Responses.

Avaliar RAG agêntico

O RAG agentic apresenta dimensões de avaliação além do RAG padrão. Além das métricas que a fase de avaliação de ponta a ponta do modelo de idioma aborda, avalie os seguintes aspectos da solução:

Precisão da seleção da ferramenta

Meça a frequência com que o agente seleciona a ferramenta correta para uma consulta específica. Crie um conjunto de testes de consultas com as seleções de ferramenta esperadas e compare as chamadas reais do agente com as chamadas esperadas. A baixa precisão da seleção de ferramentas indica que as descrições da ferramenta precisam de melhorias.

Eficiência de recuperação

Acompanhe o número de chamadas de ferramenta por solicitação. Se o agente faz muitas chamadas de forma consistente para consultas que deveriam exigir apenas uma ou duas chamadas, o problema pode estar em descrições ruins das ferramentas, em resultados insuficientes por chamada ou em um prompt de sistema excessivamente cauteloso.

Latência de ponta a ponta

Cada chamada de ferramenta adiciona uma ida e volta ao serviço de busca, além do tempo para o modelo raciocinar sobre os resultados. Medir a latência total da solicitação e dividi-la por componente, incluindo o tempo de raciocínio do modelo, o tempo de execução da ferramenta e o tempo de processamento de resultados.

Custo por solicitação

Calcule o custo total por solicitação, incluindo todas as chamadas de modelo (cada etapa de raciocínio e a geração final) e todas as chamadas de serviço de pesquisa. Compare esse custo com uma linha de base RAG padrão para garantir que o raciocínio extra forneça valor suficiente.

Considerações sobre o design

Analise as seguintes considerações ao decidir se vai adotar o RAG agêntico:

• Latência. Cada etapa de raciocínio adiciona uma chamada ao modelo. Uma solicitação RAG padrão com uma pesquisa e uma geração pode levar de 2 a 3 segundos. Uma solicitação de RAG agêntico com três a cinco chamadas de ferramentas pode levar de 8 a 15 segundos. Avalie se essa latência é aceitável para sua experiência de usuário.

• Custo. Mais chamadas de modelo e mais tokens consumidos por solicitação significam custos mais altos. Avalie se a melhoria na qualidade da resposta justifica o aumento.

• Fiabilidade. O agente pode fazer seleções de ferramentas abaixo do ideal, inserir loops de raciocínio ou não alcançar uma resposta. Crie salvaguardas, como limites de iteração, limites de tempo e mecanismos de contingência, caso o agente não consiga resolver uma consulta.

• Observabilidade. Faça a instrumentação de cada etapa do ciclo de raciocínio. Registre quais ferramentas o agente chama, quais parâmetros ele usa, quais resultados ele recebe e como ele explica esses resultados. O rastreamento de agentes do Microsoft Foundry fornece suporte integrado para essa instrumentação.

• Segurança. Cada ferramenta que o agente pode chamar é uma superfície de ataque. Valide os parâmetros da ferramenta, sanifique as entradas e aplique acesso de privilégios mínimos a quaisquer fontes de dados às quais as ferramentas se conectam. Não passe credenciais nas saídas da ferramenta.

Próximas Etapas 

• Visão geral do Agent Framework
• Ferramentas de funções no Agent Framework
• Visão geral do Serviço do Agente
• Agentes hospedados no Serviço de Agentes
• Chamada de função em agentes do Foundry
• Visão geral das ferramentas do agente para o Serviço de Agente

Recurso relacionado

• Padrões de orquestração do agente de IA