Comece a usar o Amazon Bedrock AgentCore

Esse guia de início rápido leva você do zero a um agente em execução em alguns minutos usando a AgentCore CLI. Você instalará a CLI, estruturará um projeto, testará localmente, implantará e invocará seu AWS agente.

Duas maneiras de criar um agente na AgentCore mesma CLI:

• Arnês gerenciado. Você declara o agente em um arquivo de configuração (modelo, prompt, ferramentas, memória) e AgentCore executa o loop para você. Sem estrutura, sem código de orquestração. Bom caminho quando você quer o caminho mais rápido da ideia para um agente em execução. Saiba mais.

• Code-based agente. Você escreve o loop do agente em Python usando uma estrutura que você já conhece (Strands LangGraph, Google ADK ou OpenAI Agents) e o implanta no Runtime. AgentCore Controle total sobre a lógica de orquestração.

Esta página mostra o fluxo baseado em código. Para arnês, consulte O que é o AgentCore arnês.

Inscreva-se em um AWS account

Inscreva-se em um AWS account

Para começar AWS, você precisa de uma AWS conta. Para obter informações sobre como criar uma AWS conta, consulte Introdução a uma AWS AWS conta no Guia de referência de gerenciamento de contas.

Pré-requisitos

• Node.js 20 ou mais tarde. A AgentCore CLI é distribuída como um pacote npm. Verifique comnode --version. Instale a partir do https://nodejs.org nodejs.org, se necessário.

• npm. Incluído com Node.js.

• Uma AWS conta com credenciais configuradas. Configure via AWS CLI, variáveis de ambiente ou um AWS perfil. Consulte Configurando a AWS CLI.

• Python 3.10 ou posterior (para código de agente). Verifique compython3 --version.

• Permissões do IAM. Sua identidade precisa de permissões para fazer chamadas de AgentCore API e assumir as funções de bootstrap do CDK usadas durante a implantação. Consulte Usar a AgentCore CLI.

• Acesso ao modelo. O Amazon Bedrock permite o acesso aos modelos de fundação por padrão. Os modelos disponíveis incluem os modelos Amazon Nova, Anthropic Claude, Meta Llama e Mistral AI. Para usar modelos sem fundamento, siga as etapas de acesso ao modelo.

• Docker. Obrigatório somente se você escolher o tipo de Container compilação. O tipo de CodeZip compilação padrão não requer Docker.

Etapa 1: instalar a AgentCore CLI

npm install -g @aws/agentcore

Verificar:

agentcore --version

nota

Se isso relatar um erro em vez de um número de versão, um comando antigo do Python está ocultando o agentcore comando npm em seu. PATH Isso acontece se você instalou anteriormente o pacote bedrock-agentcore-starter-toolkit pip e é mais comum no Windows. Executepip uninstall bedrock-agentcore-starter-toolkit, abra um novo terminal e tente novamente.

Para atualizar mais tarde, execute novamente o comando de instalação ouagentcore update. Fonte e problemas: agentcore-cli on. GitHub

Etapa 2: Crie seu projeto

agentcore create

O assistente interativo pergunta primeiro o que você quer criar:

• Harness - Um loop de agente gerenciado baseado em configuração. Não é necessário código de estrutura ou orquestração. Veja o que é o AgentCore arnês.

• Agente - Um agente baseado em código que usa uma estrutura de sua escolha, implantada no Runtime. AgentCore

• Ignorar - Crie a estrutura do projeto sem um agente. Adicione um mais tarde comagentcore add.

Se você escolher Agente, o assistente continuará com:

• Estrutura - Strands Agents (recomendado) LangChain/LangGraph, Kit de desenvolvimento de agentes do Google ou SDK de agentes OpenAI

• Fornecedor de modelos - Amazon Bedrock, Anthropic, OpenAI ou Gemini

• Memória - Nenhuma, somente de curto prazo ou de longo e curto prazo

• Tipo de compilação - CodeZip (padrão) ou contêiner

Você também pode passar sinalizadores diretamente para criar um agente baseado em código:

agentcore create \
  --project-name MyProject \
  --name MyAgent \
  --language Python \
  --framework Strands \
  --model-provider Bedrock \
  --memory none \
  --build CodeZip

Para ver todos os comandos e opções disponíveis, consulte a referência da AgentCore CLI.

Tipos de construção

• CodeZip(padrão) empacota seu código em um arquivo zip e o carrega no Amazon S3. Esse tipo de compilação não requer Docker.

• Containercria e implanta uma imagem de contêiner. Esse tipo de compilação requer um daemon Docker em execução.

Estrutura do projeto

agentcore creategera uma configuração de projeto compartilhada e uma estrutura de aplicativo diferente para agentes e equipamentos baseados em código:

exemplo

Code-based agent

MyProject/
├── AGENTS.md
├── README.md
├── agentcore/
│   ├── agentcore.json
│   ├── aws-targets.json
│   └── cdk/
└── app/
    └── MyAgent/
        ├── main.py
        ├── pyproject.toml
        ├── README.md
        ├── model/
        ├── mcp_client/
        └── skills/

Harness

MyHarnessProject/
├── AGENTS.md
├── README.md
├── agentcore/
│   ├── agentcore.json
│   ├── aws-targets.json
│   └── cdk/
└── app/
    └── MyHarness/
        ├── harness.json
        └── system-prompt.md

Arquivos principais:

• agentcore/agentcore.json- O arquivo de configuração principal. Ele define seus agentes, equipamentos, armazenamentos de memória, gateways, credenciais e outros recursos. Os agentcore remove comandos agentcore add e gerenciam esse arquivo.

• agentcore/aws-targets.json- As AWS contas e regiões para implantação.

• agentcore/.env.local- Segredos locais, como chaves de API para fornecedores de modelos.

• app/- O diretório do aplicativo. Um agente baseado em código contém um ponto de entrada e dependências. Um arnês contém harness.json e. system-prompt.md

Etapa 3: teste localmente

cd MyProject
agentcore dev

agentcore devcria um ambiente virtual Python, instala dependências, inicia um servidor local com hot reload e abre o inspetor de agentes em seu navegador para que você possa conversar com o agente, inspecionar rastreamentos e navegar pelos recursos do projeto. As alterações de código são coletadas automaticamente.

Etapa 4: implantar seu agente

agentcore deploy

Implantar:

1. Empacota seu código em um artefato zip (ou cria um contêiner se) --build Container

2. Usa o AWS CDK nos bastidores para sintetizar e provisionar recursos

3. Cria um endpoint de tempo de AgentCore execução para seu agente

4. Configura o CloudWatch registro e a observabilidade

A primeira implantação leva alguns minutos, enquanto o CDK inicializa sua conta. As implantações subsequentes são mais rápidas.

Visualize o que mudará sem implantar:

agentcore deploy --dry-run

Verifique o status:

agentcore status

Etapa 5: invocar seu agente implantado

agentcore invoke --prompt "Hello, what can you do?"

Se seu agente tiver pagamentos configurados, forneça o contexto de pagamento no momento da chamada:

agentcore invoke \
  --prompt "Access https://example-x402-merchant.com/paid-api" \
  --payment-instrument-id <INSTRUMENT_ID> \
  --auto-session \
  --payment-user-id [e-mail]

Esse é o loop. Repitaapp/MyAgent/main.py, teste comagentcore dev, implante comagentcore deploy, invoque com. agentcore invoke

Adicione recursos ao seu projeto

agentcore addgerencia recursos emagentcore.json. Execute-o sem argumentos para o menu interativo ou direcione um recurso diretamente.

agentcore add memory        # Store conversation context
agentcore add agent         # Add a second agent to the same project
agentcore add gateway       # Connect external APIs/tools through Gateway
agentcore add credential    # Add an API key for a non-Bedrock provider
agentcore add evaluator     # Quality evaluation
agentcore add payment-manager   # Payments: create a payment manager
agentcore add payment-connector # Payments: link a payment provider

Cada comando add organiza a configuração e solicita os valores necessários. Depois de adicionar, execute agentcore deploy para provisionar.

Mergulhos profundos sobre os recursos que você pode conectar:

• AgentCore Memória - memória de curto e longo prazo, estratégias de recuperação

• AgentCore Gateway - conectividade governada com APIs e servidores MCP

• AgentCore Navegador - navegação gerenciada na web para agentes

• AgentCore Interpretador de código - execução de código em sandbox

• AgentCore Identidade — OAuth, provedores de credenciais de chave de API, identidade da carga de trabalho

• AgentCore Observabilidade - traços, registros e métricas em CloudWatch

• AgentCore VPC - execute agentes dentro da sua VPC

• AgentCore Pagamentos - pagamentos por microtransação para agentes via x402

Exibir registros e rastreamentos

# Stream recent logs
agentcore logs

# Filter
agentcore logs --since 30m --level error
agentcore logs --query "timeout"

# List recent traces
agentcore traces list

# Get a specific trace
agentcore traces get <trace-id>

Solução de problemas

Erros de permissão negada

Verifique suas credenciais comaws sts get-caller-identity. Certifique-se de que sua identidade tenha as permissões em Usar a AgentCore CLI.

Acesso ao modelo negado

O Amazon Bedrock permite o acesso aos modelos de fundação por padrão. Para usar um modelo sem fundamento, siga as etapas de acesso ao modelo.

Erros de implantação

Execute agentcore deploy --verbose para mostrar eventos de implantação em nível de recurso. A CLI verifica o status de bootstrap do AWS CDK. Se o bootstrap for necessário, a implantação interativa solicitará confirmação. agentcore deploy --yesaprova a operação de bootstrap sem um aviso.

Porta já em uso

Execute agentcore dev --port 3000 para usar uma porta local diferente.

Erros de validação de configuração

Execute agentcore validate para verificar a configuração do projeto.

Para obter mais informações, consulte Solucionar problemas do Amazon Bedrock AgentCore Runtime.

Fazer a limpeza.

agentcore remove all
agentcore deploy

remove allredefine a configuração. O acompanhamento deploy detecta o estado vazio e destrói os recursos da sua conta.

Próximas etapas

• O que é o AgentCore equipamento - o caminho baseado em configuração para um agente em execução. Use qualquer modelo, conecte-se a ferramentas, mantenha o estado, implante em sua VPC e passe a programar quando precisar.

• AgentCore amostras de código - exemplos completos de estruturas e recursos.