Inizia con la AgentCore CLI

Questa guida rapida consente di passare da zero a un agente in esecuzione in pochi minuti utilizzando la CLI AgentCore . Dovrai installare la CLI, creare lo scaffold di un progetto, testarlo localmente, distribuirlo e invocare il AWS tuo agente.

Due modi per creare un agente sulla AgentCore stessa CLI:

• Imbracatura gestita. Dichiari l'agente in un file di configurazione (modello, prompt, strumenti, memoria) ed AgentCore esegue il ciclo per te. Nessun framework, nessun codice di orchestrazione. Un buon percorso se si desidera il percorso più veloce dall'idea a un agente funzionante. Ulteriori informazioni.

• Code-based agente. Scrivi il loop degli agenti in Python usando un framework che già conosci (Strands LangGraph, Google ADK o OpenAI Agents) e lo distribuisci su Runtime. AgentCore Controllo completo sulla logica di orchestrazione.

Questa pagina illustra il flusso basato sul codice. Per quanto riguarda l'imbracatura, vedi Cos'è l'imbracatura. AgentCore

Registrati per un AWS account

Iscrivetevi a un AWS account

Per iniziare AWS, è necessario un AWS account. Per informazioni sulla creazione di un AWS account, vedi Guida introduttiva a un AWS account nella Guida di riferimento per la gestione degli AWS account.

Prerequisiti

• Node.js 20 o versione successiva. La AgentCore CLI è distribuita come pacchetto npm. Verifica con. node --version Se necessario, esegui l'installazione da nodejs.org.

• npm. Incluso con Node.js

• Un AWS account con credenziali configurate. Configura tramite AWS CLI, variabili di ambiente o un AWS profilo. Vedi Configurazione della CLI. AWS

• Python 3.10 o successivo (per il codice dell'agente). Verificare con. python3 --version

• Autorizzazioni IAM. La tua identità necessita delle autorizzazioni per effettuare chiamate AgentCore API e per assumere i ruoli di bootstrap CDK utilizzati durante la distribuzione. Vedi Usare la CLI. AgentCore

• Accesso al modello. Amazon Bedrock consente l'accesso ai modelli di base per impostazione predefinita. I modelli disponibili includono i modelli AI di Amazon Nova, Anthropic Claude, Meta Llama e Mistral. Per utilizzare modelli non di base, segui i passaggi di accesso al modello. https://docs.aws.amazon.com/bedrock/latest/userguide/model-access.html#model-access-sdk-step4

• Docker. Obbligatorio solo se scegli il tipo di Container build. Il tipo di CodeZip build predefinito non richiede Docker.

Fase 1: Installare la CLI AgentCore

npm install -g @aws/agentcore

Verifica:

agentcore --version

Nota

Se questo segnala un errore invece di un numero di versione, un vecchio agentcore comando Python sta nascondendo quello di npm sul tuo. PATH Ciò accade se in precedenza hai installato il pacchetto bedrock-agentcore-starter-toolkit pip ed è più comune su Windows. Eseguipip uninstall bedrock-agentcore-starter-toolkit, quindi apri un nuovo terminale e riprova.

Per effettuare l'aggiornamento in un secondo momento, esegui nuovamente il comando install o. agentcore update Fonte e problemi: agentcore-cli attivo. GitHub

Fase 2: Crea il tuo progetto

agentcore create

La procedura guidata interattiva chiede innanzitutto cosa vuoi creare:

• Harness: un loop di agenti gestito basato sulla configurazione. Non è richiesto alcun codice di framework o orchestrazione. Vedi Cos'è l'imbracatura. AgentCore

• Agente: un agente basato su codice che utilizza un framework a tua scelta, distribuito in Runtime. AgentCore

• Salta: crea la struttura del progetto senza un agente. Aggiungine uno più tardi conagentcore add.

Se scegli Agent, la procedura guidata continua con:

• Framework: Strands Agents (consigliato) LangChain/LangGraph, Google Agent Development Kit o OpenAI Agents SDK

• Fornitore di modelli: Amazon Bedrock, Anthropic, OpenAI o Gemini

• Memoria: nessuna, solo a breve termine o a lungo e breve termine

• Tipo di build: CodeZip (impostazione predefinita) o Contenitore

Puoi anche passare i flag direttamente per creare un agente basato sul codice:

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

Per tutti i comandi e le opzioni disponibili, vedi riferimento AgentCore alla CLI.

Tipi di build

• CodeZip(impostazione predefinita) impacchetta il codice in un file zip e lo carica su Amazon S3. Questo tipo di build non richiede Docker.

• Containercrea e distribuisce un'immagine del contenitore. Questo tipo di build richiede un demone Docker in esecuzione.

Struttura del progetto

agentcore creategenera una configurazione condivisa del progetto e una diversa struttura applicativa per agenti e dispositivi basati sul codice:

Esempio

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

File chiave:

• agentcore/agentcore.json- Il file di configurazione principale. Definisce agenti, cablaggi, archivi di memoria, gateway, credenziali e altre risorse. I agentcore remove comandi agentcore add and gestiscono questo file.

• agentcore/aws-targets.json- Gli AWS account e le regioni per la distribuzione.

• agentcore/.env.local- Segreti locali, come le chiavi API per i fornitori di modelli.

• app/- La directory dell'applicazione. Un agente basato su codice contiene un punto di ingresso e delle dipendenze. Un'imbracatura contiene e. harness.json system-prompt.md

Fase 3: Eseguire il test localmente

cd MyProject
agentcore dev

agentcore devcrea un ambiente virtuale Python, installa le dipendenze, avvia un server locale con hot reload e apre l'agent inspector nel browser in modo da poter chattare con l'agente, ispezionare le tracce e sfogliare le risorse del progetto. Le modifiche al codice vengono rilevate automaticamente.

Fase 4: Implementa il tuo agente

agentcore deploy

Implementazione:

1. Impacchetta il codice in un artefatto zip (o crea un contenitore se) --build Container

2. Utilizza il AWS CDK sotto il cofano per sintetizzare e fornire risorse

3. Crea un endpoint AgentCore Runtime per il tuo agente

4. Configura la registrazione e l' CloudWatch osservabilità

La prima distribuzione richiede alcuni minuti mentre CDK avvia il tuo account. Le implementazioni successive sono più veloci.

Visualizza in anteprima cosa cambierà senza implementarlo:

agentcore deploy --dry-run

Verifica lo stato:

agentcore status

Passaggio 5: richiama il tuo agente distribuito

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

Se il tuo agente ha configurato i pagamenti, fornisci il contesto di pagamento al momento della richiesta:

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

Questo è il ciclo. Iterateapp/MyAgent/main.py, testate conagentcore dev, distribuite conagentcore deploy, invocate con. agentcore invoke

Richiama un agente a livello di codice

È possibile richiamare l'agente distribuito con l'operazione SDK. AWS InvokeAgentRuntime Ottieni l'ARN di runtime dell'agente:

agentcore status

Crea un file denominato invoke_agent.py. Sostituiscilo Agent ARN con l'ARN del tuo 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)))

Esegui il codice:

python invoke_agent.py

La tua identità deve avere l'bedrock-agentcore:InvokeAgentRuntimeautorizzazione.

Nota

Per un agente che utilizza OAuth, effettua una richiesta HTTPS a InvokeAgentRuntime invece di utilizzare l' AWS SDK. Per ulteriori informazioni, consulta Autenticazione e autorizzazione con autorizzazione in entrata e in uscita.

Aggiungi funzionalità al tuo progetto

agentcore addgestisce le risorse inagentcore.json. Eseguilo senza argomenti per il menu interattivo o scegli come destinazione una risorsa direttamente.

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

Ogni comando add impalca la configurazione e richiede i valori richiesti. Dopo l'aggiunta, corri al provisioning. agentcore deploy

Approfondisci le funzionalità che puoi collegare:

• AgentCore Memoria: memoria a breve e lungo termine, strategie di recupero

• AgentCore Gateway: connettività gestita alle API e ai server MCP

• AgentCore Browser: navigazione web gestita per gli agenti

• AgentCore Code Interpreter: esecuzione di codice in modalità sandbox

• AgentCore Identità: OAuth, fornitori di credenziali per le chiavi API, identità del carico di lavoro

• AgentCore Osservabilità: tracce, registri e metriche in CloudWatch

• AgentCore VPC: esegui agenti all'interno del tuo VPC

• AgentCore Pagamenti: pagamenti con microtransazioni per agenti tramite x402

Visualizza registri e tracce

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

Risoluzione dei problemi

Errori relativi all'autorizzazione negata

Verifica le tue credenziali conaws sts get-caller-identity. Assicurati che la tua identità disponga delle autorizzazioni in Usa la CLI AgentCore .

Accesso al modello negato

Amazon Bedrock consente l'accesso ai modelli di base per impostazione predefinita. Per utilizzare un modello non di base, segui i passaggi di accesso al modello.

Errori di distribuzione

Esegui agentcore deploy --verbose per mostrare gli eventi di distribuzione a livello di risorsa. La CLI controlla lo stato di bootstrap del CDK. AWS Se è richiesto il bootstrap, la distribuzione interattiva richiede una conferma. agentcore deploy --yesapprova l'operazione di bootstrap senza un prompt.

Porta già in uso

Esegui agentcore dev --port 3000 per utilizzare una porta locale diversa.

Errori di convalida della configurazione

Esegui agentcore validate per verificare la configurazione del progetto.

Per ulteriori informazioni, consulta Risoluzione dei problemi relativi ad Amazon AgentCore Bedrock Runtime.

Eliminazione

agentcore remove all
agentcore deploy

remove allripristina la configurazione. Il follow-up deploy rileva lo stato vuoto e riduce le risorse del tuo account.

Fasi successive

• Qual è il AgentCore cablaggio: il percorso basato sulla configurazione verso un agente in esecuzione. Usa qualsiasi modello, connettiti agli strumenti, persisti nello stato, implementa nel tuo VPC e passa al codice quando ne hai bisogno.

• AgentCore esempi di codice: esempi completi su framework e funzionalità.