Inscreva-se em um AWS account Pré-requisitos Etapa 1: instalar a AgentCore CLI Etapa 2: Crie seu projeto Etapa 3: teste localmente Etapa 4: implantar seu agente Etapa 5: invocar seu agente implantado Adicione recursos ao seu projeto Exibir registros e rastreamentos Solução de problemas Fazer a limpeza.Próximas etapas

Comece a usar a AgentCore CLI

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

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

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:

Empacota seu código em um artefato zip (ou cria um contêiner se) --build Container
Usa o AWS CDK nos bastidores para sintetizar e provisionar recursos
Cria um endpoint de tempo de AgentCore execução para seu agente
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 user@example.com

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

Invoque um agente programaticamente

Você pode invocar o agente implantado com a operação do AWS SDK InvokeAgentRuntime. Obtenha o ARN do tempo de execução do agente:


agentcore status

Crie um arquivo chamado invoke_agent.py. Agent ARNSubstitua pelo ARN do seu agente:


import json
import uuid

import boto3

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

client = boto3.client("bedrock-agentcore")
response = client.invoke_agent_runtime(
    agentRuntimeArn=agent_arn,
    runtimeSessionId=str(uuid.uuid4()),
    payload=json.dumps({"prompt": prompt}).encode(),
    qualifier="DEFAULT",
)

content = []
for chunk in response.get("response", []):
    content.append(chunk.decode("utf-8"))

print(json.loads("".join(content)))

Execute o código:


python invoke_agent.py

Sua identidade deve ter a bedrock-agentcore:InvokeAgentRuntime permissão.

nota

Para um agente que usa OAuth, faça uma solicitação HTTPS para InvokeAgentRuntime em vez de usar o AWS SDK. Para obter mais informações, consulte Autenticar e autorizar com autorização de entrada e saída.

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.

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 a usar a AgentCore CLI () TypeScript