Pré-requisitos Etapa 1: instalar a AgentCore CLI Etapa 2: criar seu projeto de agente Etapa 3: teste seu agente localmente Etapa 4: habilitar a observabilidade para seu agente Etapa 5: Implantar no Amazon Bedrock AgentCore Runtime Etapa 6: testar seu agente implantado Etapa 7: invocar seu agente implantado Etapa 8: Limpeza Encontrar seus recursos Problemas e soluções comuns de Opções avançadas (opcional)

Comece a usar a AgentCore CLI

Este tutorial mostra como usar a AgentCore CLI para criar, implantar e invocar um agente Python no Amazon Bedrock Runtime. AgentCore

A AgentCore CLI é uma ferramenta de linha de comando que estrutura projetos de agentes, os implanta no Amazon Bedrock Runtime e os invoca. AgentCore Você pode usar a CLI com estruturas de agentes Python populares, como Strands Agents LangChain/LangGraph, Google ADK e OpenAI Agents. Este tutorial usa Strands Agents.

Para obter informações sobre o protocolo HTTP que o agente usa, consulte Contrato de protocolo HTTP.

Tópicos

Pré-requisitos
Etapa 1: instalar a AgentCore CLI
Etapa 2: criar seu projeto de agente
Etapa 3: teste seu agente localmente
Etapa 4: habilitar a observabilidade para seu agente
Etapa 5: Implantar no Amazon Bedrock AgentCore Runtime
Etapa 6: testar seu agente implantado
Etapa 7: invocar seu agente implantado
Etapa 8: Limpeza
Encontrar seus recursos
Problemas e soluções comuns de
Opções avançadas (opcional)

Pré-requisitos

Antes de começar, verifique se você tem:

AWS Conta com credenciais configuradas. Para definir suas AWS credenciais, consulte Configuração e configurações do arquivo de credenciais na CLI AWS.
Node.js Mais de 20 instalados. A AgentCore CLI é distribuída como um pacote npm.
Python 3.10+ instalado. O código do agente gerado é Python.
AWS CDK instalado. A CLI usa o AWS CDK para implantar recursos. Para obter informações, consulte Introdução ao AWS CDK.
AWS Permissões: para criar e implantar um agente com a AgentCore CLI, você deve ter as permissões apropriadas. Para obter informações, consulte Usar a AgentCore CLI.
Acesso ao modelo: Anthropic Claude Sonnet 4.0 habilitado no console Amazon Bedrock (se estiver usando o Bedrock como fornecedor do modelo). Para obter informações sobre como usar um modelo diferente com os Strands Agents, consulte a seção Model Providers na documentação do SDK do Strands Agents.

Etapa 1: instalar a AgentCore CLI

Instale a AgentCore CLI globalmente:


npm install -g @aws/agentcore

Verifique a instalação:


agentcore --help

Você deve ver uma saída semelhante a:


Usage: agentcore [options] [command]

Build and deploy Agentic AI applications on AgentCore

Options:
  -V, --version                output the version number
  -h, --help                   Display help

Commands:
  add [subcommand]             Add resources (agent, evaluator, online-eval,
                               memory, identity, target)
  dev|d [options]              Launch local development server with hot-reload.
  deploy|p [options]           Deploy project infrastructure to AWS via CDK.
  create [options]             Create a new AgentCore project
  evals                        View past eval run results.
  fetch                        Fetch access info for deployed resources.
  help                         Display help topics
  invoke|i [options] [prompt]  Invoke a deployed agent endpoint.
  logs|l [options]             Stream or search agent runtime logs.
  package|pkg [options]        Package agent artifacts without deploying.
  pause                        Pause an online eval config.
  remove [subcommand]          Remove resources from project config.
  resume                       Resume a paused online eval config.
  run                          Run on-demand evaluation.
  status|s [options]           Show deployed resource details and status.
  traces|t                     View and download agent traces.
  update [options]             Check for and install CLI updates
  validate [options]           Validate agentcore/ config files.

Etapa 2: criar seu projeto de agente

Use o agentcore create comando para estruturar um novo projeto de agente:

exemplo

O agentcore create comando aceita os seguintes sinalizadores:

--name— O nome do projeto (alfanumérico, começa com uma letra, no máximo 36 caracteres).
--framework— A estrutura do agente. Valores suportados:Strands,LangChain_LangGraph,GoogleADK,OpenAIAgents.
--protocol— O modo de protocolo. Valores suportados: HTTP (padrão),MCP,A2A.
--build— O tipo de construção. Valores suportados: CodeZip (padrão),Container.
--model-provider— O fornecedor do modelo. Valores suportados:Bedrock,Anthropic,OpenAI,Gemini.
--memory— Configuração de memória. Valores suportados:none,shortTerm,longAndShortTerm.

O comando gera um diretório de projeto com a seguinte estrutura:


MyAgent/
  agentcore/
    agentcore.json        # Project and agent configuration
    aws-targets.json      # AWS account and region targets
    .env.local            # Local environment variables (gitignored)
  app/
    MyAgent/
      main.py             # Agent entrypoint
      pyproject.toml      # Python dependencies
  README.md

O agentcore/agentcore.json arquivo contém a configuração do seu projeto e do agente. O app/MyAgent/main.py arquivo contém o código do agente inicial usando a estrutura selecionada.

Para adicionar recursos de pagamento ao seu projeto, execute:


agentcore add payment-manager --name MyPayments --auto-payment --default-spend-limit 5.00
agentcore add payment-connector --manager MyPayments --name MyConnector --provider CoinbaseCDP \
  --api-key-id <KEY_ID> --api-key-secret <KEY_SECRET> --wallet-secret <WALLET_SECRET>

Isso configura o AgentCorePaymentsPlugin em seu agente e provisiona a infraestrutura de pagamento na implantação. Consulte Início rápido de pagamentos para ver o fluxo de trabalho completo.

Etapa 3: teste seu agente localmente

Antes de implantar AWS, teste seu agente localmente usando o servidor de desenvolvimento. Primeiro, vá para o diretório do projeto:


cd MyAgent

Se você selecionou um provedor de modelos que exige uma chave de API (OpenAI, Anthropic ou Gemini), verifique se a chave está configurada em. agentcore/.env.local

Inicie o servidor de desenvolvimento local:

exemplo

O agentcore dev comando:

Abre o inspetor de agentes em seu navegador
Cria automaticamente um ambiente virtual Python e instala dependências
Inicia um servidor local que imita o AgentCore ambiente Runtime
É executado http://localhost:8080 por padrão (use -p para alterar a porta)

Para visualizar os registros do servidor em tempo real (modo não interativo), use o --logs sinalizador:


agentcore dev --logs

Em um terminal separado, chame seu agente local:


agentcore dev "Hello, tell me a joke"

Passar um prompt o envia para o servidor de desenvolvimento local em execução. Use --stream para ver a resposta transmitida em tempo real.

Etapa 4: habilitar a observabilidade para seu agente

O Amazon Bedrock AgentCore Observability ajuda você a rastrear, depurar e monitorar agentes que você hospeda no Amazon Bedrock Runtime. AgentCore Primeiro, habilite a Pesquisa de CloudWatch transações seguindo as instruções em Habilitando a observabilidade do tempo de AgentCore execução do Amazon Bedrock. Para observar seu agente, consulte Visualizar dados de observabilidade de seus agentes do Amazon Bedrock AgentCore .

Depois de implantar seu agente, você pode usar a AgentCore CLI para transmitir registros e visualizar rastreamentos:


# Stream agent logs
agentcore logs

# List recent traces
agentcore traces list

Etapa 5: Implantar no Amazon Bedrock AgentCore Runtime

Implante seu agente no Amazon Bedrock AgentCore Runtime:

exemplo

Para visualizar a implantação sem fazer alterações, use o --dry-run sinalizador:


agentcore deploy --dry-run

O agentcore deploy comando:

Lê sua agentcore/agentcore.json agentcore/aws-targets.json configuração
Empacota seu código de agente (como um CodeZip arquivo ou contêiner Docker, dependendo do tipo de compilação)
Usa o AWS CDK para sintetizar e implantar recursos CloudFormation
Cria os AWS recursos necessários (funções do IAM, Amazon Bedrock AgentCore Runtime etc.)

Use -v para saída detalhada que mostra eventos de implantação em nível de recurso. Use -y para confirmar automaticamente a implantação sem um aviso.

Se a implantação falhar, verifique se há problemas comuns.

Etapa 6: testar seu agente implantado

Após a conclusão da implantação, invoque seu agente implantado:

exemplo

Se você ver uma piada na resposta, seu agente está em execução no Amazon Bedrock AgentCore Runtime e pode ser invocado. Caso contrário, verifique se há problemas comuns.

Etapa 7: invocar seu agente implantado

exemplo

AgentCore CLI

Invoque seu agente implantado com um prompt:
```
agentcore invoke --runtime MyAgent "Hello, what can you do?"
```
Transmita a resposta em tempo real:
```
agentcore invoke --runtime MyAgent "Tell me a joke" --stream
```
Execute agentcore invoke sem um aviso para abrir o TUI de bate-papo interativo, que transmite respostas por padrão e mantém sua sessão automaticamente.

AWS Python SDK (Boto3)

Você também pode invocar o agente usando a operação do AWS SDK. InvokeAgentRuntime Para obter o ARN do seu agente implantado, use o comando: agentcore status
```
agentcore status
```
Use o código boto3 (AWS SDK para Python) a seguir para invocar seu agente. Agent ARNSubstitua pelo ARN do seu agente. Verifique se você tem bedrock-agentcore:InvokeAgentRuntime permissões. Crie um arquivo chamado invoke_agent.py e adicione o seguinte código:
```
import json
import uuid
import boto3

agent_arn = "Agent ARN"
prompt = "Tell me a joke"

# Initialize the Amazon Bedrock AgentCore client
agent_core_client = boto3.client('bedrock-agentcore')

# Prepare the payload
payload = json.dumps({"prompt": prompt}).encode()

# Invoke the agent
response = agent_core_client.invoke_agent_runtime(
    agentRuntimeArn=agent_arn,
    runtimeSessionId=str(uuid.uuid4()),
    payload=payload,
    qualifier="DEFAULT"
)

content = []
for chunk in response.get("response", []):
    content.append(chunk.decode('utf-8'))
print(json.loads(''.join(content)))
```
Abra uma janela de terminal e execute o código com o seguinte comando:
```
python invoke_agent.py
```
Se for bem-sucedido, você verá uma piada na resposta. Se a chamada falhar, verifique os registros usando agentcore logs ou visualize-os na Amazon CloudWatch.

nota
Se você planeja integrar seu agente ao OAuth, não pode usar o AWS SDK para fazer chamadas. InvokeAgentRuntime Em vez disso, faça uma solicitação HTTPS paraInvokeAgentRuntime. Para obter mais informações, consulte Autenticar e autorizar com Autenticação de Entrada e Autenticação de Saída.

Etapa 8: Limpeza

Se você não quiser mais hospedar o agente no Amazon Bedrock AgentCore Runtime, remova os recursos implantados. AWS Primeiro, remova todos os recursos da sua configuração local:

exemplo

Em seguida, implante novamente para reduzir os AWS recursos:

exemplo

O remove all comando redefine o arquivo de agentcore/agentcore.json configuração enquanto preserva o estado agentcore/aws-targets.json de implantação. O subseqüente deploy detecta os recursos removidos e destrói os AWS recursos correspondentes.

Encontrar seus recursos

Após a implantação, você pode verificar o status dos seus recursos usando a AgentCore CLI:

exemplo

Você também pode ver seus recursos no AWS console:

Recurso	Local
Registros do agente	CloudWatch → Grupos de registros → `/aws/bedrock-agentcore/runtimes/{agent-id}-DEFAULT`
CloudFormation Pilha	CloudFormation → Stacks → pesquise o nome do seu projeto
IAM Role	IAM → Funções → Pesquisar por "BedrockAgentCore”
Ativos do S3 () CodeZip	S3 → Buckets → Balde de armazenamento CDK

Problemas e soluções comuns de

Problemas e soluções comuns ao começar a usar a AgentCore CLI. Para obter mais informações sobre solução de problemas, consulte Solucionar problemas do Amazon Bedrock AgentCore Runtime.

Erros de permissão negada

Verifique suas AWS credenciais e permissões:

Verifique AWS as credenciais: aws sts get-caller-identity
Verifique se você tem as políticas necessárias anexadas
Revise a política de permissões do chamador para obter os requisitos detalhados

Acesso ao modelo negado

Ative o acesso ao modelo no console Bedrock:

Ative o Anthropic Claude 4.0 no console Bedrock
Verifique se você está na AWS região correta (us-west-2 por padrão)

Erros de implantação do CDK

Verifique a configuração e as permissões do CDK:

Verifique se você inicializou sua AWS conta para o CDK: cdk bootstrap
Verifique se as permissões do chamador incluem CloudFormation acesso ao CDK
Use agentcore deploy -v para saída detalhada para identificar o recurso com falha

Porta 8080 em uso (somente local)

Localize e interrompa os processos que estão usando a porta 8080:

Use lsof -ti:8080 para obter uma lista de processos usando a porta 8080.

Use kill -9 PID para interromper o processo. PIDSubstitua pela ID do processo.

Como alternativa, inicie o servidor de desenvolvimento em uma porta diferente: agentcore dev -p 3000

Incompatibilidade de regiões

Verifique a AWS região com aws configure get region e certifique-se de que a região em agentcore/aws-targets.json corresponda ao local em que seus recursos devem ser implantados.

Erros de validação de configuração

Valide seus arquivos de configuração:

Use agentcore validate para verificar erros de agentcore/agentcore.json sintaxe ou esquema nos arquivos de configuração relacionados.

Opções avançadas (opcional)

Depois de criar seu projeto de agente comagentcore create, você pode estendê-lo usando os agentcore add comandos. Para obter a referência completa da CLI, consulte a documentação da CLIAgentCore .

Tipos de compilação

Ao criar seu projeto, escolha um tipo de construção que atenda às suas necessidades:

CodeZip (padrão)

Seu código de agente é empacotado como um arquivo zip e enviado para o S3. Essa é a opção mais simples e não requer Docker:


agentcore create --name MyAgent --framework Strands --model-provider Bedrock --memory none --build CodeZip

Contêiner

O código do seu agente é empacotado como uma imagem de contêiner do Docker. Use essa opção quando precisar de dependências personalizadas no nível do sistema ou de uma imagem base específica:


agentcore create --name MyAgent --framework Strands --model-provider Bedrock --memory none --build Container

Adicione recursos ao seu projeto

Você pode adicionar recursos adicionais ao seu projeto após a criação:


# Add another agent to the same project
agentcore add agent --name SecondAgent --language Python --framework Strands --model-provider Bedrock

# Add a memory store for conversational context
agentcore add memory --name MyMemory --strategies SEMANTIC

# Add an API key credential for external services
agentcore add credential --name MyApiKey --type api-key --api-key your-api-key

# Add a payment manager for x402 microtransactions
agentcore add payment-manager --name MyPayments --auto-payment --default-spend-limit 5.00

Depois de adicionar recursos, execute agentcore deploy para provisionar os novos recursos AWS.

Por que ARM64?

O Amazon Bedrock AgentCore Runtime é executado em ARM64 (AWS Graviton). A AgentCore CLI gerencia automaticamente a compatibilidade de arquitetura para os tipos de compilação CodeZip e Container. Para compilações de contêineres, somente imagens criadas para ARM64 funcionarão quando implantadas no Amazon Bedrock Runtime. AgentCore

Atenção O Javascript está desativado ou não está disponível no seu navegador.

Para usar a documentação da AWS, o Javascript deve estar ativado. Consulte as páginas de Ajuda do navegador para obter instruções.

Convenções do documento

Comece a usar o AgentCore Runtime

Comece com o AgentCore CLI () TypeScript

Comece a usar a AgentCore CLI

Tópicos

Pré-requisitos

Etapa 1: instalar a AgentCore CLI

Etapa 2: criar seu projeto de agente

exemplo

Etapa 3: teste seu agente localmente

exemplo

Etapa 4: habilitar a observabilidade para seu agente

Etapa 5: Implantar no Amazon Bedrock AgentCore Runtime

exemplo

Etapa 6: testar seu agente implantado

exemplo

Etapa 7: invocar seu agente implantado

exemplo

nota

Etapa 8: Limpeza

exemplo

exemplo

Encontrar seus recursos

exemplo

Problemas e soluções comuns de

Opções avançadas (opcional)

Tipos de compilação

Adicione recursos ao seu projeto

Por que ARM64?