Primeiros Passos com Amazon Bedrock AgentCore Harness e Runtime
O Amazon Bedrock AgentCore oferece dois caminhos distintos para executar agentes em escala. Entenda a diferença arquitetural, os trade-offs e qual se encaixa no seu caso de uso.
Series: Primeiros Passos com o Amazon Bedrock AgentCore Code (7 articles)
- 1Primeiros Passos com Amazon Bedrock AgentCore Harness e Runtime This article
Introdução
Agentes de IA estão saindo da fase de experimentação e entrando em produção. Organizações estão implantando agentes que raciocinam sobre dados, chamam ferramentas externas, mantêm histórico de conversas e executam fluxos de trabalho com múltiplas etapas de forma autônoma. O desafio já não é mais construir uma prova de conceito. É operar agentes de forma confiável em escala: isolamento entre sessões, autenticação, observabilidade, escalabilidade e controle de custos.
A AWS oferecia anteriormente o Amazon Bedrock Agents (agora chamado Bedrock Agents Classic) como solução gerenciada para cargas de trabalho com agentes. Esse serviço entrou em modo de manutenção em julho de 2026 e não está mais aberto para novos clientes. Seu sucessor é o Amazon Bedrock AgentCore .
O Amazon Bedrock AgentCore é uma plataforma para construir, implantar e operar agentes de IA em escala. Ele inclui múltiplos serviços modulares que funcionam juntos ou de forma independente: Runtime, Harness, Memory, Gateway, Identity, Code Interpreter, Browser, Observability, Evaluations, entre outros. Cada serviço resolve uma parte específica do ciclo de vida do agente.
Este artigo é o primeiro de uma série explorando os componentes do AgentCore. Aqui, o objetivo é apresentar e comparar as duas formas de executar agentes no AgentCore: Harness e Runtime. Para ilustrar a diferença, criaremos um agente simples para uma revendedora de carros usados. Este caso de uso se conecta a artigos e códigos anteriores no meu blog . É um cenário direto que nos permitirá explorar múltiplas funcionalidades do AgentCore em artigos futuros.
Harness vs Runtime: A Diferença Conceitual
O AgentCore oferece dois caminhos para implantar agentes. Ambos rodam na mesma infraestrutura subjacente (microVMs serverless com isolamento por sessão), mas diferem em quem é o responsável pelo loop de orquestração.
AgentCore Harness
O Harness é um loop de agente gerenciado. Você declara o que o agente é (modelo, system prompt, ferramentas, memória, limites) como configuração, e o AgentCore executa a orquestração. Alimentado pelo Strands Agents , o Harness cuida da execução de ferramentas, gerenciamento de memória e geração de respostas. Você não escreve código de orquestração.
Características principais:
- Orientado por configuração. Trocar um modelo ou adicionar uma ferramenta é uma mudança de configuração, não um redeploy.
- Cada sessão roda em uma microVM isolada com seu próprio sistema de arquivos e shell.
- Suporta modelos do Amazon Bedrock, OpenAI, Google Gemini e qualquer provedor compatível com LiteLLM.
- Integra-se nativamente com AgentCore Memory, Gateway, Browser, Code Interpreter e Observability.
- O caminho recomendado para a maioria dos casos de uso segundo a documentação da AWS.
AgentCore Runtime
O Runtime é um ambiente de hospedagem serverless. Você traz seu próprio código de agente, escrito em qualquer framework (Strands, LangGraph, CrewAI, LlamaIndex, OpenAI Agents SDK ou customizado), empacota em um container ARM64, envia para o Amazon ECR e implanta. O loop de orquestração é seu.
Características principais:
- Você escreve o loop do agente e controla cada aspecto da orquestração.
- Suporta qualquer framework, qualquer modelo, qualquer protocolo (MCP, A2A).
- Sessões rodam em microVMs isoladas (mesma infraestrutura do Harness).
- Execução estendida de até 8 horas para cargas de trabalho de longa duração ou assíncronas.
- Para usar serviços do AgentCore (Memory, Gateway, Browser), você os chama a partir do seu código via SDK do AgentCore.
Quando Usar Cada Um
- Harness: Comece por aqui. Use quando seu agente pode ser expresso como modelo + system prompt + ferramentas. A maioria dos agentes se encaixa neste padrão. Você obtém integração completa com o AgentCore sem código de orquestração.
- Runtime: Use quando precisar de lógica de orquestração customizada, padrões de supervisor multi-agente, overrides de prompt em etapas específicas, ou uma base de código de agente existente que você deseja hospedar em infraestrutura gerenciada.
O Harness é na verdade uma abstração gerenciada que roda sobre o Runtime. Se você ultrapassar os limites do Harness, pode exportá-lo para código e implantá-lo no Runtime sem começar do zero.
Criando um Harness: Métodos Disponíveis
Existem três caminhos para criar um Harness, todos levando ao mesmo resultado:
- Console AWS (Quick create / Advanced create) - interface gráfica, ideal para exploração e configuração inicial.
- AgentCore CLI (
agentcore create) - ferramenta de linha de comando com scaffolding de projeto, adequada para desenvolvimento iterativo. - AWS CLI / SDK (
aws bedrock-agentcore-control create-harnessou boto3) - chamadas diretas à API, melhor para automação e pipelines de CI/CD.
Neste artigo, usamos o Console AWS para uma experiência visual passo a passo.
Step 1: Criar o Harness via Console AWS
1.1 Abrir o Console do AgentCore Harness
1.1.1. Navegue até Amazon Bedrock AgentCore > Harness no Console AWS.
1.1.2. Clique no botão Create Harness. Você verá uma seta dropdown ao lado dele. Clique na seta para expandir as opções: Quick create Harness e Advanced create Harness.
1.1.3. Selecione Advanced create Harness. Isso lhe dá controle sobre a seleção de modelo e system prompt durante a criação.
O menu suspenso ao lado do botão Create Harness revela dois modos de criação. Selecionar Advanced create Harness oferece controle sobre a escolha do modelo e a configuração do prompt de sistema durante o processo de criação.
1.2 Configurar o Harness
1.2.1. No campo Harness name, digite
car_agent. O nome deve começar com uma letra e conter apenas letras, números e underscores (a-z, A-Z, 0-9, _). Máximo de 40 caracteres. Hífens não são permitidos.1.2.2. Na seção Model and system prompt:
- Defina API source como
Bedrock. - Para Model, selecione um modelo entre as opções disponíveis. O Harness usa como padrão o Claude Sonnet 4.6, mas esse modelo pode exigir permissões de assinatura do AWS Marketplace que nem todas as contas possuem. Nesta série, optei por rodar os testes com modelos da família Amazon Nova para explorar o AgentCore usando os modelos próprios da AWS, mas você tem liberdade para escolher qualquer modelo disponível na sua conta. Ao selecionar um modelo, considere os tradeoffs entre latência, custo e precisão. Modelos menores são mais baratos e rápidos, mas podem ter dificuldade com a geração de parâmetros complexos para ferramentas, resultando em mais retentativas. Modelos maiores são mais precisos na primeira tentativa, mas custam mais por token e podem ter latência maior. Escolha o modelo que melhor se adequa ao seu caso de uso e orçamento.
- No campo System prompt, digite:
1
You are a helpful sales assistant for a used car dealership. You help customers find vehicles that match their needs and budget. Be friendly, knowledgeable, and transparent about vehicle conditions. If you don't have specific inventory data, let the customer know you'll check and get back to them.
1.2.3. Deixe todas as configurações restantes com seus valores padrão por enquanto. Exploraremos configurações adicionais (ferramentas, memória, identidade) em artigos futuros.
1.2.4. Na seção Permissions, a opção padrão cria automaticamente uma nova IAM execution role. Também é possível especificar uma role pré-existente ou criar uma customizada. Para este tutorial, mantenha a opção padrão.
1.2.5. Clique em Create Harness e aguarde até que o status alcance Ready.
Step 2: Testar o Harness
Após a criação, o console abre uma página mostrando os detalhes e a configuração do Harness. O status inicialmente será exibido como Creating enquanto a AWS provisiona os recursos.
2.1 Aguardar o Harness Ficar Pronto
2.1.1. Permaneça na página de detalhes do Harness e aguarde o status mudar de Creating para Ready. Isso normalmente leva alguns instantes.
2.2 Abrir a Interface de Teste
2.2.1. Quando o status estiver Ready, clique no botão Test Harness no canto superior direito da página. Isso abre uma interface de chat interativa onde você pode se comunicar com seu agente.
Assim que o status do Harness atinge Ready, o botão Test Harness fica disponível no canto superior direito. Ao clicar nele, uma interface de chat interativa é aberta para comunicação direta com o agente implantado.
2.3 Enviar uma Mensagem de Teste
2.3.1. Na interface de chat, digite uma mensagem simples:
1
Hi, I'm looking for a reliable SUV under $25,000. What do you recommend?
2.3.2. Não espere resultados impressionantes neste momento. O agente não possui ferramentas, banco de dados de estoque, nem fontes de dados externas conectadas. Ele tentará ajudar baseado apenas no seu conhecimento geral e nas instruções do system prompt. Você pode ver o agente reconhecer que não consegue acessar dados de inventário e se oferecer para verificar manualmente. Este é o comportamento esperado para um Harness sem ferramentas conectadas.
O agente Harness responde a uma mensagem de teste usando apenas seu prompt de sistema e conhecimento geral. Sem ferramentas ou dados de inventário conectados, o agente reconhece suas limitações — comportamento esperado nesta etapa do tutorial.
O objetivo aqui é simplesmente confirmar que o agente está respondendo. Em artigos futuros, conectaremos ferramentas via AgentCore Gateway para dar ao agente acesso a dados reais.
2.4 Erro Comum: Acesso ao Modelo Negado
Se você vir um erro como:
1
AccessDeniedException - An error occurred (AccessDeniedException) when calling the ConverseStream operation: Model access is denied due to IAM user or service role is not authorized to perform the required AWS Marketplace actions (aws-marketplace:ViewSubscriptions, aws-marketplace:Subscribe) to enable access to this model.
Isso significa que o modelo selecionado requer uma assinatura do AWS Marketplace que não foi concluída para a sua conta. Você tem duas opções:
- Trocar para um modelo diferente: Edite a configuração do Harness e selecione um modelo que não exija assinatura no Marketplace, como Amazon Nova Lite ou outro modelo nativo da Amazon.
- Assinar o modelo: Vá ao console do Amazon Bedrock, navegue até Model access e solicite acesso ao modelo desejado. Para mais detalhes, consulte Add or remove access to Amazon Bedrock foundation models .
Step 3: Criar um Repositório ECR
Para implantar um agente no AgentCore Runtime, você precisa de uma imagem de container armazenada no Amazon ECR. Nesta etapa, criamos o repositório que armazenará a imagem do nosso agente.
3.1 Abrir o Console do ECR
3.1.1. Navegue até Amazon ECR > Repositories no Console AWS.
3.1.2. Clique em Create repository.
3.2 Configurar o Repositório
3.2.1. Defina Visibility settings como Private.
3.2.2. No campo Repository name, digite
agentcore/car-agent-runtime. O prefixo agentcore/ funciona como um namespace para agrupar todos os repositórios relacionados a agentes.3.2.3. Deixe todas as configurações restantes com seus valores padrão.
3.2.4. Clique em Create repository.
O formulário de criação do repositório ECR configurado com visibilidade privada e o prefixo de namespace agentcore/. Esse namespace agrupa todos os repositórios relacionados a agentes para facilitar o gerenciamento.
3.3 Construir e Enviar a Imagem do Container
O código do agente está disponível no GitHub. Clone o repositório para obter os arquivos fonte:
1
2
git clone https://github.com/biagolini/PythonAwsBedrockAgentCoreRuntime.git
cd PythonAwsBedrockAgentCoreRuntime
O repositório contém três arquivos:
agent.py- Uma aplicação FastAPI que implementa os endpoints/invocations(POST) e/ping(GET) exigidos pelo AgentCore Runtime. Ele usa a API Bedrock Converse com Amazon Nova Lite e o mesmo system prompt que usamos no Harness.requirements.txt- Dependências Python com versões fixas.Dockerfile- Configuração de container ARM64 baseada empython:3.11-slim-bookworm.
3.3.1. Defina suas variáveis de ambiente (atualize uma vez com seus valores):
1
2
3
4
5
6
export AWS_PROFILE=<your-aws-profile> # optional, if you use named profiles
export AWS_REGION=us-east-1
export AWS_ACCOUNT_ID=<your-account-id>
export ECR_REPO=agentcore/car-agent-runtime
export REGISTRY="${AWS_ACCOUNT_ID}.dkr.ecr.${AWS_REGION}.amazonaws.com"
export REPO_URI="${REGISTRY}/${ECR_REPO}"
3.3.2. Construa a imagem ARM64:
1
docker buildx build --platform linux/arm64 -t ${ECR_REPO}:latest --load .
3.3.3. Autentique o Docker com o ECR:
1
aws ecr get-login-password --region $AWS_REGION | docker login --username AWS --password-stdin $REGISTRY
3.3.4. Marque e envie para o ECR:
1
2
docker tag ${ECR_REPO}:latest ${REPO_URI}:latest
docker push ${REPO_URI}:latest
3.3.5. Verifique se a imagem foi enviada conferindo o console do ECR. Você deverá ver a tag
latest no seu repositório.
Após executar o comando docker push, o repositório ECR exibe a tag latest confirmando que a imagem de container ARM64 está disponível. Essa imagem será referenciada na criação do AgentCore Runtime.
Step 4: Criar o Runtime via Console AWS
4.1 Abrir o Console do AgentCore Runtime
4.1.1. Navegue até Amazon Bedrock AgentCore > Runtime no Console AWS.
4.1.2. Clique no botão Create runtime.
O console do AgentCore Runtime antes de qualquer runtime ser criado. O botão Create runtime inicia a implantação de um agente em container a partir de uma imagem ECR.
4.2 Configurar o Runtime
4.2.1. No campo Name, digite
car_agent_runtime.4.2.2. No campo Description, digite
Used car dealership agent - Runtime deployment.4.2.3. Na seção Agent Source:
- Defina Source type como
ECR Container. - No campo Image URI, insira a URI completa da sua imagem:
1
<your-account-id>.dkr.ecr.us-east-1.amazonaws.com/car-agent-runtime:latest
4.2.4. Deixe todas as configurações restantes com seus valores padrão. Similar ao Harness, o console cria automaticamente uma nova IAM execution role com as permissões necessárias (ECR pull, invocação de modelos Bedrock, CloudWatch Logs, X-Ray).
4.2.5. Clique em Create runtime e aguarde até que o status alcance Ready. Isso pode levar alguns minutos enquanto a AWS baixa a imagem do container e provisiona o ambiente.
O formulário de criação do Runtime configurado com o nome do agente, ECR Container como tipo de fonte e o URI completo da imagem apontando para o container enviado anteriormente. O console cria automaticamente a role de execução IAM necessária.
Step 5: Testar o Agente no Runtime
5.1 Aguardar o Runtime Ficar Pronto
5.1.1. Permaneça na página de detalhes do Runtime e aguarde o status mudar de Creating para Ready.
5.2 Abrir a Interface de Teste
5.2.1. Quando o status estiver Ready, clique no botão Test no canto superior direito da página de detalhes do Runtime.
A página de detalhes do Runtime após a conclusão do provisionamento. O status Ready confirma que o container foi baixado e o ambiente está ativo. O botão Test no canto superior direito abre a interface de invocação.
5.3 Enviar uma Mensagem de Teste
5.3.1. Na interface de teste, insira o seguinte payload:
1
{"prompt": "Hi, do you have any SUVs available?"}
5.3.2. Clique em Run para invocar o agente. Assim como no teste do Harness, não espere resultados impressionantes. O agente não possui ferramentas nem dados de inventário. Ele responderá usando seu conhecimento geral e o system prompt. O objetivo é confirmar que o container está rodando corretamente e que o agente responde.
A interface de teste do Runtime aceita um payload JSON bruto compatível com o contrato do endpoint FastAPI. O agente responde usando seu prompt de sistema e conhecimento geral, confirmando que o container está em execução e o endpoint de invocação está acessível.
5.4 Atualizando o Runtime Após Mudanças na Imagem
Se você fizer alterações no código do seu agente e enviar uma nova imagem para o ECR, saiba que isso não atualiza o Runtime automaticamente. Cada versão do Runtime é um snapshot imutável da configuração (imagem de container, protocolo, configurações de rede). Para implantar uma nova imagem, você deve disparar uma atualização explicitamente.
No console, navegue até a página de detalhes do seu Runtime e clique em Update runtime. Via CLI:
1
2
3
4
5
6
7
aws bedrock-agentcore-control update-agent-runtime \
--agent-runtime-id "<your-runtime-id>" \
--agent-runtime-artifact '{"containerConfiguration": {"containerUri": "'${REPO_URI}':latest"}}' \
--network-configuration '{"networkMode": "PUBLIC"}' \
--role-arn "<your-role-arn>" \
--region ${AWS_REGION} \
--profile ${AWS_PROFILE}
Isso cria uma nova versão e o endpoint DEFAULT aponta automaticamente para ela. Versões anteriores permanecem disponíveis para rollback se necessário.
Step 6: Limpeza
Se você não planeja continuar usando os recursos criados neste tutorial, é uma boa prática removê-los da sua conta. Para detalhes de preço, consulte a página de preços do AgentCore .
Para remover os recursos:
- Navegue até Amazon Bedrock AgentCore > Harness, selecione seu Harness e clique em Delete
- Navegue até Amazon Bedrock AgentCore > Runtime, selecione seu Runtime e clique em Delete
- Navegue até Amazon ECR > Repositories, selecione o repositório
agentcore/car-agent-runtimee clique em Delete
Conclusão
O Amazon Bedrock AgentCore substitui o legado Bedrock Agents Classic com uma plataforma modular e flexível. Os dois modelos de implantação cobrem necessidades diferentes:
- Harness oferece velocidade e simplicidade. Declare a configuração do seu agente, implante, invoque. Sem código de orquestração, sem builds de container.
- Runtime oferece controle total. Traga qualquer framework, qualquer modelo, qualquer lógica de orquestração. Empacote em um container e implante em infraestrutura gerenciada.
Ambos compartilham o mesmo modelo de segurança (isolamento por microVM por sessão), modelo de preço (baseado em consumo) e stack de observabilidade (OpenTelemetry). A escolha depende se o seu caso de uso se encaixa em um modelo declarativo ou requer código customizado.
Para detalhes adicionais, consulte:
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! 🚀☁️
Series: Primeiros Passos com o Amazon Bedrock AgentCore Code (7 articles)
- 1Primeiros Passos com Amazon Bedrock AgentCore Harness e Runtime This article
Enjoyed reading this content? Let the author know!
Your likes, comments, shares, and saves help creators reach more builders.
Loading recommendations
Loading article