AWS Bedrock AgentCore Managed Harness (Preview): Um Primeiro Olhar Pratico

Visao Geral

A maioria dos times de software esta construindo agentes agora. A parte dificil raramente e decidir o que o agente deve fazer; e tudo em volta do loop: quem hospeda, quem observa, quem e acionado quando uma ferramenta da timeout as 3 da manha. O agente em si, a parte interessante, costuma ser a menor parte do projeto.

Um agente de IA e uma lista curta de pecas:

• um modelo fazendo o raciocinio,
• um system prompt dizendo quem ele e e com o que deve se importar,
• um conjunto de ferramentas que ele pode chamar:
  • arquivo, HTTP, shell, busca,
  • servidores MCP que expoem mais ferramentas e dados externos,
  • skills descrevendo como lidar com workflows especificos,
• um loop que alimenta a saida das ferramentas de volta no modelo ate a tarefa ser concluida,
• e, opcionalmente, memoria para que o agente lembre de algo entre turnos e entre sessoes.

Na pratica, a maioria dos agentes e um harness fino em volta dessa lista. Alguem escreve um system prompt, conecta dois ou tres servidores MCP, joga algumas skills dentro, e roda tudo como boilerplate dentro de uma aplicacao, ou deixa um coding agent como Claude Code ou Cursor hospedar. Funciona. Tambem significa que todo mundo esta reconstruindo alguma versao do mesmo runtime.

A proposta da AWS com o Bedrock AgentCore Managed Harness, anunciado em preview em 22 de abril de 2026, e que voce entrega os ingredientes e eles rodam o loop. Voce descreve o modelo, o prompt, os servidores MCP, e quais primitivas do AgentCore quer plugadas, e a AWS hospeda tudo. Cada sessao fica isolada em sua propria microVM. O uso de ferramentas chega em stream conforme acontece. As primitivas embutidas fazem os trabalhos que a maioria dos times teria que improvisar do zero: o Gateway intermedia conexoes MCP, o Browser da ao agente um navegador headless, o Code Interpreter da um ambiente de execucao de codigo em sandbox, e o Memory persiste contexto entre sessoes. A observabilidade ja vem conectada por padrao ao CloudWatch e ao X-Ray.

O valor e velocidade de composicao. Voce para de escrever codigo de runtime e comeca a descrever o agente. Era isso que eu queria testar.

Neste post eu uso a AgentCore CLI para compor um managed harness conectado ao Knowledge MCP server da AWS, ao AgentCore Browser, e ao Code Interpreter. Rodo tudo via agentcore dev, que sobe um chatbot web local apontado para o harness real e faz stream dos traces conforme o agente trabalha.

Setup

Pre-requisitos

• Uma conta AWS com acesso a modelos Bedrock em uma das regioes de preview do AgentCore Harness (us-west-2, us-east-1, eu-central-1, ap-southeast-2). Eu usei us-east-1.
• Claude Sonnet 4.6 habilitado no Bedrock. Qualquer modelo de fronteira disponivel no Bedrock funciona; o Sonnet foi o que escolhi para essas demos.
• Node 20 ou mais novo.
• Credenciais AWS no shell com permissoes para criar IAM roles e chamar o control plane do AgentCore. A CLI le do seu profile AWS padrao.

Duas formas de configurar o AgentCore Harness, e por que eu escolhi a CLI

Existem duas superficies de controle. A API boto3 e a escolha certa se voce quer scriptar tudo a partir de Python. Ela expoe dois clients: bedrock-agentcore-control para ciclo de vida (criar, atualizar, deletar), e bedrock-agentcore para invocacao. A AgentCore CLI e o workflow de projeto: ela te guia por um wizard interativo, faz o scaffold de uma arvore de projeto em disco, conecta as primitivas do AgentCore, e te entrega um chatbot web local em modo dev. Eu escolhi a CLI porque o ponto principal do managed harness e velocidade de composicao, e e ai que a CLI brilha. Responda alguns prompts, confirme, ganhe um agente funcionando.

Passo 1: Instalar a CLI

npm install -g @aws/agentcore@preview
agentcore --version

Eu rodei contra a v1.0.0-preview.2.

Passo 2: Compor o harness

Rode agentcore em um diretorio vazio. A CLI detecta que nao ha projeto ali e oferece criar um.

Pressione Enter e o wizard comeca pelo nome do projeto. Eu chamei o meu de my2cents.

Em seguida ele pergunta o que construir. As opcoes sao Harness (o loop de agente gerenciado, baseado em config) ou Agent (um projeto de codigo rodando no AgentCore Runtime). O caminho recomendado para o nosso caso e Harness.

Escolher Harness te leva para o wizard do harness. Nome primeiro.

A etapa de provedor de modelo e mais interessante do que parece. Bedrock, OpenAI e Google Gemini sao todos opcoes de primeira classe, entao o harness e genuinamente cross-provider, nao so Bedrock. OpenAI e Gemini pedem um ARN de chave de API. Eu escolhi Bedrock para essas demos.

Custom environment permite trocar o container de runtime do harness. Default Environment ja vem com ferramentas Python, Bash, e File e e o que voce quer para prototipagem. Container URI aponta para uma imagem ECR pre-construida, e Dockerfile te deixa trazer o seu. O environment e a caixa em que o agente roda para trabalho estilo shell; nao e o mesmo sandbox do Code Interpreter ou do Browser. Eu mantive o padrao.

Habilitar memoria cria um store persistente conectado a este harness.

Advanced settings e a tela mais opinativa. E um multi-select para as coisas que voce pode querer configurar agora ou depois: Tools (browser, code interpreter, servidores MCP), Authentication (AWS_IAM ou Custom JWT inbound), Network (deploy dentro de uma VPC), Lifecycle (idle timeout, max session lifetime), Execution limits (iteracoes, tokens, timeout por turno), Truncation (estrategia de overflow de contexto), e Session Storage (um volume persistente montado dentro da sessao). Para este post marquei Tools e Session Storage e deixei o resto nos padroes.

Uma coisa que eu esperava encontrar aqui e nao encontrei: uma forma de configurar skills. Skills sao uma das principais razoes pelas quais a maioria dos times compoe um agente, mas elas nao aparecem como opcao no wizard hoje, e tambem nao consegui encontrar uma flag pra isso em outro lugar da CLI. Elas podem ser anexadas via console web da AWS e SDKs. Tambem abri uma issue no projeto para acompanhar o suporte na CLI: aws/agentcore-cli#968.

Marcar Tools abre o sub-fluxo de ferramentas. Quatro opcoes: AgentCore Browser, AgentCore Code Interpreter, AgentCore Gateway (um broker MCP-as-a-service operado pela AWS), e Remote MCP Server (conecta direto numa URL de servidor MCP). Selecionei Browser, Code Interpreter, e Remote MCP Server.

Para esta demo, conectei o AWS Knowledge MCP Server, para que o agente consiga puxar a documentacao da AWS, anuncios, e entradas de What’s New mais atuais sob demanda, em vez de depender do cutoff de treino do modelo.

Em seguida, o caminho de session storage. Esse e o caminho absoluto dentro de cada microVM de sessao onde o volume persistente fica montado. Session storage tambem e pre-requisito se voce planeja usar skills, ja que as skills sao carregadas a partir do disco dentro da sessao e precisam de um lugar persistente para morar. Mantive o padrao /mnt/data/.

Tela final de revisao. Nome, provedor de modelo, ID do modelo, memoria, ferramentas, servidor MCP, caminho de session storage, tudo num so lugar.

Aperte Enter e a CLI faz o scaffold do projeto em disco.

Voce termina com um projeto my2cents/ contendo dois diretorios:

• harness/MyHarness/: o harness em si, incluindo o config que o wizard produziu.
• agentcore/: o config do AgentCore e um projeto CDK subjacente para deploy.

Nenhum codigo Python que eu escrevi, nenhum Dockerfile, nenhum JSON de IAM. O wizard produziu tudo.

Passo 3: agentcore dev

cd my2cents
agentcore dev

agentcore dev faz duas coisas em sequencia. Primeiro ele sintetiza o stack CDK do projeto e faz deploy na sua conta AWS, entao o harness, o memory store, a fiacao do MCP, e as primitivas browser/code-interpreter passam a existir como recursos reais. Em seguida ele inicia uma UI de chat web local apontada para esse harness deployado. IAM roles sao criadas ou reutilizadas automaticamente contra o profile no seu shell.

Tudo abaixo acontece nesse chatbot.

Testes

Rodei tres cenarios pelo chatbot do agentcore dev, cada um exercitando uma primitiva diferente: a conexao MCP, o Code Interpreter, e o Browser. Tracing ficou ligado em cada turno.

Cenario 1: perguntar ao servidor MCP quando o AgentCore harness foi lancado

A primeira coisa que eu queria ver era se a conexao com o AWS Knowledge MCP funcionava de fato de ponta a ponta. Na chat UI digitei:

When was the Bedrock AgentCore managed harness launched? Cite the source.

O agente narrou o proprio plano (“Let me get the full details from the announcement page to confirm the exact launch date”), chamou o AWS Knowledge MCP duas vezes, e respondeu:

Duas coisas interessantes aparecem nessa screenshot. O agente usou duas ferramentas MCP, nao uma: aws-knowledge-mcp-server___search_documentation para achar a pagina de anuncio, e depois aws-knowledge-mcp-server___read_documentation para buscar o conteudo. Isso nao foi algo que eu pedi; o harness descobriu os schemas das ferramentas MCP no startup, expos elas para o modelo, e o modelo escolheu o par certo sozinho.

A barra lateral direita e o agent inspector embutido: abas de Resources, Traces, e Memories, todas conectadas pelo agentcore dev.

Follow-up, mesma sessao:

Vale notar: o agente nao chamou o MCP uma terceira vez. Ele reutilizou a pagina ja buscada no turno anterior (“Based on the information already retrieved in the previous search…”), o que e o contexto de sessao do harness funcionando corretamente sem que eu tivesse conectado nada.

Cenario 2: Code Interpreter num CSV do Our World in Data

Para o Code Interpreter, queria uma tarefa que o modelo nao conseguisse fingir: buscar um CSV real de uma fonte confiavel, fazer o parse, calcular alguma coisa, e produzir um grafico. Digitei:

Download the annual CO₂ emissions per country CSV from Our World in Data (https://ourworldindata.org/grapher/annual-co-emissions-per-country.csv). Plot the top 5 emitters since 2000 as a single chart. Tell me which of those five countries has grown fastest in percentage terms over that period.

A revelacao interessante esta na narracao do agente: “The sandbox can’t reach external URLs directly. Let me download it from the host machine and then pass the data into the sandbox.” Isso e consequencia de rodar o Code Interpreter em sandbox mode, o modo de rede padrao sem acesso de saida. Os outros modos, Public (internet aberta) e VPC (escopado a uma das suas VPCs), permitem ao interpreter buscar o CSV diretamente sem o harness ter que atuar como intermediario. O agente lidou com a alternativa de forma limpa aqui, baixando na sessao do harness e injetando os bytes do CSV no interpreter, mas vale saber disso na hora de decidir qual modo de rede usar.

A saida e uma tabela top-5 (China, Estados Unidos, India, Russia, Japao) com valores de 2000 e 2024 em gigatoneladas, e um grafico salvo como top_co2.png dentro do sandbox.

Sete tool calls para um unico prompt. Cada uma e uma invocacao separada de code_interpreter: carregar, inspecionar o schema, filtrar, ranquear, recortar a janela de tempo, plotar, salvar. O harness faz stream de cada uma conforme acontece, entao o chat parece o agente pensando alto, e voce pode parar ele no meio do voo se ele estiver indo pelo caminho errado.

Cenario 3: Browser para a previsao do tempo de Dublin

A primitiva Browser e mais dificil de demonstrar bem, porque o valor dela esta em navegar sites ao vivo que nao estao nos dados de treino do modelo. Escolhi o servico nacional de meteorologia da Irlanda para uma consulta limpa, baseada em localizacao:

Go to https://www.met.ie/ and tell me the weather forecast for tomorrow in Dublin.

O agente lancou Chromium headless, abriu met.ie, navegou ate a pagina de previsao de Dublin, e leu a previsao do dia seguinte.

Duas coisas se destacam. Primeiro, o numero de chamadas: 28 tool calls para uma unica consulta de tempo. Trabalho de browser e tagarela: cada navegacao, clique, scroll, e leitura e uma invocacao separada de ferramenta, e elas se acumulam rapido mesmo numa pagina simples. Segundo, o agente nao desistiu no primeiro 404. Ele bateu numa URL ruim, tentou o endpoint de API, bateu em outro 404, e depois voltou e achou o slug certo da pagina de previsao antes de extrair os dados. Esse loop de recuperacao aconteceu automaticamente e apareceu no chat como narracao plana, nao como um retry escondido enterrado num trace.

Enquanto o agente esta dirigindo o browser voce pode abrir o console do AgentCore e assistir a sessao ao vivo. Existe uma view de “Live browser session” com uma URL de sessao, mais um botao “Take control of session” se voce precisar entrar manualmente para debugar ou limpar algo que o agente nao consiga. Esse e o tipo de gancho operacional que voce teria que construir do zero se rodasse Chromium headless na sua propria infraestrutura.

O que esse cenario testa e se o agente consegue navegar num site real e puxar os dados sem nenhum scraper pre-cozido. A primitiva Browser roda como seu proprio sandbox, separado do microVM da sessao e do Code Interpreter. O agente emite acoes de alto nivel (navegar, buscar, extrair) e recebe de volta o conteudo da pagina. Se o site mudar o layout no mes que vem e a consulta falhar, a falha aparece no trace como erro de acao do browser, nao como uma resposta silenciosamente errada.

Cleanup

agentcore dev faz deploy de recursos AWS reais, entao quando terminei eu derrubei tudo. Dois passos.

agentcore remove all

Isso retira todo recurso do arquivo de config local.

agentcore deploy

Isso sincroniza o config (agora vazio) com a AWS, deletando os recursos deployados da conta.

Veredito

O managed harness entrega o que promete, dentro do escopo estreito dele. Use a AgentCore CLI para compor, rode agentcore dev, e voce tem um agente funcional conectado a um servidor MCP, um browser, um code interpreter, e um memory store, com traces ligados desde o primeiro turno. A composicao em si demorou mais para eu descrever neste post do que para fazer na CLI. E essa e a historia.

Quando usar o managed harness

Use quando o formato do seu agente e o tipico: um modelo, um prompt, dois ou tres servidores MCP, um punhado de ferramentas embutidas, e memoria. As primitivas do AgentCore cobrem esse formato quase exatamente. Voce para de escrever codigo de runtime e comeca a iterar no prompt, na lista de ferramentas, e nas conexoes MCP. Traces e logs vem prontos.

E uma boa escolha se:

• Voce quer iterar numa ideia de agente em uma tarde sem escrever o boilerplate de runtime de sempre.
• Voce ja vive na AWS e quer que a observabilidade caia no mesmo CloudWatch e X-Ray que voce ja roda.
• Sua superficie de ferramentas e principalmente servidores MCP mais as primitivas do AgentCore (Browser, Code Interpreter, Memory). A fiacao e declarativa; voce escreve zero cola.
• Voce quer um lugar central para gerenciar IAM, rate limits, e network egress do agente, em vez de boilerplate por aplicacao.

Pule, ou mantenha seu framework existente, se:

• Seu agente precisa de logica de orquestracao customizada que nao encaixa num loop de “modelo + ferramentas + memoria”. Maquinas de estado com ramificacoes, fluxos de aprovacao, e handoffs multi-agente com roteamento sob medida ainda sao melhor servidos por LangGraph, CrewAI, ou Strands.

O que eu quero ver no GA

Uma lista curta de gaps que encontrei nesta avaliacao e que gostaria que a AWS fechasse antes de declarar o harness pronto para producao:

• Skills no wizard da CLI. O wizard configura todas as outras primitivas (memoria, browser, code interpreter, MCP) menos skills. Hoje elas precisam ser anexadas por fora via console AWS ou pelos SDKs. Acompanhada em aws/agentcore-cli#968.
• Instalar skills a partir de um registry ou de uma URL de discovery. Aponte o harness para uma entrada no AgentCore Registry ou para uma URL .well-known/agent-skills e faca ele puxar a skill, em vez de empacotar elas na arvore do projeto na mao. Veja meu post sobre registries de agentes e skill discovery para contexto.
• Cobertura de regiao mais ampla. Quatro regioes ja e bastante para um preview, mas seria bom ver o harness disponivel mais perto de onde os times ja mantem seus dados.
• Suporte a Terraform e independencia do CDK. A CLI hoje se apoia num projeto CDK gerado por baixo dos panos. Seria legal ter um caminho Terraform e a opcao de gerenciar harnesses sem CDK no meio do caminho.
• Um botao de stop no chatbot do dev. De vez em quando, depois que eu submetia um prompt, a UI ficava la girando sem forma obvia de cancelar o turno em andamento. Um controle simples de stop tornaria iterar no agentcore dev bem menos frustrante.
• Visibilidade de custo por harness. Uma view unica de custo escopada a um ARN de harness, segmentada por primitiva, seria melhor do que juntar as pecas a partir de CloudWatch e Cost Explorer.

Para prototipos, ferramentas internas, e o formato de agente “modelo + alguns MCPs + memoria” muito comum que a maioria dos times esta entregando em 2026, o managed harness e o caminho mais curto que eu ja usei. Para qualquer coisa de stakes mais altos, espere o GA.