AgentCore CLI 1.0 leva agente TypeScript do laptop à produção na AWS

A AgentCore CLI 1.0 está disponível desde 28 de outubro de 2026. É a ferramenta de linha de comando para criar, testar localmente e implantar agentes de IA no Amazon Bedrock AgentCore. O desenvolvedor Sascha M. S. publicou no DEV Community um tutorial em TypeScript que vai do zero até uma chamada em produção, construindo o consultor de livros de uma livraria fictícia chamada Bücherfuchs, e é esse percurso que vale destrinchar para quem decide deploy de agentes de IA no trabalho.

O problema que a CLI ataca não é o modelo, é a parte chata do meio: como o código vira um ambiente de execução gerenciado, quem pode chamar o agente e onde os logs terminam. É justamente aí que boa parte dos protótipos de IA generativa trava antes de sair do laptop.

O que você vai construir

O tutorial parte de uma pasta vazia e chega a um agente rodando no AgentCore Runtime, com dois tools próprios e sessão isolada por usuário. O pacote @aws/agentcore existe desde fevereiro de 2026 em preview e versões 0.x; a versão 1.0 reorganiza os comandos em três grupos (Project, Resources e Settings), padroniza opções globais como --region, --json e --debug em todo comando, e permite endereçar um recurso existente direto pelo ID ou ARN sem adicioná-lo antes a um projeto.

Para entender o que está sendo criado, quatro conceitos bastam:

• Runtime: o ambiente gerenciado que roda o código do agente; cada sessão ganha sua própria microVM isolada.
• Harness: um agente descrito só por configuração (modelo, prompt, tools), sem código próprio; a CLI roda o loop do agente por você.
• Memory: armazenamento de históricos de conversa e fatos derivados deles, para o agente lembrar entre sessões.
• Gateway: expõe APIs e funções Lambda como tools no padrão MCP (Model Context Protocol) para os agentes consumirem.

O tutorial segue o caminho com código próprio, que exige um runtime. Um harness sai mais rápido, mas esconde o que o agente realmente faz. Dá para converter um harness em código depois com agentcore export harness, caso ele fique curto demais.

O agente final usa o framework open-source Strands Agents, responde em inglês sobre o catálogo da livraria e decide sozinho quando chamar search_books ou check_stock antes de falar sobre preço ou estoque.

Pré-requisitos

• Node.js 20.12 ou mais recente (o autor usou o 22) e npm.
• Conta AWS com credenciais válidas, verificáveis com aws sts get-caller-identity.
• Permissões IAM para o AgentCore e para os papéis de bootstrap do CDK; em conta de sandbox, um papel de admin resolve, em conta corporativa isso precisa de alinhamento prévio.
• Acesso a um modelo Claude no Amazon Bedrock: o template usa um Claude Sonnet via perfil de inferência global.
• Nenhum Docker é necessário: o template TypeScript empacota como ZIP (CodeZip), não como imagem de container.

Passo a passo

1. Instalar a CLI

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

O esperado é 1.0.1 ou mais recente. Se aparecer outra coisa, a ferramenta Python antiga bedrock-agentcore-starter-toolkit ainda está no PATH com o mesmo nome agentcore; desinstale com pip, pipx ou uv e abra um terminal novo. A CLI coleta telemetria anônima por padrão; para desativar: agentcore config telemetry.enabled false.

2. Gerar o projeto a partir do template

Sem opções, agentcore create abre um assistente que cria um harness por padrão. Para um agente com código próprio em TypeScript, o template precisa ser explícito:

agentcore create --name buecherfuchs --template agent-typescript-strands
cd buecherfuchs

O arquivo central é agentcore/agentcore.json: ele lista os recursos do projeto e a CLI o traduz numa stack CDK na hora do deploy. Recursos AWS extras, como uma tabela DynamoDB, entram em agentcore/cdk/lib/cdk-stack.ts, que já vem com um exemplo comentado.

3. Tirar a memória do caminho por enquanto

O template Strands adiciona por padrão uma AgentCore Memory com quatro estratégias (fatos, preferências, resumos, episódios). Para um primeiro agente isso custa extra, deixa o deploy mais lento e esconde o que o próprio agente faz:

agentcore remove memory --name agentMemory
rm -r app/agent/memory

Dá para trazer de volta depois com agentcore add memory, quando o agente realmente precisar lembrar de algo entre sessões.

4. Escrever os tools do catálogo

Cada tool é uma função que o modelo pode chamar; o Strands valida os argumentos com um schema Zod. O exemplo cria uma busca no catálogo e uma checagem de estoque, com os livros guardados em memória para o exemplo rodar sem depender de outro serviço AWS:

// app/agent/tools/catalog.ts
import { tool } from '@strands-agents/sdk';
import { z } from 'zod';

type Book = {
 isbn: string;
 title: string;
 author: string;
 genre: string;
 priceEur: number;
 inStock: number;
};

const BOOKS: Book[] = [
 { isbn: '978-3-0000-0001-1', title: 'Fog over Hamburg', author: 'Lena Brandt', genre: 'Crime', priceEur: 14.0, inStock: 3 },
 { isbn: '978-3-0000-0003-5', title: 'Stars over Lapland', author: 'Mira Holm', genre: 'Novel', priceEur: 18.9, inStock: 7 },
];

function searchBooks(query: string, genre?: string): Book[] {
 const q = query.trim().toLowerCase();
 return BOOKS.filter(
 (b) =>
 (q === '' || b.title.toLowerCase().includes(q) || b.author.toLowerCase().includes(q)) &&
 (!genre || b.genre.toLowerCase() === genre.toLowerCase()),
 );
}

export const searchBooksTool = tool({
 name: 'search_books',
 description: 'Busca no catálogo da livraria Bücherfuchs por título ou autor, com filtro opcional de gênero.',
 inputSchema: z.object({
 query: z.string().describe('Termo de busca para título ou autor, vazio retorna todos'),
 genre: z.string().optional(),
 }),
 callback: async ({ query, genre }) => searchBooks(query, genre),
});

export const checkStockTool = tool({
 name: 'check_stock',
 description: 'Verifica por ISBN quantas cópias de um livro há em estoque.',
 inputSchema: z.object({ isbn: z.string() }),
 callback: async ({ isbn }) => {
 const book = BOOKS.find((b) => b.isbn === isbn);
 return { found: !!book, isbn, title: book?.title ?? null, inStock: book?.inStock ?? 0 };
 },
});

Dois detalhes importam aqui. O retorno do tool precisa ser compatível com JSON: usar interface em vez de type para Book quebra a checagem do compilador. E a description de cada tool é, na prática, o prompt que decide se o modelo vai chamá-la ou não, então vale escrever com cuidado.

5. O ponto de entrada main.ts

// app/agent/main.ts
import { BedrockAgentCoreApp } from 'bedrock-agentcore/runtime';
import { Agent } from '@strands-agents/sdk';
import { z } from 'zod';
import { loadModel } from './model/load.js';
import { searchBooksTool, checkStockTool } from './tools/catalog.js';

const SYSTEM_PROMPT = `Você é o consultor de livros da livraria "Bücherfuchs". Use search_books e check_stock antes de falar sobre livros, preços ou estoque. Nunca invente livros.`;

const requestSchema = z.object({ prompt: z.string().min(1) });
const agents = new Map<string, Agent>();

async function agentFor(sessionId: string): Promise<Agent> {
 let agent = agents.get(sessionId);
 if (!agent) {
 agent = new Agent({ model: await loadModel(), systemPrompt: SYSTEM_PROMPT, tools: [searchBooksTool, checkStockTool] });
 agents.set(sessionId, agent);
 }
 return agent;
}

const app = new BedrockAgentCoreApp({
 invocationHandler: {
 requestSchema,
 async *process(payload, context) {
 const agent = await agentFor(context?.sessionId ?? 'local');
 for await (const event of agent.stream(payload.prompt)) {
 if (event.type === 'modelStreamUpdateEvent' && event.event?.type === 'modelContentBlockDeltaEvent' && event.event.delta?.type === 'textDelta') {
 yield { data: event.event.delta.text };
 }
 }
 },
 },
});

app.run({ port: parseInt(process.env.PORT ?? '8080', 10) });

O agente é criado uma vez por sessão e guardado num Map. Como cada sessão no AgentCore ganha sua própria microVM, o histórico de conversa dura o tempo da sessão; para memória de longo prazo entre sessões, entra a AgentCore Memory.

6. Build e deploy

agentcore build
agentcore deploy
agentcore status

No projeto do tutorial, a stack gerada (AgentCore-buecherfuchs) continha três recursos: um papel IAM, a policy correspondente e o runtime. No primeiro deploy, a CLI cria sozinha o alvo padrão em aws-targets.json a partir da conta e região atuais, e faz o bootstrap do CDK se precisar. A primeira execução leva alguns minutos.

Testando

A lógica dos tools é TypeScript puro, então é testada como TypeScript puro, sem gastar nenhum token:

cd app/agent
node --import tsx --test tools/catalog.test.ts
npx tsc --noEmit
cd ../..

Com os testes passando, o próximo passo é subir o servidor local com hot reload e tracing via OpenTelemetry:

agentcore dev
curl -s localhost:8080/ping
# {"status":"Healthy","time_of_last_update":...}

Rodando agentcore dev --mode browser, abre também o Agent Inspector, uma interface web para conversar com o agente e navegar pelos traces. Para chamar o agente local a partir de outro terminal, a opção --runtime é obrigatória, senão a CLI recusa por não saber qual recurso endereçar:

agentcore invoke --runtime agent --local \
 --payload '{"prompt":"Tem algum livro de crime em estoque?"}'

Sem credenciais AWS válidas ou com a região fora de alcance, a resposta vem como event: error no stream, mas servidor, roteamento e tools continuam funcionando normalmente, só a chamada ao modelo falha. Depois do deploy, o mesmo comando sem --local chama o agente em produção:

agentcore invoke --runtime agent \
 --payload '{"prompt":"Quanto custa Stars over Lapland e tem em estoque?"}' \
 --session-id "cliente-4711-$(date +%Y%m%d)-consulta-livro"

Usar o mesmo --session-id em perguntas seguintes mantém a conversa no mesmo objeto Agent; sem a opção, cada chamada cria uma sessão nova. Numa aplicação real, quem chama o runtime é o backend via SDK, não a CLI direto, por exemplo uma função Lambda atrás de uma API.

Para depurar, os logs saem do CloudWatch e os traces mostram cada chamada ao modelo e a cada tool, com duração:

agentcore logs runtime --name agent --since 30m --level error
agentcore traces runtime list --name agent --since 1h

Com agente, trace não é luxo: sem ele não dá para saber se uma resposta errada veio do prompt, do tool ou do modelo.

Limpando os recursos

Apagar a pasta do projeto não apaga nada na AWS. O padrão que o próprio material do tutorial demonstra para memory (agentcore remove memory --name agentMemory seguido de um novo deploy para sincronizar a stack) vale como referência para os outros tipos de recurso, como agentcore remove runtime --name agent, antes de rodar agentcore deploy de novo e deixar a CLI eliminar da CloudFormation o que saiu do agentcore.json.

Como alternativa mais direta, a stack gerada tem nome previsível (AgentCore-buecherfuchs no exemplo), então apagá-la via CloudFormation remove runtime, papel IAM e policy de uma vez:

aws cloudformation delete-stack --stack-name AgentCore-buecherfuchs

Vale ficar de olho na fatura mesmo depois de limpar. Segundo a página de preços citada no tutorial, o runtime é cobrado por segundo de CPU e memória consumidos, e nenhum tempo de CPU é cobrado enquanto o agente só espera o modelo ou um tool responder, o que ajuda bastante em agentes que passam a maior parte do tempo esperando. Por cima disso entram os tokens do Bedrock, normalmente o maior item da conta, os logs do CloudWatch e, se usada, a AgentCore Memory. Um alarme de orçamento na conta não custa nada e evita surpresa.

Próximos passos

Quem já tinha um projeto na versão 0.x precisa convertê-lo, porque o formato do agentcore.json pula da versão 1 para a 2. O comando agentcore migrate sem --yes só escreve um plano em agentcore/.cli/migrate/ e não muda nada; o projeto precisa estar num repositório Git com working tree limpo, e recursos já implantados mantêm o nome original, marcados com "migratedFrom": "v1" no agentcore.json.

Minha recomendação é migrar primeiro numa branch e implantar numa conta de teste antes de tocar em produção.

My advice: migrate in a branch first and deploy to a test account before you touch production.Sascha M. S., autor no DEV Community

Daqui para frente, os caminhos naturais são: trazer a AgentCore Memory de volta com agentcore add memory quando o agente precisar lembrar entre sessões; usar o Gateway para expor APIs e funções Lambda existentes como tools no padrão MCP, em vez de reescrever integrações; e mover segredos e chaves de API para fora do .env.local, indo para a AgentCore Identity (agentcore add credentials) ou o Secrets Manager. Permissões extras para o agente devem entrar via métodos grant… específicos na stack CDK, não ampliando o papel IAM padrão de forma genérica.

Um cuidado prático vale registrar: o mesmo nome agentcore é usado tanto pela CLI nova quanto pelo toolkit Python antigo (bedrock-agentcore-starter-toolkit), e partes da documentação online ainda descrevem comandos da versão anterior, como agentcore import em vez de migrate. Até a documentação se atualizar, agentcore <comando> --help é mais confiável que a referência online.

Fonte: DEV Community — #aws