# Inizia a usare la AgentCore CLI
Questo tutorial mostra come utilizzare la [AgentCore CLI](https://github.com/aws/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](https://strandsagents.com/latest/documentation/docs/). Questo tutorial utilizza Strands Agents.
Per informazioni sul protocollo HTTP utilizzato dall'agente, consulta il [contratto di protocollo HTTP](runtime-http-protocol-contract.md).
**Topics**
+ [Prerequisiti](#prerequisites)
+ [Fase 1: Installare la AgentCore CLI](#setup-project)
+ [Fase 2: Crea il tuo progetto di agente](#create-agent)
+ [Fase 3: Esegui il test del tuo agente a livello locale](#configure-agent)
+ [Fase 4: Abilita l'osservabilità per il tuo agente](#enable-observability)
+ [Fase 5: Implementazione su Amazon AgentCore Bedrock Runtime](#deploy-runtime)
+ [Fase 6: Testa l'agente distribuito](#test-deployed-agent)
+ [Passaggio 7: richiama l'agente distribuito](#invoke-programmatically)
+ [Fase 8: Pulizia](#stop-session-or-clean-up)
+ [Trova le tue risorse](#find-resources)
+ [Problemi e soluzioni comuni](#common-issues)
+ [Opzioni avanzate (facoltative)](#advanced-options)
## Prerequisiti
Prima di iniziare, assicurati di avere:
+ ** AWS Account** con credenziali configurate. Per configurare le AWS credenziali, consulta [Configurazione e impostazioni dei file di credenziali nella CLI AWS](https://docs.aws.amazon.com/cli/latest/userguide/cli-configure-files.html).
+ **Node.js Oltre 20 installate.** La AgentCore CLI è distribuita come pacchetto npm.
+ **Python 3.10\+** installato. Il codice agente generato è Python.
+ ** AWS CDK installato.** La CLI utilizza il AWS CDK per distribuire le risorse. Per informazioni, consulta [Guida introduttiva](https://docs.aws.amazon.com/cdk/v2/guide/getting_started.html) al CDK. AWS
+ ** AWS Autorizzazioni**: per creare e distribuire un agente con la AgentCore CLI, è necessario disporre delle autorizzazioni appropriate. Per informazioni, consulta [Utilizzare la AgentCore CLI](https://docs.aws.amazon.com/bedrock-agentcore/latest/devguide/runtime-permissions.html#runtime-permissions-cli).
+ **Accesso al modello**: Anthropic Claude Sonnet 4.0 [abilitato](https://docs.aws.amazon.com/bedrock/latest/userguide/model-access-modify.html) nella console Amazon Bedrock (se si utilizza Bedrock come fornitore di modelli). [Per informazioni sull'utilizzo di un modello diverso con Strands Agents, consulta la sezione *Model Provider* nella documentazione di Strands Agents SDK.](https://strandsagents.com/latest/documentation/docs/)
## 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:
**Example**
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
```
1. Esegui `agentcore create` senza bandiere per avviare la procedura guidata interattiva:
```
agentcore create
```
1. Inserisci il nome del tuo progetto:
1. Scegliete il vostro framework di agenti e il vostro fornitore di modelli:
1. Rivedi la tua configurazione 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 --api-key-secret --wallet-secret
```
Questo configura il `AgentCorePaymentsPlugin` tuo agente e provvede all'infrastruttura di pagamento durante l'implementazione. Consulta [Payments quick start](https://docs.aws.amazon.com/bedrock-agentcore/latest/devguide/payments-getting-started.html) 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:
**Example**
1.
```
agentcore dev
```
1. Esegui `agentcore` per aprire la schermata principale di TUI, quindi seleziona **dev** per avviare il server di sviluppo locale:
```
agentcore
```
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. `--stream`Utilizzatelo per vedere la risposta trasmessa in streaming in tempo reale.
## Fase 4: Abilita l'osservabilità per il tuo agente
[Amazon Bedrock AgentCore Observability](https://docs.aws.amazon.com/bedrock-agentcore/latest/devguide/observability.html) 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](https://docs.aws.amazon.com/bedrock-agentcore/latest/devguide/observability-configure.html#observability-configure-builtin). Per osservare il tuo agente, consulta [Visualizzare i dati di osservabilità per i tuoi agenti Amazon Bedrock AgentCore ](https://docs.aws.amazon.com/bedrock-agentcore/latest/devguide/observability-view.html).
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 :
**Example**
1.
```
agentcore deploy
```
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
```
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. `-y`Da utilizzare per confermare automaticamente la distribuzione senza una richiesta.
Se la distribuzione fallisce, verifica i problemi [più comuni](#common-issues).
## Fase 6: Testa l'agente distribuito
Al termine della distribuzione, richiama l'agente distribuito:
**Example**
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 \
--auto-session \
--payment-user-id user@example.com
```
1. Esegui `agentcore` per aprire la schermata principale di TUI, quindi seleziona l'opzione invoke per chattare con il tuo agente schierato:
```
agentcore
```
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.](#common-issues)
## Passaggio 7: richiama l'agente distribuito
**Example**
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.
1. Puoi anche richiamare l'agente utilizzando l'operazione SDK. AWS [InvokeAgentRuntime](https://docs.aws.amazon.com/bedrock-agentcore/latest/APIReference/API_InvokeAgentRuntime.html) 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.](runtime-oauth.md)
## 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:
**Example**
1.
```
agentcore remove all
```
1. Esegui `agentcore` per aprire la schermata principale di TUI, quindi seleziona l'opzione di rimozione per scegliere quali risorse rimuovere:
```
agentcore
```
Quindi esegui nuovamente l'implementazione per eliminare le risorse: AWS
**Example**
1.
```
agentcore deploy
```
1. Dalla schermata principale della AgentCore CLI, seleziona di `deploy` applicare le risorse di rimozione e rimozione: AWS
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:
**Example**
1.
```
agentcore status
```
1. Esegui `agentcore` e seleziona `status` per visualizzare una dashboard live di tutte le risorse distribuite:
```
agentcore
```
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](https://docs.aws.amazon.com/bedrock-agentcore/latest/devguide/runtime-troubleshooting.html) 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 validate`Da 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 con`agentcore create`, puoi estenderlo utilizzando i `agentcore add` comandi. [Per il riferimento completo alla CLI, consulta la documentazione CLIAgentCore .](https://github.com/aws/agentcore-cli)
### 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