View a markdown version of this page

Inizia a usare la AgentCore CLI - Amazon Bedrock AgentCore
PrerequisitiFase 1: Installare la AgentCore CLIFase 2: Crea il tuo progetto di agenteFase 3: Esegui il test del tuo agente a livello localeFase 4: Abilita l'osservabilità per il tuo agenteFase 5: Implementazione su Amazon AgentCore Bedrock RuntimeFase 6: Testa l'agente distribuitoPassaggio 7: richiama l'agente distribuitoFase 8: PuliziaTrova le tue risorseProblemi e soluzioni comuniOpzioni avanzate (facoltative)

Inizia a usare la AgentCore CLI

Questo tutorial mostra come utilizzare la AgentCore CLI per creare, distribuire e richiamare un agente Python su Amazon Bedrock Runtime. AgentCore

La AgentCore CLI è uno strumento da riga di comando che raggruppa i progetti degli agenti, li distribuisce in Amazon Bedrock Runtime e li richiama. AgentCore Puoi utilizzare la CLI con i più diffusi framework di agenti Python come Strands Agents, LangChain/LangGraph Google ADK e OpenAI Agents. Questo tutorial utilizza Strands Agents.

Per informazioni sul protocollo HTTP utilizzato dall'agente, consulta il contratto di protocollo HTTP.

Prerequisiti

Prima di iniziare, assicurati di avere:

Fase 1: Installare la AgentCore CLI

Installa la AgentCore CLI a livello globale:

npm install -g @aws/agentcore

Verifica l’installazione:

agentcore --help

Verrà visualizzato un output simile al seguente:

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.

Fase 2: Crea il tuo progetto di agente

Usa il agentcore create comando per costruire un nuovo progetto di agente:

Esempio
AgentCore CLI

  1. Passa i flag direttamente per creare un progetto in modo non interattivo:

    agentcore create --name MyAgent --framework Strands --protocol HTTP --model-provider Bedrock --memory none

    Per accettare tutte le impostazioni predefinite (Python, Strands, Bedrock, no memory), usa il flag: --defaults

    agentcore create --name MyAgent --defaults
Interactive

  1. Esegui agentcore create senza bandiere per avviare la procedura guidata interattiva:

    agentcore create

  2. Inserisci il nome del tuo progetto:

    Creazione guidata: inserisci il nome del progetto

  3. Scegliete il vostro framework di agenti e il vostro fornitore di modelli:

    Crea procedura guidata: seleziona il framework

  4. Rivedi la tua configurazione e conferma:

    Creazione guidata: verifica e conferma

Il agentcore create comando accetta i seguenti flag:

  • --name— Il nome del progetto (alfanumerico, inizia con una lettera, max 36 caratteri).

  • --framework— Il framework degli agenti. Valori supportati:Strands,LangChain_LangGraph,GoogleADK,OpenAIAgents.

  • --protocol— La modalità del protocollo. Valori supportati: HTTP (impostazione predefinita)MCP,A2A.

  • --build— Il tipo di build. Valori supportati: CodeZip (impostazione predefinita),Container.

  • --model-provider— Il fornitore del modello. Valori supportati:Bedrock,Anthropic,OpenAI,Gemini.

  • --memory— Configurazione della memoria. Valori supportati:none,shortTerm,longAndShortTerm.

Il comando genera una directory di progetto con la seguente struttura:

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

Il agentcore/agentcore.json file contiene la configurazione del progetto e dell'agente. Il app/MyAgent/main.py file contiene il codice dello starter agent che utilizza il framework selezionato.

Per aggiungere funzionalità di pagamento al tuo progetto, esegui:

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>

Questo configura il AgentCorePaymentsPlugin tuo agente e provvede all'infrastruttura di pagamento durante l'implementazione. Consulta Payments quick start per il flusso di lavoro completo.

Fase 3: Esegui il test del tuo agente a livello locale

Prima di eseguire la distribuzione su AWS, testate l'agente localmente utilizzando il server di sviluppo. Per prima cosa, accedi alla directory del progetto:

cd MyAgent

Se hai selezionato un fornitore di modelli che richiede una chiave API (OpenAI, Anthropic o Gemini), assicurati che la chiave sia configurata in. agentcore/.env.local

Avvia il server di sviluppo locale:

Esempio
AgentCore CLI

  1. agentcore dev
Interactive

  1. Esegui agentcore per aprire la schermata principale di TUI, quindi seleziona dev per avviare il server di sviluppo locale:

    agentcore
    AgentCore agent inspector con richiesta di chat

Il agentcore dev comando:

  • Apre Agent Inspector nel tuo browser web

  • Crea automaticamente un ambiente virtuale Python e installa le dipendenze

  • Avvia un server locale che imita l'ambiente Runtime AgentCore

  • Viene eseguito http://localhost:8080 per impostazione predefinita (si usa -p per cambiare la porta)

Per visualizzare i log del server in tempo reale (modalità non interattiva), usa il --logs flag:

agentcore dev --logs

In un terminale separato, richiamate il vostro agente locale:

agentcore dev "Hello, tell me a joke"

L'invio di un prompt lo invia al server di sviluppo locale in esecuzione. --streamUtilizzatelo per vedere la risposta trasmessa in streaming in tempo reale.

Fase 4: Abilita l'osservabilità per il tuo agente

Amazon Bedrock AgentCore Observability ti aiuta a tracciare, eseguire il debug e monitorare gli agenti ospitati in Amazon Bedrock Runtime. AgentCore Per prima cosa abilita CloudWatch Transaction Search seguendo le istruzioni in Enabling Amazon Bedrock AgentCore runtime observability. Per osservare il tuo agente, consulta Visualizzare i dati di osservabilità per i tuoi agenti Amazon Bedrock AgentCore .

Dopo aver distribuito l'agente, puoi utilizzare la AgentCore CLI per eseguire lo streaming dei log e visualizzare le tracce:

# Stream agent logs
agentcore logs

# List recent traces
agentcore traces list

Fase 5: Implementazione su Amazon AgentCore Bedrock Runtime

Implementa il tuo agente su Amazon Bedrock Runtime AgentCore :

Esempio
AgentCore CLI

  1. agentcore deploy
Interactive

  1. Esegui agentcore deploy per avviare la distribuzione. La CLI mostra lo stato di avanzamento dell'implementazione durante la creazione e la distribuzione del progetto:

    agentcore deploy
    Avanzamento dell'implementazione: creazione CloudFormation delle risorse e stato della distribuzione

Per visualizzare in anteprima la distribuzione senza apportare modifiche, usa il --dry-run flag:

agentcore deploy --dry-run

Il agentcore deploy comando:

  • Legge la tua agentcore/agentcore.json configurazione agentcore/aws-targets.json

  • Impacchetta il codice dell'agente (come CodeZip archivio o contenitore Docker, a seconda del tipo di build)

  • Utilizza il AWS CDK per sintetizzare e distribuire le risorse CloudFormation

  • Crea le AWS risorse necessarie (ruoli IAM, Amazon Bedrock AgentCore Runtime, ecc.)

Utilizzalo -v per un output dettagliato che mostra gli eventi di distribuzione a livello di risorsa. -yDa utilizzare per confermare automaticamente la distribuzione senza una richiesta.

Se la distribuzione fallisce, verifica i problemi più comuni.

Fase 6: Testa l'agente distribuito

Al termine della distribuzione, richiama l'agente distribuito:

Esempio
AgentCore CLI

  1. agentcore invoke "Tell me a joke"

    Puoi anche passare il prompt con il --prompt flag, specificare un runtime con --runtime o trasmettere la risposta in streaming in tempo reale con: --stream

    agentcore invoke --prompt "Tell me a joke" --stream

    Per mantenere una conversazione tra più chiamate, usa il flag: --session-id

    agentcore invoke --session-id my-session "What else can you tell me?"

    Se il tuo agente ha configurato i pagamenti, fornisci il contesto di pagamento:

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

  1. Esegui agentcore per aprire la schermata principale di TUI, quindi seleziona l'opzione invoke per chattare con il tuo agente schierato:

    agentcore
    Richiama la schermata TUI che mostra l'interfaccia di chat

Se vedi uno scherzo nella risposta, il tuo agente è in esecuzione in Amazon Bedrock AgentCore Runtime e può essere richiamato. In caso contrario, verifica la presenza di problemi comuni.

Passaggio 7: richiama l'agente distribuito

Esempio
AgentCore CLI

  1. Richiama l'agente distribuito con un prompt:

    agentcore invoke --runtime MyAgent "Hello, what can you do?"

    Trasmetti la risposta in tempo reale:

    agentcore invoke --runtime MyAgent "Tell me a joke" --stream

    Esegui agentcore invoke senza chiedere conferma per aprire la chat interattiva TUI, che trasmette le risposte per impostazione predefinita e mantiene la sessione automaticamente.

AWS Python SDK (Boto3)

  1. Puoi anche richiamare l'agente utilizzando l'operazione SDK. AWS InvokeAgentRuntime Per ottenere l'ARN del tuo agente distribuito, usa il comando: agentcore status

    agentcore status

    Usa il seguente codice boto3 (AWS SDK per Python) per richiamare il tuo agente. Sostituisci Agent ARN con l'ARN del tuo agente. Assicurati di disporre delle bedrock-agentcore:InvokeAgentRuntime autorizzazioni. Crea un file denominato invoke_agent.py e aggiungi il seguente codice:

    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)))

    Apri una finestra di terminale ed esegui il codice con il seguente comando:

    python invoke_agent.py

    In caso di successo, dovresti vedere una barzelletta nella risposta. Se la chiamata fallisce, controlla i log utilizzando agentcore logs o visualizzali in Amazon CloudWatch.

    Nota

    Se prevedi di integrare il tuo agente con OAuth, non puoi utilizzare l' AWS SDK per chiamare. InvokeAgentRuntime Effettua invece una richiesta HTTPS a. InvokeAgentRuntime Per ulteriori informazioni, consulta Autenticazione e autorizzazione con autenticazione in entrata e autenticazione in uscita.

Fase 8: Pulizia

Se non desideri più ospitare l'agente in Amazon Bedrock AgentCore Runtime, rimuovi le risorse distribuite AWS . Innanzitutto, rimuovi tutte le risorse dalla configurazione locale:

Esempio
AgentCore CLI

  1. agentcore remove all
Interactive

  1. Esegui agentcore per aprire la schermata principale di TUI, quindi seleziona l'opzione di rimozione per scegliere quali risorse rimuovere:

    agentcore
    Rimuovi la selezione delle risorse (TUI)

Quindi esegui nuovamente l'implementazione per eliminare le risorse: AWS

Esempio
AgentCore CLI

  1. agentcore deploy
Interactive

  1. Dalla schermata principale della AgentCore CLI, seleziona di deploy applicare le risorse di rimozione e rimozione: AWS

    Avanzamento della distribuzione: eliminazione CloudFormation delle risorse e stato di smontaggio

Il remove all comando ripristina il file di agentcore/agentcore.json configurazione agentcore/aws-targets.json preservando lo stato di distribuzione. Il successivo deploy rileva le risorse rimosse e abbatte le risorse corrispondenti. AWS

Trova le tue risorse

Dopo la distribuzione, puoi controllare lo stato delle tue risorse utilizzando la AgentCore CLI:

Esempio
AgentCore CLI

  1. agentcore status
Interactive

  1. Esegui agentcore e seleziona status per visualizzare una dashboard live di tutte le risorse distribuite:

    agentcore
    AgentCore Dashboard di stato CLI TUI

Puoi anche visualizzare le tue risorse nella Console: AWS

Risorsa Location (Ubicazione)

Registri degli agenti

CloudWatch → Gruppi di log → /aws/bedrock-agentcore/runtimes/{agent-id}-DEFAULT

CloudFormation Pila

CloudFormation → Stacks → cerca il nome del tuo progetto

Ruolo IAM

IAM → Ruoli → Cerca "» BedrockAgentCore

Risorse S3 () CodeZip

S3 → Bucket → Secchio di staging CDK

Problemi e soluzioni comuni

Problemi e soluzioni comuni quando si inizia a usare la AgentCore CLI. Per ulteriori informazioni sulla risoluzione dei problemi, consulta Risoluzione dei problemi di Amazon AgentCore Bedrock Runtime.

Errori di autorizzazione negata

Verifica AWS le tue credenziali e le tue autorizzazioni:

  • Verifica le credenziali AWS : aws sts get-caller-identity

  • Verifica di avere allegate le politiche richieste

  • Consulta la politica sulle autorizzazioni dei chiamanti per i requisiti dettagliati

Accesso al modello negato

Abilita l'accesso al modello nella console Bedrock:

  • Abilita Anthropic Claude 4.0 nella console Bedrock

  • Assicurati di trovarti nella AWS regione corretta (us-west-2 per impostazione predefinita)

Errori di distribuzione CDK

Controlla la configurazione e le autorizzazioni del CDK:

  • Assicurati di aver avviato il tuo AWS account per CDK: cdk bootstrap

  • Verifica che il chiamante includa le autorizzazioni e l'accesso CDK CloudFormation

  • Utilizzatelo agentcore deploy -v per un output dettagliato per identificare la risorsa in errore

Porta 8080 in uso (solo locale)

Trova e interrompi i processi che utilizzano la porta 8080:

Utilizza lsof -ti:8080 per ottenere un elenco di processi che utilizzano la porta 8080.

Utilizzare kill -9 PID per interrompere il processo. Sostituisci PID con l'ID del processo.

In alternativa, avvia il server di sviluppo su una porta diversa: agentcore dev -p 3000

Mancata corrispondenza tra le regioni

Verifica la AWS regione con aws configure get region e assicurati che agentcore/aws-targets.json corrisponda a quella in cui devono essere distribuite le tue risorse.

Errori di convalida della configurazione

Convalida i tuoi file di configurazione:

agentcore validateDa utilizzare per verificare la presenza di errori di sintassi o di schema nei file agentcore/agentcore.json di configurazione correlati.

Opzioni avanzate (facoltative)

Dopo aver creato il progetto dell'agente conagentcore create, puoi estenderlo utilizzando i agentcore add comandi. Per il riferimento completo alla CLI, consulta la documentazione CLIAgentCore .

Tipi di build

Quando crei il tuo progetto, scegli un tipo di build adatto alle tue esigenze:

CodeZip (default) (predefinito)

Il codice del tuo agente viene impacchettato come archivio zip e caricato su S3. Questa è l'opzione più semplice e non richiede Docker:

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

Il codice dell'agente è impacchettato come immagine del contenitore Docker. Usa questa opzione quando hai bisogno di dipendenze personalizzate a livello di sistema o di un'immagine di base specifica:

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

Aggiungi risorse al tuo progetto

Puoi aggiungere risorse aggiuntive al tuo progetto dopo la creazione:

# 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

Dopo aver aggiunto le risorse, corri agentcore deploy a fornire le nuove risorse in AWS.

Perché ARM64?

Amazon Bedrock AgentCore Runtime viene eseguito su ARM64 (AWS Graviton). La AgentCore CLI gestisce automaticamente la compatibilità dell'architettura sia per i tipi di build che per i tipi CodeZip di build Container. Per le build di container, solo le immagini create per ARM64 funzioneranno se distribuite su Amazon Bedrock Runtime. AgentCore