Recuperação Agêntica com Amazon Bedrock Knowledge Base Gerenciada e CDK

Quando o RAG tradicional não é suficiente

A maioria dos sistemas de Geração Aumentada por Recuperação (RAG — Retrieval Augmented Generation) segue o mesmo padrão: uma pergunta é transformada em vetor, os trechos mais próximos são buscados em um índice e entregues ao modelo, que gera a resposta. Uma recuperação, uma geração. Para muitos casos de uso, esse design é perfeitamente adequado.

O problema aparece em situações específicas: quando a resposta está espalhada por dois corpora distintos, quando a fonte certa depende do tipo de pergunta, ou quando seria necessário consultar o corpus uma segunda vez depois de ver o primeiro resultado. Nesses cenários, uma única recuperação retorna metade do que o modelo precisa — e uma resposta fluente porém incompleta pode ser pior do que nenhuma resposta.

A recuperação agêntica empresarial resolve esses três problemas colocando um agente de raciocínio no fluxo. Esse agente decide se deve recuperar, qual base de conhecimento do Amazon Bedrock consultar e se é necessário buscar mais informações antes de compor a resposta final.

O que mudou desde o RAG de ciclo único

Em agosto de 2024, a AWS publicou o guia Build an end-to-end RAG solution using Knowledge Bases for Amazon Bedrock and the AWS CDK, que implantava o design de ciclo único como uma aplicação CDK: um bucket do Amazon Simple Storage Service (Amazon S3), uma coleção e índice do Amazon OpenSearch Serverless, uma base de conhecimento e uma fonte de dados.

Desde então, três coisas mudaram de forma significativa:

• O Amazon Bedrock passou a oferecer uma Knowledge Base Gerenciada (Type: MANAGED), que cuida internamente da ingestão, armazenamento, indexação e recuperação — sem necessidade de provisionar um banco de dados vetorial.
• O Amazon Bedrock AgentCore fornece a camada agêntica: um Gateway que expõe cada base de conhecimento como uma ferramenta do Protocolo de Contexto de Modelo (MCP — Model Context Protocol), um Runtime que hospeda o agente de raciocínio, e a API AgenticRetrieveStream, que faz reranking interno e retorna uma resposta sintetizada com citações.
• A observabilidade e avaliação agora são provisionadas junto com a solução, não adicionadas depois. A solução inclui dois dashboards do Amazon CloudWatch com sete camadas de telemetria, mais duas formas de avaliação — sob demanda e contínua.

Vale destacar: a recuperação agêntica via AgenticRetrieveStream está disponível somente na Knowledge Base Gerenciada. O modelo autogerenciado (DIY), onde o cliente provisiona e opera o próprio banco vetorial, não suporta esse recurso.

Visão geral da solução

A solução é uma aplicação AWS CDK em Python que declara quatro stacks. O CDK deriva automaticamente a ordem de implantação a partir das referências entre os constructs — não é necessário um script de deploy manual.

kb_stack = KnowledgeBasesStack(app, f"{project}-kb", env=env)
gateway_stack = AgenticGatewayStack(
    app, f"{project}-gateway",
    env=env,
    financial_kb=kb_stack.financial_kb,  # ← a referência cria a dependência
    weather_kb=kb_stack.weather_kb,
)
agent_stack = AgentRuntimeStack(
    app, f"{project}-agent",
    env=env,
    gateway=gateway_stack.gateway,
)
DashboardsStack(
    app, f"{project}-dashboards",
    env=env,
    financial_kb=kb_stack.financial_kb,
    weather_kb=kb_stack.weather_kb,
    gateway=gateway_stack.gateway,
    agent_runtime=agent_stack.agent_runtime,
)

As quatro stacks e o que cada uma cria:

• -kb: bucket S3, upload dos corpora, duas Knowledge Bases gerenciadas, fontes de dados e ingestão.
• -gateway: Gateway com AWS IAM e MCP, com targets de AgenticRetrieveStream por Knowledge Base.
• -agent: repositório no Amazon ECR, build no AWS CodeBuild, agente Strands no Runtime com logs e traces — leva cerca de 8 a 10 minutos pelo build da imagem.
• -dashboards: dois dashboards de observabilidade no CloudWatch, que se populam conforme o tráfego chega.

O fluxo de uma pergunta pela solução

Antes de qualquer pergunta ser feita, cada corpus no S3 é ingerido na sua respectiva Knowledge Base Gerenciada: o Amazon Bedrock analisa, divide em chunks, gera embeddings e indexa automaticamente. Esse processo ocorre uma vez, no deploy.

A partir daí, cada pergunta segue o seguinte caminho:

• O usuário envia a pergunta ao agente hospedado no Amazon Bedrock AgentCore Runtime, que auto-instrumenta todo o loop de raciocínio e ação com spans de OpenTelemetry (OTEL).
• O modelo de raciocínio do agente planeja e roteia entre as bases de conhecimento. Como cada base está exposta como uma ferramenta de recuperação separada, o agente seleciona a ferramenta cujo tópico corresponde à pergunta — financeiro ou meteorológico.
• A chamada de ferramenta é intermediada pelo AgentCore Gateway via MCP, autorizada pela role IAM da tarefa do agente e assinada com SigV4, que invoca a API AgenticRetrieveStream da Knowledge Base correspondente.
• O AgenticRetrieveStream decompõe a pergunta em sub-consultas, recupera iterativamente do armazenamento gerenciado pelo Bedrock e sintetiza uma resposta fundamentada com citações, que é transmitida de volta pelo Gateway.
• O agente verifica se o contexto retornado é suficiente. Se não, ele volta ao loop; se sim, retorna a resposta citada ao usuário.
• Durante todo o processo, o Runtime emite spans, contagens de tokens e métricas para o CloudWatch e o AWS X-Ray.

Os datasets da solução

A solução inclui dois corpora pequenos, no diretório data/ do repositório:

• Financeiro: um relatório 10-K sintético da empresa fictícia Octank Financial (arquivo octank_financial_10K.pdf, ~198 KB). Trata-se de dados de amostra gerados por modelo, licenciados CC0 — não são dados financeiros reais.
• Meteorológico: um relatório real e de domínio público do Serviço de Pesquisa do Congresso dos EUA sobre tornados (IF12695, arquivo tornadoes_report.pdf, ~560 KB), disponível em sgp.fas.org/crs/misc/IF12695.pdf.

Os dois corpora são intencionalmente distintos para que o agente precise rotear cada pergunta para a base de conhecimento correta. Por se tratar de Knowledge Bases Gerenciadas, não é necessário configurar chunking, embedding ou índice — o Amazon Bedrock cuida de tudo automaticamente na ingestão.

A decisão de usar duas bases separadas, cada uma exposta como uma ferramenta própria no Gateway, é deliberada. Ela torna o roteamento um ato explícito de raciocínio observável: a árvore de spans mostra qual ferramenta foi escolhida para cada pergunta, e as métricas de qualidade de recuperação permanecem separáveis por base de conhecimento. Uma única ferramenta abrangendo ambos os corpora tornaria essa distinção invisível.

Pré-requisitos e implantação

Para implantar a solução, são necessários:

• Uma conta AWS com permissões para Amazon Bedrock, AgentCore (Runtime + Gateway), AWS Identity and Access Management (IAM), CloudWatch, AWS X-Ray, Amazon Elastic Container Registry (Amazon ECR), AWS CodeBuild, Amazon S3, AWS Lambda e AWS CloudFormation.
• O modelo do agente disponível na conta (padrão: us.anthropic.claude-haiku-4-5-20251001-v1:0).
• CloudWatch Transaction Search habilitado, para que os spans OTEL cheguem ao grupo aws/spans.
• Node.js 18+ e o CDK CLI (npm install -g aws-cdk), além de Python 3.13+.
• A conta e região inicializadas para o CDK (cdk bootstrap), uma vez por conta/região. Docker local não é necessário — a imagem do agente é construída pelo CodeBuild (ARM64).

Atenção à disponibilidade regional: a Knowledge Base Gerenciada, a recuperação agêntica (AgenticRetrieveStream) e o Amazon Bedrock AgentCore não estão disponíveis em todas as regiões AWS. Antes de implantar, confirme se todos esses recursos estão disponíveis na sua região alvo e ajuste ACCOUNT_REGION no arquivo config.py. O padrão é us-west-2. Consulte a documentação do Amazon Bedrock AgentCore e a lista de serviços regionais da AWS.

Com os pré-requisitos atendidos, toda a solução é implantada com um único conjunto de comandos:

git clone https://github.com/aws-samples/amazon-bedrock-samples.git
cd rag/managed-knowledge-bases/07-IaaC/managed-kb-observability-cdk/
python3 -m venv .venv && source .venv/bin/activate
pip install -r requirements.txt
cdk bootstrap # uma vez por conta/região
cdk deploy --all

O terminal reporta cada stack conforme é concluída: bmkb-obs-cdk-kb [1/4], depois gateway [2/4], depois agent [3/4], e finalmente dashboards [4/4]. Essa ordem é derivada automaticamente pelo CDK a partir das referências entre os constructs — não existe script de deploy para manter sincronizado.

Observabilidade em sete camadas

A solução inclui dois dashboards no CloudWatch que cobrem sete camadas de telemetria:

• L1: métricas nativas da Knowledge Base.
• L2: métricas de ingestão.
• L3: qualidade da recuperação agêntica (métricas sem ground truth: retrieval_utilization, grounded_coverage e duplicate_rate).
• L4: métricas do Gateway e MCP (invocações, erros de sistema, erros de usuário, throttles).
• L5: árvore de spans OTEL no grupo aws/spans.
• L6: uso de tokens por modelo.
• L7: scores de avaliação (sob demanda e contínua).

As camadas 1, 4 e 5 são emitidas automaticamente. As camadas 3, 6 e 7 são publicadas como métricas customizadas pelo notebook de driver.

Um detalhe importante sobre a camada 5: uma única chamada LLM produz três spans aninhados. Para contar cada chamada LLM apenas uma vez ao agregar tokens, é necessário filtrar pelo span folha do tipo CLIENT:

fields attributes.gen_ai.request.model as model,
       attributes.gen_ai.usage.input_tokens as in_tok,
       attributes.gen_ai.usage.output_tokens as out_tok
| filter ispresent(in_tok) and kind = 'CLIENT' and name like /^chat /
| stats sum(in_tok) as input_tokens, sum(out_tok) as output_tokens, count(*) as llm_calls by model

Sem esse filtro, a mesma consulta reportaria três vezes mais tokens e três vezes mais chamadas.

Avaliação sob demanda e contínua

A qualidade é medida de duas formas, ambas provisionadas pela aplicação:

• Sob demanda: o notebook de driver chama o AgentCore (LLM-as-judge) sobre os spans de cada sessão, usando avaliadores integrados de Correção (Correctness), Fidelidade (Faithfulness) e Precisão de Seleção de Ferramenta (Tool-Selection Accuracy), publicando os scores no CloudWatch como camada 7.
• Contínua (online): a stack do agente provisiona um AWS::BedrockAgentCore::OnlineEvaluationConfig que amostra sessões ao vivo e as pontua automaticamente, sem necessidade de executar o notebook. Os resultados chegam no grupo de logs /aws/bedrock-agentcore/evaluations/results/<config-id> e são publicados como métricas no namespace Bedrock-AgentCore/Evaluations, permitindo criar gráficos ou alarmes sem precisar analisar logs.

Os quatro avaliadores integrados são: Precisão de Seleção de Ferramenta, Fidelidade, Correção e Relevância da Resposta. Na execução de exemplo descrita pela AWS, a avaliação contínua pontuou 1,00 em todos os quatro avaliadores, com cinco traces pontuados por avaliador.

Atenção ao custo: a solução define SAMPLING_PERCENTAGE = 100 apenas para fins de demonstração, para que todos os resultados apareçam imediatamente. Isso não é uma recomendação para produção. A avaliação online invoca um LLM-as-judge por sessão amostrada, portanto o custo escala com a taxa de amostragem e o volume de tráfego. Para implantações reais, escolha uma porcentagem que se adeque às suas necessidades de monitoramento de qualidade e orçamento. A taxa é configurada em uma única constante, EvalConfig.SAMPLING_PERCENTAGE, no arquivo config.py.

Limpeza dos recursos

Para remover a solução e evitar cobranças contínuas (dados armazenados na Knowledge Base, imagem no ECR e avaliação online ativa geram custos enquanto as stacks existem), basta executar:

cdk destroy --all

O CDK remove as stacks na ordem inversa de dependência automaticamente: dashboards, depois agent, depois gateway, depois kb. O mesmo grafo de dependências derivado para o deploy é percorrido ao contrário — sem script de teardown para manter sincronizado.

O que mudou em relação à solução de 2024

Comparando com a solução de 2024, a mudança principal é de subtração: a nova arquitetura remove infraestrutura em vez de adicionar.

• Banco vetorial: antes, era necessário provisionar, escalar e pagar por uma coleção OpenSearch Serverless com OCUs. Agora, com Type: MANAGED, o Amazon Bedrock gerencia armazenamento e indexação.
• Ciclo de vida do índice: antes, um custom resource criava o índice e aguardava ficar pesquisável. Agora, não há nada a criar.
• Modelo de embedding: antes, o cliente selecionava e concedia acesso ao modelo. Agora, é gerenciado pelo serviço por padrão.
• Recuperação: antes, uma chamada Retrieve retornava os top-k chunks por similaridade vetorial. Agora, o AgenticRetrieveStream faz reranking interno e retorna uma resposta sintetizada com citações.
• Telemetria: antes, nenhuma provisionada. Agora, sete camadas e dois dashboards.
• Avaliação: antes, manual. Agora, sob demanda e contínua, ambas provisionadas.

A troca é real nos dois sentidos: um único índice respondendo perguntas de ciclo único é mais barato por consulta, mais simples de raciocinar e totalmente suficiente quando um corpus contém a resposta. A arquitetura agêntica é a escolha certa quando esse cenário não se aplica.

Próximos passos

A partir dessa base, é possível apontar as fontes de dados para corpora próprios, colocar o agente em uma Nuvem Virtual Privada (VPC — Virtual Private Cloud), ajustar a taxa de amostragem da avaliação online ao orçamento e às políticas da organização, ou adicionar mais bases de conhecimento ao roteador. Para saber mais, consulte a documentação do Amazon Bedrock. A aplicação, o notebook de driver e os utilitários estão disponíveis no repositório GitHub, onde é possível clonar e implantar uma cópia própria com um único comando.

Fonte

Build agentic retrieval on a Managed Amazon Bedrock Knowledge Base with CDK (https://aws.amazon.com/blogs/machine-learning/build-agentic-retrieval-on-a-managed-amazon-bedrock-knowledge-base-with-cdk/)