Como Construir um Assistente de Reparo de Equipamentos com IA Usando o Amazon Bedrock AgentCore

O problema que essa solução resolve

Quem trabalha com manutenção de maquinário agrícola pesado conhece bem o cenário: o técnico chega ao campo sem a peça certa, o equipamento fica parado, e durante a época de colheita cada hora de inatividade representa prejuízo real. A AWS publicou um guia técnico mostrando como o Amazon Bedrock AgentCore pode ser usado para construir um assistente de reparo com Inteligência Artificial (IA) que ajuda agricultores e técnicos de campo a diagnosticar problemas, identificar peças necessárias e acessar procedimentos de reparo aprovados pelos fabricantes — tudo por linguagem natural.

Visão geral da arquitetura

A solução combina um frontend web com um agente hospedado no AgentCore que responde perguntas de diagnóstico consultando documentação técnica indexada dos fabricantes. Os componentes principais são:

AgentCore Runtime com o Strands Agents SDK para hospedar e executar o agente
Amazon Nova 2 Lite como modelo de fundação para inferência
Amazon Bedrock Knowledge Base para Geração Aumentada por Recuperação (RAG — Retrieval-Augmented Generation)
AgentCore Memory para persistência de conversas entre sessões
Amazon Cognito para autenticação de usuários
AWS Amplify para hospedar a aplicação web React

A arquitetura é organizada em quatro seções principais:

Seção A – Autenticação e Frontend: Uma stack do CloudFormation implanta o Amazon Cognito (User Pool e Identity Pool) e o AWS Amplify. Os usuários se autenticam pelo Cognito, e o frontend se comunica diretamente com o endpoint do AgentCore Runtime.
Seção B – AgentCore Runtime: Hospeda o agente baseado em Strands e expõe o endpoint /invocations. O frontend chama esse endpoint usando um token Bearer do Cognito. O agente roteia requisições internamente com base no campo path do payload (/chat para consultas de IA e /issues para operações de criação, leitura, atualização e exclusão — CRUD).
Seção C – Processamento com IA: O agente Strands usa uma ferramenta customizada chamada search_equipment_knowledge que consulta a Base de Conhecimento do Bedrock via API retrieve_and_generate. A Base de Conhecimento indexa documentação armazenada no Amazon S3 usando o Amazon OpenSearch Serverless para busca vetorial e o Amazon Titan Embeddings para correspondência semântica.
Seção D – Dados e Memória: O Amazon DynamoDB armazena os chamados de serviço dos equipamentos. O AgentCore Memory oferece memória de curto prazo (dentro da sessão) e de longo prazo (entre sessões). O Amazon CloudWatch e o AWS X-Ray fornecem observabilidade automática.

Como o fluxo de uma consulta funciona

O caminho percorrido desde a pergunta do técnico até a resposta do agente segue estas etapas:

O técnico abre a aplicação web e se autentica pelo Amazon Cognito.
A pergunta é enviada ao endpoint /invocations do AgentCore Runtime com um token Bearer do Cognito.
O AgentCore valida o token, encaminha a requisição ao agente e recupera o contexto de conversas anteriores.
O agente Strands envia a consulta ao Amazon Nova 2 Lite para inferência.
O modelo invoca a ferramenta search_equipment_knowledge, que consulta a Base de Conhecimento do Bedrock.
A Base de Conhecimento pesquisa os manuais indexados e retorna documentação relevante com citações de fontes.
O modelo sintetiza uma resposta de diagnóstico com procedimentos de reparo e recomendações de peças, devolvendo o resultado ao técnico com atribuição de fonte para verificação.

O código da ferramenta de busca na Base de Conhecimento

O trecho abaixo mostra como a ferramenta de recuperação do agente consulta a documentação dos fabricantes:

@tool
def search_equipment_knowledge(query: str) -> str:
    """Search equipment manuals, parts catalogs, and repair docs."""
    response = bedrock_agent_runtime.retrieve_and_generate(
        input={"text": query},
        retrieveAndGenerateConfiguration={
            "type": "KNOWLEDGE_BASE",
            "knowledgeBaseConfiguration": {
                "knowledgeBaseId": KNOWLEDGE_BASE_ID,
                "modelArn": f"arn:aws:bedrock:{REGION}::foundation-model/{MODEL_ID}",
            },
        },
    )
    return response.get("output", {}).get("text", "No results found.")

Pré-requisitos e estimativa de custos

Antes de começar a implantação, é necessário ter:

Uma conta AWS com permissões adequadas para implantar agentes AgentCore. As permissões de Gerenciamento de Identidade e Acesso (IAM — Identity and Access Management) necessárias estão documentadas em IAM Permissions for AgentCore Runtime.
Acesso ao modelo Amazon Nova 2 Lite no Amazon Bedrock na região de implantação. É possível usar outro modelo suportado — consulte disponibilidade de modelos por região.
AWS Command Line Interface (AWS CLI) v2.0 ou superior instalado e configurado.
Python 3.10 ou mais recente instalado.

Em termos de custos para testes, os principais são as invocações do modelo Amazon Nova 2 Lite (US$ 0,30/US$ 2,50 por milhão de tokens de entrada/saída) e a Base de Conhecimento do Bedrock (OpenSearch Serverless a aproximadamente US$ 0,24/hora enquanto ativo). Os demais serviços — AgentCore Runtime, Amazon DynamoDB, Amazon S3, Amazon Cognito e AWS Amplify — se enquadram no nível gratuito da AWS para volumes de teste. Para estimativas detalhadas, utilize a AWS Pricing Calculator.

Criando a Base de Conhecimento

Passo 1: Prepare a documentação

Para testes, a AWS recomenda baixar manuais de equipamentos da John Deere Technical Information Store — o guia usa especificamente os manuais dos tratores compactos John Deere 1023E e 1025R. Também é possível usar a documentação da própria organização. Os documentos devem ser pesquisáveis por texto (não imagens escaneadas), com nomenclatura consistente e sem informações proprietárias que não devam ser acessíveis a todos os usuários.

Passo 2: Crie um bucket S3 para a Base de Conhecimento

aws s3 mb s3://agriculture-kb-documents-<unique-suffix>
aws s3 cp ./equipment-docs s3://agriculture-kb-documents-<unique-suffix> --recursive

Passo 3: Crie a Base de Conhecimento do Bedrock

Siga as instruções da documentação para criar a Base de Conhecimento com as seguintes configurações:

Nome: Agriculture-Equipment-Repair-KB
Fonte de dados: o bucket S3 criado no passo anterior
Estratégia de parsing: parser padrão do Amazon Bedrock
Estratégia de chunking: chunking padrão
Modelo de embeddings: Amazon Titan Embeddings G1 – Text
Vector store: criação rápida de um novo (Amazon OpenSearch Serverless)

Passo 4: Sincronize e teste a Base de Conhecimento

Após criar a Base de Conhecimento, sincronize a fonte de dados para iniciar a ingestão dos documentos (normalmente 10 a 20 minutos). Consulte como sincronizar suas fontes de dados. Use a funcionalidade de teste no console do Bedrock para verificar se a Base de Conhecimento responde corretamente. Anote o ID da Base de Conhecimento na página de detalhes.

Implantando a solução

Passo 5: Implante a infraestrutura de suporte

Inicie a stack do CloudFormation. Nos parâmetros, informe um nome para o deployment (padrão: ag-repair-assist) e o ID da Base de Conhecimento do passo anterior. Após a conclusão, anote os valores da aba Outputs da stack — eles serão usados nos passos seguintes.

Passo 6: Implante o agente a partir da máquina local

Com Python 3.10 ou superior e credenciais AWS configuradas, execute os seguintes comandos:

mkdir agriculture-repair-agent && cd agriculture-repair-agent
python3 -m venv .venv
source .venv/bin/activate

pip install "bedrock-agentcore-starter-toolkit>=0.1.21" strands-agents strands-agents-tools boto3

Em seguida, baixe e extraia o código do agente (dois arquivos: agriculture_repair_agent.py e requirements.txt). Configure o agente com:

agentcore configure -e agriculture_repair_agent.py

Durante a configuração interativa, selecione “Direct Code Deploy” (sem Docker), informe o ARN do papel de execução, a URL de descoberta OAuth do Cognito e o ID do cliente do User Pool — todos obtidos dos Outputs do CloudFormation. Depois, faça o deploy:

agentcore launch --env KNOWLEDGE_BASE_ID=<your-kb-id> --env TABLE_NAME=<EquipmentIssuesTableName> --env MODEL_ID=us.amazon.nova-2-lite-v1:0

O processo leva aproximadamente 5 a 10 minutos. Ao final, anote o ARN do AgentCore Runtime gerado.

Passo 7: Implante o frontend

Baixe o arquivo ML-18699-FrontEnd.zip, acesse o console do AWS Amplify pela URL fornecida nos Outputs do CloudFormation, clique em “Deploy updates”, escolha o método de arrastar e soltar, selecione o arquivo .zip e aguarde a conclusão do deploy.

Usando a aplicação

Acesse a URL da aplicação Amplify, configure os valores obtidos nos passos anteriores, crie uma conta, verifique o e-mail e faça login. Alguns exemplos de consultas para testar:

Análise de problema: “My John Deere 1023E series tractor is losing hydraulic pressure on the left side when lifting heavy implements. The pressure drops from 2500 PSI to about 1800 PSI under load.”
Consulta técnica: “What hydraulic fluid is recommended for John Deere 1025R?”

Limpeza dos recursos

Os recursos implantados geram cobranças contínuas até serem removidos. Para encerrar tudo:

agentcore destroy

aws cloudformation delete-stack --stack-name ag-repair-assist

No console do Amazon Bedrock Knowledge Bases, selecione Agriculture-Equipment-Repair-KB e escolha Delete. Por fim, esvazie e remova o bucket S3:

aws s3 rm s3://agriculture-kb-documents-<unique-suffix> --recursive
aws s3 rb s3://agriculture-kb-documents-<unique-suffix>

Considerações para produção

A solução foi projetada para ser leve e servir como ponto de partida. Para ambientes produtivos, a AWS recomenda considerar os seguintes aprimoramentos:

Amazon Bedrock Guardrails: Adicionar detecção de ataques de prompt e filtragem de conteúdo para proteger contra entradas maliciosas, além de configurar tópicos negados para limitar o escopo do agente.
Proteção de API: Posicionar o Amazon CloudFront na frente do endpoint do AgentCore Runtime com AWS WAF para limitação de taxa e proteção OWASP.
Autenticação multifator: Habilitar MFA no Amazon Cognito com tokens de software baseados em TOTP.
Observabilidade e alertas: O AgentCore gera automaticamente métricas, logs e rastreamentos visíveis nos dashboards de observabilidade de IA generativa do Amazon CloudWatch. Configure alarmes para taxas de erro e latência de resposta.
Ciclo de vida dos dados: Implementar políticas de ciclo de vida no Amazon S3 para versionamento de documentação e recuperação point-in-time no Amazon DynamoDB.
Deploy multi-região: Para equipes de campo globais, implantar o AgentCore Runtime em múltiplas regiões AWS com Bases de Conhecimento específicas por região.

Próximos passos e extensibilidade

Uma das vantagens da arquitetura é que novas capacidades podem ser adicionadas simplesmente criando uma nova função com o decorador @tool no código do agente — sem necessidade de alterações na infraestrutura. Algumas extensões sugeridas pela AWS:

Integração com pedidos de peças: Uma ferramenta @tool que conecta ao sistema de estoque e permite verificar disponibilidade e fazer pedidos diretamente da conversa de diagnóstico.
Comunicação com revendedores: Uma ferramenta que envia resumos de diagnóstico ao revendedor autorizado mais próximo via Amazon Simple Email Service (SES) ou Amazon Simple Notification Service (SNS).
Integração com telemetria IoT: Conectar sensores dos equipamentos via AWS IoT Core para criar chamados automaticamente quando leituras anômalas forem detectadas, pré-populando o contexto de diagnóstico do agente.
Aplicativo mobile para campo: Construir um frontend otimizado para mobile com cache offline para áreas com conectividade limitada.

Benefícios da implementação

De acordo com a AWS, os principais benefícios dessa arquitetura são:

Redução do tempo médio de resolução por meio de diagnósticos mais rápidos fundamentados na documentação dos fabricantes
Melhora nas taxas de resolução na primeira visita, já que os técnicos chegam ao local com as peças e procedimentos corretos
Memória de conversa que mantém contexto dentro de sessões e persiste conhecimento entre sessões
Operações simplificadas: um único endpoint AgentCore Runtime substitui a necessidade de API Gateway, Lambda e Bedrock Agent separados
Observabilidade integrada com rastreamento X-Ray e integração com CloudWatch sem configuração adicional
Desenvolvimento orientado a código com o padrão @tool do Strands Agent, permitindo extensão e teste local antes do deploy

O código de exemplo deste guia está disponível sob a licença MIT-0.

Recursos adicionais

Fonte

Build an AI-Powered Equipment Repair Assistant Using Amazon Bedrock AgentCore (https://aws.amazon.com/blogs/machine-learning/build-an-ai-powered-equipment-repair-assistant-using-amazon-bedrock-agentcore/)