Primeiros Passos com Amazon Bedrock AgentCore Knowledge Bases

Aprenda a criar uma Knowledge Base gerenciada, ingerir documentos do S3, consultar com Python e conectar ao Harness do AgentCore via Gateway para construir um agente de IA com RAG

Series: Primeiros Passos com o Amazon Bedrock AgentCore Code (8 articles)

1
Primeiros Passos com Amazon Bedrock AgentCore Harness e Runtime
…
8
Primeiros Passos com Amazon Bedrock AgentCore Knowledge Bases This article

Carlos Biagolini

AWS Solutions Architect

Published Oct 12, 2026

Last modified Oct 12, 2026

Introdução

Agentes de IA são tão bons quanto os dados que conseguem acessar. Um chatbot treinado com conhecimento geral não consegue responder perguntas sobre a documentação interna da sua empresa, manuais de produtos ou políticas. Retrieval-Augmented Generation (RAG) resolve isso permitindo que agentes pesquisem seus dados privados e fundamentem suas respostas em informações reais e verificáveis.

Amazon Bedrock Knowledge Bases é um serviço totalmente gerenciado que implementa pipelines de RAG para agentes de IA. Ele cuida de todo o ciclo de vida: ingestão de documentos, conversão em embeddings vetoriais, armazenamento em um índice pesquisável e recuperação de trechos relevantes quando um agente precisa deles.

Este artigo faz parte de uma série que estou escrevendo sobre diferentes aspectos do Amazon Bedrock AgentCore. Aqui, focamos em como usar Knowledge Bases para dar aos agentes acesso aos seus dados privados. Para uma compreensão mais ampla do AgentCore e seus componentes, confira os outros artigos desta série:

Tipos de Knowledge Base

O Amazon Bedrock oferece três tipos de Knowledge Bases, cada um projetado para diferentes padrões de dados e requisitos operacionais:

Bedrock Managed Knowledge Base é a opção totalmente gerenciada. A AWS cuida de todo o pipeline de RAG: ingestão, vector store, modelo de embedding, reranking e otimização de recuperação. Inclui modelos de embedding e reranking integrados sem custo adicional, suporta 7 conectores nativos de fonte de dados (S3, SharePoint, Confluence, Web Crawler, Google Drive, OneDrive, Custom) e se integra nativamente com o AgentCore Gateway . Também suporta Agentic Retrieval, uma capacidade de recuperação em múltiplas etapas que raciocina sobre seus dados para responder consultas complexas. Esta é a opção recomendada para a maioria dos casos de uso.

Unstructured Vector Store Knowledge Base (gerenciada pelo cliente) oferece controle total sobre a infraestrutura do vector store. Você provisiona e gerencia seu próprio banco de dados vetorial (Amazon OpenSearch Serverless, Aurora, Neptune, Pinecone, Redis Enterprise Cloud, MongoDB Atlas ou Amazon S3 Vectors). Você escolhe o modelo de embedding e a estratégia de busca. Esta opção é ideal quando você tem requisitos específicos de infraestrutura ou precisa de acesso direto ao banco de dados vetorial. Não suporta Agentic Retrieval nem integração nativa com o AgentCore Gateway.

Structured Data Store Knowledge Base (gerenciada pelo cliente) conecta-se a dados tabulares e relacionais através do motor de consultas do Amazon Redshift. Em vez de embeddings vetoriais, converte consultas em linguagem natural em SQL para recuperar dados do Amazon Redshift ou AWS Glue Data Catalog (Lake Formation). Esta opção é ideal para cenários onde seus dados são estruturados (tabelas, bancos de dados) e você precisa responder perguntas analíticas sobre eles.

Resumo Comparativo

Managed KB: Zero gerenciamento de infraestrutura, embedding/reranking integrados, Agentic Retrieval, integração com Gateway. Melhor para a maioria dos casos de uso de RAG.
Unstructured Vector Store KB: Controle total sobre o banco vetorial, estratégias de busca customizadas, mais opções de vector store. Melhor para requisitos de infraestrutura específicos.
Structured Data Store KB: Recuperação baseada em SQL a partir do Redshift/Glue, sem necessidade de embeddings vetoriais. Melhor para análises de dados tabulares/relacionais.

Neste artigo, focamos exclusivamente no Bedrock Managed Knowledge Base. Vamos criar um bucket S3 com documentos sobre carros, construir um Managed KB que indexa esses documentos, consultá-lo localmente com Python e, em seguida, integrá-lo ao nosso Harness de concessionária de carros usados através do AgentCore Gateway.

Pré-requisitos

Conta AWS com credenciais configuradas
Usuário ou role IAM com permissões para criar buckets S3, roles IAM e usar o Amazon Bedrock AgentCore
Python 3.12 instalado
Região AWS onde o AgentCore está disponível (us-east-1, us-west-2, ap-southeast-2 ou eu-central-1)
Um Harness já criado (do primeiro artigo desta série )

Step 1: Criar um Bucket S3 com Documentos sobre Carros

Precisamos de documentos fonte para o Knowledge Base ingerir. Neste passo, criamos um bucket S3 e fazemos upload de arquivos de texto sobre carros que se conectam ao nosso cenário de concessionária de carros usados.

1.1 Criar o Bucket S3

1.1.1. Navegue até Amazon S3 > Buckets no Console AWS

1.1.2. Clique em Create bucket

1.1.3. No campo Bucket name, insira um nome único (exemplo: agentcore-kb-cars-<your-account-id>)

1.1.4. Selecione a mesma região onde você criará o Knowledge Base (por exemplo, us-east-1)

1.1.5. Deixe todas as configurações restantes nos valores padrão

1.1.6. Clique em Create bucket

1.2 Criar os Documentos

O repositório complementar contém arquivos markdown de exemplo sobre carros no diretório demos/:

suv-vs-sedan-guide.md — Comparação abrangente entre SUVs e sedãs para famílias americanas, incluindo preços, economia de combustível e recomendações por faixa de orçamento.
car-maintenance-tips.md — Diretrizes de manutenção para proprietários de veículos usados, cobrindo troca de óleo, pneus, freios, bateria, fluidos, preparação sazonal e manutenção específica para elétricos/híbridos.
financing-guide.md — Guia de financiamento de carros usados com taxas de juros por score de crédito, recomendações de prazo de empréstimo, estratégias de entrada e cálculos de custo total de propriedade.
powertrain-comparison-guide.md — Comparação detalhada de veículos a combustão (ICE), elétricos a bateria (BEV), híbridos padrão (HEV) e híbridos plug-in (PHEV), incluindo análise de custo em 5 anos.

Clone o repositório para obter esses arquivos:

1
git clone https://github.com/biagolini/PythonAwsBedrockAgentCoreKnowledgeBases.git

Os documentos estão localizados na pasta demos/. Usamos formato markdown para permitir exploração futura de estratégias avançadas de chunking que aproveitam a estrutura do documento (títulos, listas, seções).

1.3 Fazer Upload dos Documentos para o S3

1.3.1. Navegue até o bucket recém-criado no console do S3

1.3.2. Clique em Upload

1.3.3. Faça upload de todos os arquivos markdown da pasta demos/ do repositório complementar

1.3.4. Clique em Upload para confirmar

Os arquivos podem ser colocados diretamente na raiz do bucket. Se preferir, você pode organizá-los em pastas (prefixos). O conector S3 suporta filtros opcionais de inclusão e exclusão de prefixo para limitar a ingestão a caminhos específicos. Para este tutorial, mantemos todos os arquivos na raiz por simplicidade.

Console do Amazon S3 mostrando o conteúdo do bucket com os arquivos markdown sobre carros enviados para a raiz do bucket — Documentos markdown de origem enviados ao bucket S3 que a Knowledge Base irá ingerir

Step 2: Criar o Managed Knowledge Base

Agora criamos um Bedrock Managed Knowledge Base e o conectamos ao nosso bucket S3. O assistente do console cuida da criação do Knowledge Base e da fonte de dados em um único fluxo.

2.1 Navegar até Knowledge Base

2.1.1. Abra o console do Amazon Bedrock AgentCore

2.1.2. No painel de navegação à esquerda, em Built-in tools, clique em Knowledge Base

2.1.3. Clique no botão Create Managed Knowledge Base

Console do Amazon Bedrock AgentCore mostrando a opção Knowledge Base em Built-in tools e o botão Create Managed Knowledge Base — Navegação até a seção Knowledge Base para iniciar a criação de uma Bedrock Managed Knowledge Base

2.2 Configurar Detalhes do Knowledge Base

2.2.1. No campo Knowledge Base name, insira car_kb

2.2.2. Expanda Additional configurations para revisar as configurações padrão:

Description: Insira Used car dealership knowledge base with vehicle guides and financing info
Embedding model type: Mantenha Managed (padrão). A AWS fornece um modelo de embedding integrado, otimizado para precisão e desempenho, sem custo adicional.
IAM permissions: Mantenha Create and use a new service role (recomendado). O console criará uma role com as permissões necessárias para acessar seu bucket S3 e gerenciar o knowledge base.
Encryption: Mantenha a chave gerenciada pela AWS (padrão).

Formulário de criação da Knowledge Base mostrando o campo de nome e o painel Additional configurations com descrição, modelo de embedding gerenciado e nova service role — Configuração do nome da Knowledge Base, descrição, modelo de embedding gerenciado e service role

2.3 Configurar a Fonte de Dados

2.3.1. Em Data source, no campo Data source name, insira car-documents-s3

2.3.2. No dropdown Data source type, selecione Amazon S3

2.3.3. No campo S3 URI, insira o caminho para o seu bucket:

1
s3://<your-bucket-name>/

Substitua <your-bucket-name> pelo nome real do bucket que você criou no Step 1 (por exemplo, agentcore-kb-cars-<your-account-id>).

Seção de fonte de dados do assistente da Knowledge Base mostrando o conector Amazon S3 selecionado e o S3 URI apontando para o bucket de origem — Configuração da fonte de dados Amazon S3 com o URI do bucket que contém os documentos sobre carros

2.4 Configurar Parsing e Chunking (Opcional)

2.4.1. Expanda Content parsing and chunking para revisar os padrões:

Parsing strategy: Mantenha Managed parser (padrão). Isso determina automaticamente a estratégia de parsing ideal para cada tipo de arquivo.
Text chunking strategy: Mantenha Default chunking (recomendado). Isso divide o texto em chunks de tamanho fixo otimizados para recuperação.

Para este tutorial, os padrões funcionam bem com nossos arquivos de texto. Para cenários de produção com documentos complexos (PDFs com tabelas, imagens ou layouts em múltiplas colunas), você pode considerar chunking de tamanho fixo com parâmetros customizados.

2.5 Criar o Knowledge Base

2.5.1. Clique em Create Knowledge Base

2.5.2. Aguarde o knowledge base e a fonte de dados serem criados. Isso normalmente leva de 2 a 5 minutos. O status mostrará Creating e depois mudará para Available quando estiver pronto.

Página de detalhes da Knowledge Base mostrando o status Creating enquanto a AWS provisiona o pipeline de RAG gerenciado — Provisionamento da Knowledge Base em andamento antes de o status mudar para Available

2.6 Sincronizar a Fonte de Dados

Após a criação do knowledge base, você precisa sincronizar (ingerir) os documentos do S3 no knowledge base.

2.6.1. Na página de detalhes do knowledge base, navegue até a seção Data sources

2.6.2. Selecione a fonte de dados car-documents-s3

2.6.3. Clique no botão Sync para iniciar o processo de ingestão

2.6.4. Aguarde a sincronização ser concluída. O status mudará para Syncing e depois voltará para Available. Para três pequenos arquivos de texto, isso deve levar menos de um minuto.

Seção de fontes de dados mostrando a fonte S3 no status Syncing enquanto os documentos são ingeridos e indexados — Sincronização da fonte de dados S3 para ingerir e indexar os documentos na Knowledge Base

Após a sincronização ser concluída, seus documentos estão indexados e o knowledge base está pronto para ser consultado.

2.7 Testar o Knowledge Base no Console

2.7.1. Na página de detalhes do knowledge base, procure a seção ou botão Test

2.7.2. Antes de executar o teste, revise as configurações de Retrieval and response generation. Selecione o modelo que deseja usar para geração de resposta. Para este tutorial, selecionei Amazon Nova Micro para testar a stack com um modelo mínimo e verificar se o pipeline de recuperação funciona corretamente mesmo com um modelo muito pequeno. Você pode escolher um modelo maior para melhor qualidade de resposta.

2.7.3. Insira uma consulta de teste como:

1
What are the main differences between SUVs and sedans for families?

2.7.4. Clique em Run e observe a resposta gerada. Na parte inferior da resposta, observe o botão Trace details.

Painel de teste da Knowledge Base mostrando as configurações de Retrieval and response generation à esquerda, a resposta gerada e o botão Trace details no canto inferior direito — Teste da Knowledge Base no console gerando uma resposta fundamentada com o modelo selecionado

2.7.5. Clique no botão Trace details (ou ative o switch Details no canto superior direito do painel de teste). Isso abre a visualização de trace onde você pode inspecionar como a recuperação foi realizada.

Dentro dos detalhes do trace, você verá duas seções principais:

Speculative retrieval — Esta é uma recuperação inicial que executa antes da etapa de planejamento para reduzir a latência. Para um único knowledge base, o serviço imediatamente recupera resultados usando sua consulta bruta enquanto o foundation model ainda está analisando e planejando sub-consultas. Essa otimização significa que os resultados já estão disponíveis quando a etapa de planejamento é concluída, reduzindo significativamente o tempo total de resposta.
Iteration — Cada iteração representa um ciclo de planejamento e recuperação. O foundation model decompõe sua consulta em sub-consultas, executa-as contra o knowledge base e avalia se os resultados recuperados são suficientes para responder à pergunta original. Caso contrário, planeja e executa iterações adicionais (até o máximo configurado). Para consultas simples, uma única iteração geralmente é suficiente.

Para mais detalhes sobre como o Agentic Retrieval funciona, consulte a documentação da AWS.

2.7.6. Expanda a seção Iteration para ver os chunks individuais recuperados. Cada chunk mostra uma porção de texto dos seus documentos. Clique em Metadata associated with this chunk para ver o ID do documento e o nome do arquivo fonte (por exemplo, suv-vs-sedan-guide.md).

Visão de trace da Knowledge Base mostrando Speculative retrieval, uma iteração expandida com o texto do chunk recuperado e a seção de metadados com o ID do documento e o nome do arquivo — Inspeção do trace de recuperação com recuperação especulativa, chunks de iteração e metadados como ID do documento e arquivo de origem

2.8 Anotar o ID do Knowledge Base

Após a criação, copie o Knowledge Base ID da página de detalhes. Você precisará dele para a configuração do Gateway e testes locais. O ID segue um padrão como XXXXXXXXXX.

Página de detalhes da Knowledge Base destacando o Knowledge Base ID usado para o teste local e a configuração do Gateway — Localização do Knowledge Base ID necessário para as consultas locais e para o conector do Gateway

Step 3: Consultar o Knowledge Base Localmente

Antes de integrar com o Harness, vamos testar o Knowledge Base programaticamente usando a API do Bedrock Agent Runtime. Isso demonstra como qualquer aplicação pode consultar seu knowledge base diretamente.

3.1 Clonar o Repositório e Instalar Dependências

1
2
3
4
5
git clone https://github.com/biagolini/PythonAwsBedrockAgentCoreKnowledgeBases.git
cd PythonAwsBedrockAgentCoreKnowledgeBases
python3.12 -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt

No Windows, substitua o comando de ativação por .venv\Scripts\activate.

3.2 Configurar Variáveis de Ambiente

1
cp .env.example .env

Edite o .env:

1
2
AWS_REGION=us-east-1
KNOWLEDGE_BASE_ID=<your-knowledge-base-id>

Substitua <your-knowledge-base-id> pelo ID do Knowledge Base que você copiou no Step 2.8.

3.3 Executar o Script de Recuperação

O script kb_retrieve.py demonstra uma consulta simples de recuperação contra o knowledge base. Ele envia uma consulta em linguagem natural e recebe trechos relevantes com referências de origem.

1
# kb_retrieve.py

Execute o script:

1
python kb_retrieve.py

Saída esperada:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
Query: What SUVs are good for families with a budget under $25,000?

--- Retrieved Passages ---

Result 1 (score: 0.7049):
  Source: https://<your-bucket-name>.s3.amazonaws.com/suv-vs-sedan-guide.md
  Content: For buyers in the $20,000-$30,000 range (used vehicles, 2-4 years old):

# Used Mid-Size SUVs

- Toyota RAV4: $22,000-$28,000
- Honda CR-V: $21,000-$27,000
- Mazda CX-5: $20,000-$26,000...

Result 2 (score: 0.6043):
  Source: https://<your-bucket-name>.s3.amazonaws.com/suv-vs-sedan-guide.md
  Content: ### Drawbacks

The main drawbacks of SUVs are higher fuel consumption (typically 20-28 MPG for mid-size, 15-22 MPG for full-size), higher purchase price, and increased maintenance costs due to larger...

Result 3 (score: 0.5548):
  Source: https://<your-bucket-name>.s3.amazonaws.com/suv-vs-sedan-guide.md
  Content: # SUV vs Sedan: A Complete Guide for American Families

When choosing between an SUV and a sedan, American families face a decision that impacts daily comfort, safety, and long-term costs...

O knowledge base recuperou com sucesso trechos relevantes sobre SUVs, preços e financiamento dos nossos documentos. Os resultados incluem scores de confiança e referências de origem, permitindo que o agente cite suas fontes.

Step 4: Criar um Gateway com o Conector de Knowledge Base

Para conectar o Knowledge Base ao Harness, precisamos expô-lo através do AgentCore Gateway como uma ferramenta MCP. Isso segue o mesmo padrão usado no artigo sobre Gateway e no artigo sobre Web Search : criar um Gateway, adicionar um connector target e anexar o Gateway ao Harness.

O conector de Knowledge Base (bedrock-knowledge-bases) expõe duas ferramentas:

AgenticRetrieveStream — Recuperação agêntica em múltiplas etapas com streaming. O serviço planeja, recupera em múltiplos passos e retorna uma resposta sintetizada com citações.
Retrieve — Busca híbrida única que retorna os trechos mais relevantes com referências de origem.

4.1 Criar a Role de Execução do Gateway

4.1.1. Navegue até IAM > Roles no Console AWS

4.1.2. Clique em Create role

4.1.3. Selecione Custom trust policy e insira a seguinte trust policy:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Sid": "AllowAgentCoreToAssumeRole",
      "Effect": "Allow",
      "Principal": {
        "Service": "bedrock-agentcore.amazonaws.com"
      },
      "Action": "sts:AssumeRole",
      "Condition": {
        "StringEquals": {
          "aws:SourceAccount": "<your-account-id>"
        },
        "ArnLike": {
          "aws:SourceArn": "arn:aws:bedrock-agentcore:<your-region>:<your-account-id>:gateway/*"
        }
      }
    }
  ]
}

4.1.4. Clique em Next. Pule as políticas gerenciadas. Clique em Next.

4.1.5. No campo Role name, insira AgentCoreGatewayKnowledgeBase

4.1.6. Clique em Create role

4.1.7. Após a criação, abra a role e clique em Add permissions > Create inline policy. Selecione a aba JSON e insira:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Sid": "GetGateway",
      "Effect": "Allow",
      "Action": "bedrock-agentcore:GetGateway",
      "Resource": "arn:aws:bedrock-agentcore:<your-region>:<your-account-id>:gateway/*"
    },
    {
      "Sid": "ValidateKnowledgeBase",
      "Effect": "Allow",
      "Action": "bedrock:GetKnowledgeBase",
      "Resource": "arn:aws:bedrock:<your-region>:<your-account-id>:knowledge-base/<your-kb-id>"
    },
    {
      "Sid": "RetrieveFromKnowledgeBase",
      "Effect": "Allow",
      "Action": "bedrock:Retrieve",
      "Resource": "arn:aws:bedrock:<your-region>:<your-account-id>:knowledge-base/<your-kb-id>"
    },
    {
      "Sid": "AgenticRetrieveStream",
      "Effect": "Allow",
      "Action": "bedrock:AgenticRetrieveStream",
      "Resource": "*"
    }
  ]
}

Substitua <your-region>, <your-account-id> e <your-kb-id> pelos seus valores reais.

4.1.8. Clique em Next, nomeie a política como GatewayKnowledgeBaseAccess e clique em Create policy

4.2 Criar o Gateway

Siga o mesmo processo de criação de Gateway descrito no artigo sobre Gateway , com estas configurações específicas:

4.2.1. Navegue até Amazon Bedrock AgentCore > Gateways

4.2.2. Clique em Create Gateway

Step 1 — Definir detalhes do gateway:

4.2.3. No campo Gateway name, insira KnowledgeBaseGateway

4.2.4. Em Permissions, selecione Use another role e escolha AgentCoreGatewayKnowledgeBase

4.2.5. Clique em Next

Primeira página do assistente de criação do Gateway com o campo de nome preenchido e a opção Use another role selecionando a role de execução da Knowledge Base — Definição do nome do gateway e atribuição da role de execução da Knowledge Base durante a criação

Step 2 — Configurar Identidade de Entrada:

4.2.6. Em Inbound Auth type, selecione No authorization (para este tutorial). Clique em Next.

Segunda página do assistente de criação do Gateway mostrando o tipo de autenticação de entrada definido como No authorization para este tutorial — Configuração da identidade de entrada com No authorization para o Gateway da Knowledge Base

Step 3 — Adicionar targets:

4.2.7. Em Select a target protocol, selecione MCP target

4.2.8. No campo Target name, insira CarDealershipKB

4.2.9. No campo Target description, insira Car dealership knowledge base with vehicle guides, maintenance tips, and financing information

4.2.10. Em Target type, selecione Connectors

4.2.11. Em Pre-configured targets, selecione Knowledge Bases (KB)

4.2.12. Em Runtime retrieval type, mantenha Standard retrieval selecionado

4.2.13. No dropdown Knowledge Base (KB), selecione car_kb

4.2.14. Em Outbound Auth configurations, mantenha IAM Role selecionado

4.2.15. No campo Tool description, insira:

1
Search the car dealership knowledge base for information about vehicle comparisons (SUVs, sedans, electric, hybrid), maintenance tips, and financing guides. Use this tool when the customer asks about car features, pricing, maintenance schedules, or financing options.

Essa descrição ajuda o agente a entender quando invocar a ferramenta do Knowledge Base. Uma descrição de ferramenta bem escrita leva a uma seleção mais precisa da ferramenta.

4.2.16. Em Additional configurations (opcional), você pode customizar o comportamento de recuperação. Para este tutorial, mantemos os padrões, mas estas opções estão disponíveis:

Guardrail — Anexe um Bedrock Guardrail para filtrar entradas e respostas geradas (não aplicado aos resultados brutos de recuperação do KB).
Reranking — Habilite um modelo de reranking secundário para melhorar a relevância dos resultados. As opções são: sem reranking, padrão (reranker gerenciado pelo serviço) ou customizado (selecione um modelo específico).
Agent overrides — Permita que o agente substitua configurações padrão em tempo de chamada, como Source chunks count (quantos chunks recuperar) e User context (para filtragem de controle de acesso).

4.2.17. Clique em Next

Terceira página do assistente de criação do Gateway mostrando o target MCP com o conector Knowledge Bases, a knowledge base de carros selecionada e a descrição da ferramenta preenchida — Adição do conector da Knowledge Base como target MCP com uma descrição de ferramenta que orienta o agente sobre quando pesquisar

Step 4 — Revisar e criar:

4.2.14. Revise sua configuração e clique em Create

4.2.15. Aguarde o status do Gateway e do target ficarem como Ready

4.3 Anotar o ARN do Gateway

Após a criação, copie o Gateway ARN da página de detalhes do Gateway. Você precisará dele ao conectar ao Harness.

4.4 Testar o Gateway Localmente

Antes de integrar com o Harness, você pode testar o Gateway localmente usando o Strands Agents SDK. O script kb_gateway_agent.py conecta-se ao Knowledge Base através do Gateway via protocolo MCP, descobre as ferramentas de recuperação e permite que o agente responda perguntas fundamentadas nos seus documentos.

4.4.1. Adicione o Gateway ID ao seu arquivo .env:

1
GATEWAY_ID=<your-gateway-id>

4.4.2. O script kb_gateway_agent.py conecta-se ao Knowledge Base através do Gateway via protocolo MCP, descobre as ferramentas de recuperação e permite que o agente responda perguntas fundamentadas nos seus documentos.

1
# kb_gateway_agent.py

Execute o script:

1
python kb_gateway_agent.py

O agente se conectará ao Gateway, descobrirá as ferramentas de recuperação do Knowledge Base, pesquisará seus documentos e gerará uma resposta fundamentada com informações dos arquivos enviados.

Step 5: Conectar o Gateway ao Harness

Agora anexamos o Gateway do Knowledge Base ao nosso Harness de concessionária de carros para que o agente possa pesquisar nossos documentos e responder perguntas dos clientes fundamentadas em dados reais.

5.1 Editar o Harness

5.1.1. Navegue até Amazon Bedrock AgentCore > Harness

5.1.2. Clique no nome do seu Harness (car_agent) para abrir a página de detalhes

5.1.3. Clique no botão Edit

5.1.4. Na seção Tools, clique em Add Gateway e selecione KnowledgeBaseGateway

5.1.5. Em Outbound Auth configurations, mantenha IAM role (padrão) selecionado. Isso permite que o Harness se autentique com o Gateway usando sua role de execução.

5.1.6. Clique em Save Harness e aguarde o status retornar para Ready

Após salvar, o console pode exibir uma mensagem sugerindo que a role de execução do Harness precisa ser atualizada com a permissão bedrock-agentcore:InvokeGateway no ARN do Gateway. Se essa mensagem aparecer, siga as instruções fornecidas pelo console para atualizar a role.

5.2 Testar com o Harness

5.2.1. Quando o Harness estiver Ready, clique no botão Test Harness

5.2.2. Insira um prompt que deve acionar uma busca no knowledge base:

1
A customer is asking: I have a family of 4 and a budget of $25,000. Should I buy an SUV or a sedan? What are the pros and cons of each?

5.2.3. Observe a resposta. O agente usa o Knowledge Base para recuperar informações relevantes e gera uma resposta fundamentada com detalhes específicos dos seus documentos (modelos de veículos, faixas de preço, prós e contras). Na seção Agent trace, você verá um link azul clicável chamado CarDealershipKB Retrieve, indicando que o agente invocou a ferramenta do Knowledge Base.

Interface de teste do Harness mostrando a resposta fundamentada do agente com a seção Agent trace e o link CarDealershipKB Retrieve indicando uma chamada à Knowledge Base — Teste do Harness com um prompt que aciona uma busca na Knowledge Base e produz uma resposta fundamentada

5.2.4. Clique no link CarDealershipKB Retrieve para abrir o painel de detalhes da invocação da ferramenta. Este painel tem duas abas: Input e Output.

5.2.5. A aba Input mostra a consulta que o agente enviou ao Knowledge Base. Observe que o agente formulou sua própria consulta de recuperação baseada na pergunta do usuário. Neste caso, ele enviou uma consulta como "pros and cons of SUVs and seda..." para o campo retrievalQuery.text. Isso demonstra que o agente decide autonomamente o que pesquisar com base no contexto da conversa.

Aba Input do painel de invocação da ferramenta mostrando o texto de retrievalQuery que o agente enviou de forma autônoma para a Knowledge Base — Análise da consulta de recuperação que o agente formulou por conta própria com base na pergunta do cliente

5.2.6. A aba Output mostra os resultados brutos de recuperação retornados pelo Knowledge Base. Estes são os dados que o agente usou para compor sua resposta. A estrutura inclui:

retrievalResults — Um array de chunks recuperados dos seus documentos, ordenados por score de relevância.
content.text — O trecho de texto real extraído do documento.
documentId — O URI do S3 identificando o documento fonte.
location — Os detalhes de localização no S3 (bucket e key).
metadata — Metadados ricos incluindo _document_title (nome do arquivo), _source_uri (URL completa do S3), _chunk_id, _file_type, _language_code, _created_at, _last_updated_at e _data_source_id.
score — O score de relevância para o chunk (por exemplo, 0.7226). Scores mais altos indicam correspondência semântica mais forte com a consulta.

Esta saída mostra exatamente quais trechos dos seus documentos o agente recuperou e quão relevante cada um era. O agente então usa esses chunks para compor uma resposta informada e fundamentada em vez de alucinar informações.

Aba Output do painel de invocação da ferramenta mostrando o array retrievalResults com o texto dos chunks, IDs de documento, metadados e pontuações de relevância retornados pela Knowledge Base — Inspeção dos resultados brutos de recuperação com texto dos chunks, metadados e pontuações de relevância usados para compor a resposta fundamentada

Step 6: Limpeza

Se você não pretende continuar usando os recursos criados neste tutorial, remova-os para evitar cobranças desnecessárias. Para detalhes de preços, consulte a página de preços do AgentCore .

Para remover os recursos:

Remova o Gateway do Harness (edite o Harness e remova a ferramenta Gateway)
Navegue até Amazon Bedrock AgentCore > Gateways, selecione KnowledgeBaseGateway e delete-o
Navegue até Amazon Bedrock AgentCore > Built-in tools > Knowledge Base, selecione car_kb e delete-o
Navegue até Amazon S3, selecione o bucket que você criou, esvazie-o e delete-o
Navegue até IAM > Roles, delete a role AgentCoreGatewayKnowledgeBase

Conclusão

Neste artigo, você aprendeu como usar Amazon Bedrock Managed Knowledge Bases para fundamentar as respostas do seu agente em dados privados:

Três tipos de KB atendem diferentes necessidades: Managed KB para RAG totalmente gerenciado sem infraestrutura, Unstructured Vector Store KB para controle customizado do banco vetorial, e Structured Data Store KB para recuperação baseada em SQL de dados relacionais.
Managed KB cuida de todo o pipeline: você fornece os documentos, e a AWS gerencia ingestão, embedding, armazenamento e recuperação. O modelo de embedding integrado e o reranker estão inclusos sem custo adicional.
O caminho de integração para o Harness é sempre através do AgentCore Gateway. Você cria um Gateway com o conector bedrock-knowledge-bases, que expõe Retrieve e AgenticRetrieveStream como ferramentas MCP que o agente descobre e chama automaticamente.
Respostas fundamentadas incluem citações de fontes, permitindo que os usuários verifiquem as informações que o agente fornece. Isso constrói confiança e responsabilidade em implantações de produção.

Os principais aprendizados são:

Knowledge Bases são a forma recomendada de dar aos agentes acesso aos seus documentos privados. O agente decide quando pesquisar com base no contexto da conversa.
A opção Managed KB elimina todo o gerenciamento de infraestrutura. Sem banco vetorial para provisionar, sem modelo de embedding para selecionar, sem reranking para configurar.
O padrão do Gateway é consistente entre todos os tipos de ferramentas no AgentCore. Seja Web Search, funções Lambda ou Knowledge Bases, a integração segue o mesmo fluxo: criar um Gateway target, anexar ao Harness.
Para implantações de produção, combine Knowledge Bases com outras ferramentas do AgentCore (Memory para personalização, Code Interpreter para cálculos, Web Search para informações atuais) para construir agentes abrangentes.

Referências

Fique Conectado

Se você achou este artigo útil e quer aprender mais sobre AWS, arquitetura cloud, IA, infraestrutura como código e segurança na nuvem, siga o autor para conteúdos futuros e tutoriais:

LinkedIn: https://www.linkedin.com/in/biagolini
Medium: https://medium.com/@biagolini
GitHub: https://github.com/biagolini
YouTube (PT-BR): https://www.youtube.com/@BiagoliniTech
AWS Builder Center (PT-BR): https://builder.aws.com/community/@cbiagolini

Fique ligado para mais walkthroughs práticos e soluções para desafios de infraestrutura cloud e DevOps.

Happy building on AWS! 🚀☁️

# amazon-bedrock-agentcore # amazon-bedrock # agents # ai

Series: Primeiros Passos com o Amazon Bedrock AgentCore Code (8 articles)

1
Primeiros Passos com Amazon Bedrock AgentCore Harness e Runtime
…
8
Primeiros Passos com Amazon Bedrock AgentCore Knowledge Bases This article

Any opinions in this article are those of the individual author and may not reflect the opinions of AWS.

Enjoyed reading this content? Let the author know!

Your likes, comments, shares, and saves help creators reach more builders.

Loading recommendations

Loading article

Builder Center

Primeiros Passos com Amazon Bedrock AgentCore Knowledge Bases

Series: Primeiros Passos com o Amazon Bedrock AgentCore Code (8 articles)

Carlos Biagolini

Introdução

Tipos de Knowledge Base

Resumo Comparativo

Pré-requisitos

Step 1: Criar um Bucket S3 com Documentos sobre Carros

1.1 Criar o Bucket S3

1.2 Criar os Documentos

1.3 Fazer Upload dos Documentos para o S3

Step 2: Criar o Managed Knowledge Base

2.1 Navegar até Knowledge Base

2.2 Configurar Detalhes do Knowledge Base

2.3 Configurar a Fonte de Dados

2.4 Configurar Parsing e Chunking (Opcional)

2.5 Criar o Knowledge Base

2.6 Sincronizar a Fonte de Dados

2.7 Testar o Knowledge Base no Console

2.8 Anotar o ID do Knowledge Base

Step 3: Consultar o Knowledge Base Localmente

3.1 Clonar o Repositório e Instalar Dependências

3.2 Configurar Variáveis de Ambiente

3.3 Executar o Script de Recuperação

Step 4: Criar um Gateway com o Conector de Knowledge Base

4.1 Criar a Role de Execução do Gateway

4.2 Criar o Gateway

4.3 Anotar o ARN do Gateway

4.4 Testar o Gateway Localmente

Step 5: Conectar o Gateway ao Harness

5.1 Editar o Harness

5.2 Testar com o Harness

Step 6: Limpeza

Conclusão

Referências

Fique Conectado

Series: Primeiros Passos com o Amazon Bedrock AgentCore Code (8 articles)