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 campopathdo payload (/chatpara consultas de IA e/issuespara 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_knowledgeque consulta a Base de Conhecimento do Bedrock via APIretrieve_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
/invocationsdo 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> --recursivePasso 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/activatepip install "bedrock-agentcore-starter-toolkit>=0.1.21" strands-agents strands-agents-tools boto3Em 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.pyDurante 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:0O 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 destroyaws cloudformation delete-stack --stack-name ag-repair-assistNo 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
@toolque 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
@tooldo 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
- Documentação do Amazon Bedrock AgentCore
- Strands Agents SDK
- Guia do Usuário do Amazon Bedrock
- Amazon Bedrock Knowledge Bases
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/)
