Distribuzione diretta del codice per Python
L'implementazione diretta del codice ti consente di portare il tuo Python-based agente su Amazon Bedrock AgentCore Runtime semplicemente impacchettando il codice dell'agente e le sue dipendenze in un archivio di file.zip. Il tuo agente deve comunque rispettare i requisiti AgentCore di Runtime: disporre di un file entrypoint .py che utilizzi l'@app.entrypointannotazione di Amazon Bedrock AgentCore Python SDK o implementi gli endpoint del server POST e GET. /invocations /ping
Prerequisiti
Prima di iniziare, assicurati di disporre dei seguenti elementi:
Passaggio 1: configurare il progetto e installare le dipendenze
Inizializza il tuo progetto con i seguenti comandi:
uv init agentcore_runtime_direct_deploy --python 3.13
cd agentcore_runtime_direct_deploy
Aggiungi pacchetti principali:
uv add bedrock-agentcore strands-agents
Installa la AgentCore CLI (richiesta per i passaggi seguenti):
npm install -g @aws/agentcore
Descrizioni dei pacchetti:
-
bedrock-agentcore - L'SDK Amazon AgentCore Bedrock per la creazione di agenti AI
-
strands-agents - L'SDK di Strands Agents
-
@ aws/agentcore - La AgentCore CLI
Facoltativamente, esegui uv add aws-opentelemetry-distro per abilitare le tracce di AgentCore osservabilità di Amazon Bedrock.
Uv creerà automaticamente un pyproject.toml file con dipendenze, uv.lock file con chiusura delle dipendenze e directory. .venv
Passaggio 2: crea il tuo progetto di agente
Usa il agentcore create comando per configurare un progetto skeleton agent con il framework che preferisci:
agentcore create
Il comando ti chiederà di:
-
Scegli un framework (scegli Strands Agents per questo tutorial)
-
Fornisci un nome per il progetto
-
Scegli un modello (di base o di produzione)
-
Scegli il fornitore del modello e altre opzioni
Questo comando genera:
-
Codice dell'agente con il framework selezionato
-
Un pyproject.toml file con le dipendenze necessarie
-
Un agentcore/agentcore.json file di configurazione
-
File Infrastructure as Code (IaC) se è selezionato il modello di produzione
Fase 3: Esegui il test in locale
Assicurati che la porta 8080 sia libera prima di iniziare. Vedi Porta 8080 in uso (solo locale) in Problemi e soluzioni comuni.
Apri una finestra di terminale e avvia l'agente con il seguente comando:
agentcore dev --no-browser
Metti alla prova il tuo agente aprendo un'altra finestra di terminale e inserisci il seguente comando:
curl -X POST http://localhost:8080/invocations \
-H "Content-Type: application/json" \
-d '{"prompt": "Hello!"}'
Operazione riuscita: dovresti vedere una risposta del tipo{"result": "Hello! I’m here to help…"}. Nella finestra del terminale in cui è in esecuzione l'agente, immettete Ctrl+C per arrestarlo.
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 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 .
Fase 5: Esegui la distribuzione su Runtime e richiama AgentCore
Implementa il tuo agente utilizzando uno dei seguenti metodi:
Esempio
- AgentCore CLI
-
-
Saranno necessari i seguenti passaggi per distribuire un agente in Runtime. AgentCore Per ulteriori informazioni, consulta Guida introduttiva alla AgentCore CLI. Se Uv è disponibile, la AgentCore CLI consiglierà la distribuzione diretta del codice. Altrimenti verrà impostato per impostazione predefinita il tipo di distribuzione del contenitore.
Dopo aver configurato l'agente utilizzandoagentcore create, utilizza il deploy comando per creare un pacchetto di distribuzione zip, caricarlo nel bucket specificato e distribuire l'agente.
agentcore deploy
Chiediamo all'agente di raccontare una barzelletta!
agentcore invoke "Tell me a joke"
La prima distribuzione richiede tempo per installare le dipendenze, ma i successivi aggiornamenti dell'agente ottimizzano questa operazione riutilizzando le dipendenze compresse
Gestione della configurazione
È possibile modificare la configurazione dell'agente in qualsiasi momento utilizzando i agentcore add comandi o modificando direttamente il file di agentcore/agentcore.json configurazione.
Il file di configurazione consente di aggiornare i parametri di distribuzione come la configurazione del VPC, i ruoli di esecuzione, i timeout delle sessioni e le impostazioni dell'autorizzatore OAuth.
- Interactive
-
-
Esegui agentcore per aprire la TUI, quindi seleziona deploy. La schermata di distribuzione mostra i progressi in tempo reale mentre convalida il progetto, sintetizza CloudFormation e fornisce le risorse: AWS
Una volta completata la distribuzione, usalo agentcore invoke per testare il tuo agente.
- Custom zip + boto3
-
-
Per scaricare una ruota compatibile con AgentCore Runtime, utilizzate l'opzione uv pip--python-platform. AgentCore Runtime supporta solo l'architettura del set di istruzioni arm64, esegui il seguente comando. Sostituisci --python 3.x con la versione del runtime Python che stai utilizzando.
uv pip install \
--python-platform aarch64-manylinux2014 \
--python-version 3.13 \
--target=deployment_package \
--only-binary=:all: \
-r pyproject.toml
Crea un file.zip con le librerie installate nella radice del progetto.
cd deployment_package
zip -r ../deployment_package.zip .
Aggiungi il main.py file e gli altri file del pacchetto alla radice del file.zip.
cd ..
zip deployment_package.zip main.py
Dopo aver creato il pacchetto di distribuzione.zip, puoi utilizzarlo per creare un nuovo AgentCore Runtime o aggiornarne uno esistente. Puoi distribuire il tuo pacchetto .zip utilizzando l'API AgentCore Runtime, la console Runtime e l'interfaccia a riga AgentCore di AWS comando. La AgentCore CLI si occuperà dei passaggi precedenti per creare un file.zip.
. La dimensione massima per un pacchetto di distribuzione.zip per AgentCore Runtime è 250 MB (compresso) e 750 MB (decompresso). Tieni presente che questo limite si applica alla dimensione combinata di tutti i file che carichi. Il AgentCore Runtime richiede l'autorizzazione per leggere i file nel pacchetto di distribuzione. Nella notazione ottale delle autorizzazioni Linux, AgentCore Runtime richiede 644 autorizzazioni per i file non eseguibili (rw-r—r--) e 755 permessi (rwxr-xr-x) per le directory e i file eseguibili. In Linux e macOS, utilizza il comando chmod per modificare le autorizzazioni file su file e directory nel pacchetto di implementazione. Ad esempio, per assegnare a un file non eseguibile le autorizzazioni corrette, esegui il comando seguente,. chmod 644 <filepath> Per modificare le autorizzazioni file in Windows, consulta Set, View, Change, or Remove Permissions on an Object nella documentazione di Microsoft Windows. +.. Se non concedi a AgentCore Runtime le autorizzazioni necessarie per accedere alle directory nel pacchetto di distribuzione, AgentCore Runtime imposta le autorizzazioni per tali directory su 755 (rwxr-xr-x).
Un archivio ZIP contenente le dipendenze Linux arm64 deve essere caricato su S3 come prerequisito per Create Agent Runtime. Il codice seguente richiede che il bucket S3 specificato esista già. Segui la AWS documentazione qui per creare un bucket usando boto3. Il seguente codice boto3 caricherà l'archivio di file.zip su un s3 e creerà il runtime Amazon Bedrock. AgentCore
import boto3
account_id = "your aws account id"
agent_name = "strands_10_23"
s3_client = boto3.client('s3', region_name='us-west-2')
print("Uploading deployment.zip to S3...")
s3_client.upload_file(
'deployment_package.zip', # archive on file system
f"bedrock-agentcore-code-{account_id}-us-west-2", # bucket name
f"{agent_name}/deployment_package.zip", # prefix
ExtraArgs={'ExpectedBucketOwner': account_id} # ownership check
)
print("Upload completed successfully!")
print(f"S3 Location: s3://bedrock-agentcore-code-{account_id}-us-west-2/{agent_name}/deployment_package.zip")
agentcore_client = boto3.client('bedrock-agentcore-control', region_name='us-west-2')
response = agentcore_client.create_agent_runtime(
agentRuntimeName=agent_name,
agentRuntimeArtifact={
'codeConfiguration': {
'code': {
's3': {
'bucket': f"bedrock-agentcore-code-{account_id}-us-west-2",
'prefix': f"{agent_name}/deployment_package.zip"
}
},
'runtime': 'PYTHON_3_13',
'entryPoint': ['opentelemetry-instrument', 'main.py']
} # if not adding otel dependency, remove opentelemetry-instrument from entrypoint array
},
networkConfiguration={"networkMode": "PUBLIC"},
roleArn=f"arn:aws:iam::{account_id}:role/AmazonBedrockAgentCoreSDKRuntime-us-west-2",
lifecycleConfiguration={
'idleRuntimeSessionTimeout': 300, # 5 min, configurable
'maxLifetime': 1800 # 30 minutes, configurable
},
)
print(f"Agent Runtime created successfully!")
print(f"Agent Runtime ARN: {response['agentRuntimeArn']}")
print(f"Status: {response['status']}")
Per ulteriori informazioni sull'invocazione di un agente a livello di codice, consulta Richiamare un agente a livello di codice.
- console
-
-
Puoi distribuire il tuo agente utilizzando la AgentCore console Amazon Bedrock con supporto di runtime gestito. La console fornisce un'interfaccia intuitiva per il caricamento di file ZIP e la configurazione delle impostazioni dell'agente.
Per eseguire la distribuzione utilizzando la console, è necessario innanzitutto creare il pacchetto di distribuzione seguendo i passaggi indicati nella scheda Custom zip + boto3 riportata sopra.
Crea agente tramite console
Per creare il tuo agente:
-
Dalla home page degli agenti, scegli Host Agent
-
Scegliete la fonte selezionata:
-
S3 Source: carica dal bucket S3
-
Caricamento locale: carica il file ZIP dal tuo computer
-
Modelli: utilizza modelli di agenti predefiniti
-
Configura le impostazioni del tuo agente:
-
Nome dell'agente
-
Versione runtime (Python 3.13 consigliato)
-
Punto di ingresso (ad es.) main.py
-
Ruolo di esecuzione (crearne uno nuovo o utilizzare uno esistente)
-
Scegli Create Agent da distribuire
Crea endpoint
Scegli Crea endpoint per creare un nuovo endpoint per il tuo agente. Il nome dell'endpoint e la versione associata verranno precompilati.
Endpoint del test
Seleziona un endpoint e scegli Test Endpoint per passare all'endpoint per il Playground/Sandbox test.
Requisiti del ruolo di esecuzione
Il tuo agente richiede un ruolo di esecuzione con le autorizzazioni appropriate. Per informazioni dettagliate sui ruoli e le autorizzazioni di esecuzione, consulta Autorizzazioni AgentCore di runtime. Il ruolo di esecuzione deve includere le autorizzazioni di AgentCore runtime di base di Amazon Bedrock, le autorizzazioni di accesso S3 per il pacchetto di distribuzione e le autorizzazioni CloudWatch Logs per l'osservabilità.
Passaggio 6: interrompere la sessione, l'aggiornamento o la pulizia
Interrompi la sessione di runtime, aggiorna o pulisci l'agente utilizzando uno dei seguenti metodi:
Esempio
- AgentCore CLI
-
-
Per aggiornare il AgentCore Runtime precedentemente distribuito, esegui:
agentcore deploy
Per interrompere una sessione in esecuzione prima di quella configurabile IdleRuntimeSessionTimeout (impostazione predefinita: 15 minuti) e risparmiare su eventuali costi imprevedibili, utilizzate l'operazione API. StopRuntimeSession La AgentCore CLI attualmente non supporta l'interruzione diretta delle sessioni.
Per eliminare tutte le risorse relative a un AgentCore Runtime, rimuovi prima tutte le risorse e poi distribuiscile per eliminare le risorse: AWS
agentcore remove all
agentcore deploy
- boto3
-
-
Il seguente codice boto3 aggiornerà un Runtime. AgentCore
import boto3
account_id = "your aws account id"
agent_name = "strands_10_23"
s3_client = boto3.client('s3', region_name='us-west-2')
print("Uploading deployment.zip to S3...")
s3_client.upload_file(
'deployment_package.zip', # archive on file system
f"bedrock-agentcore-code-{account_id}-us-west-2", # bucket name
f"{agent_name}/deployment_package.zip", # prefix
ExtraArgs={'ExpectedBucketOwner': account_id} # ownership check
)
print("Upload completed successfully!")
print(f"S3 Location: s3://bedrock-agentcore-code-{account_id}-us-west-2/{agent_name}/deployment_package.zip")
bedrock_agentcore_client = boto3.client('bedrock-agentcore-control', region_name='us-west-2')
response = bedrock_agentcore_client.update_agent_runtime(
agentRuntimeId='<your-agent-id>',
agentRuntimeArtifact={
'codeConfiguration': {
'code': {
's3': {
'bucket': f"bedrock-agentcore-code-{account_id}-us-west-2",
'prefix': f"{agent_name}/deployment_package.zip"
}
},
'runtime': 'PYTHON_3_13',
'entryPoint': ['opentelemetry-instrument', 'main.py']
} # if not adding otel dependency, remove opentelemetry-instrument from entrypoint array
},
networkConfiguration={"networkMode": "PUBLIC"},
roleArn=f"arn:aws:iam::{account_id}:role/AmazonBedrockAgentCoreSDKRuntime-us-west-2"
)
print(f"Agent Runtime updated successfully!")
print(f"Agent Runtime ARN: {response['agentRuntimeArn']}")
print(f"Status: {response['status']}")
Per interrompere la sessione in esecuzione prima di quella configurabile IdleRuntimeSessionTimeout (impostazione predefinita a 15 minuti) e risparmiare su eventuali costi inutili, utilizza il seguente codice boto3:
import boto3
agent_core_client = boto3.client('bedrock-agentcore', region_name='us-west-2')
response = agent_core_client.stop_runtime_session(
agentRuntimeArn='arn:aws:bedrock-agentcore:us-west-2:account-id:runtime/agent-name-suffix',
runtimeSessionId='your-session-id',
qualifier="DEFAULT"
)
Il seguente codice boto3 eliminerà il AgentCore runtime di Amazon Bedrock e il file di archivio.zip in s3.
import boto3
account_id = "your aws account id"
agent_name = "strands_10_23"
bedrock_agentcore_client = boto3.client('bedrock-agentcore-control', region_name='us-west-2')
print("Deleting Agent from Amazon Bedrock AgentCore Runtime!")
response = bedrock_agentcore_client.delete_agent_runtime(
agentRuntimeId='<agent-id>'
)
print(f"Agent Runtime delete successfully!")
print(f"Status: {response['status']}")
s3_client = boto3.client('s3', region_name='us-west-2')
print("Deleting deployment archive from S3...")
s3_client.delete_object(
Bucket=f"bedrock-agentcore-code-{account_id}-us-west-2",
Key=f"{agent_name}/deployment_package.zip",
ExpectedBucketOwner=account_id
)
print("Archive deleted successfully from S3!")
- console
-
-
====== Agente di aggiornamento
Dalla pagina dei dettagli dell'agente, scegli Update hosting per creare una nuova versione con codice o configurazione aggiornati.
Aggiorna endpoint
Seleziona un endpoint dalla tabella Endpoints e scegli Modifica per aggiornare la descrizione o la versione associata.
Elimina un endpoint
Seleziona un endpoint e scegli Elimina. Dovrai digitare «elimina» per confermare l'eliminazione.
Elimina agente
Dall'elenco degli agenti o dalla pagina dei dettagli, seleziona il tuo agente e scegli Elimina per rimuovere l'agente e tutte le risorse associate.
Python-specific concetti per l'implementazione diretta del codice
Scopri Python-specific i concetti relativi all'utilizzo della distribuzione diretta del codice con Amazon Bedrock AgentCore Runtime.
Quando utilizzi un'istruzione import nel codice, il runtime Python cerca nelle directory del suo percorso di ricerca finché non trova il modulo o il pacchetto. Per impostazione predefinita, la prima posizione ricercata dal runtime è la directory in cui il pacchetto di distribuzione.zip viene decompresso e montato (). /var/task
È possibile visualizzare il percorso di ricerca completo per il proprio agente AgentCore Runtime aggiungendo il seguente frammento di codice.
import sys
search_path = sys.path
print(search_path)
Puoi anche aggiungere dipendenze in una cartella separata all'interno del tuo pacchetto .zip. Ad esempio, potreste aggiungere una versione dell'SDK Boto3 a una cartella del pacchetto .zip denominata. common Quando il pacchetto .zip viene decompresso e montato, questa cartella viene inserita nella directory /var/task. Per utilizzare nel codice una dipendenza da una cartella del pacchetto di implementazione .zip, utilizza un'istruzione import from. Ad esempio, per utilizzare una versione di Boto3 da una cartella denominata common nel tuo pacchetto .zip, usa la seguente istruzione.
from common import boto3
Ti consigliamo di non includere
pycache
cartelle nel pacchetto di distribuzione dell'agente. Il bytecode Python compilato su una macchina di compilazione con un'architettura o un sistema operativo diversi potrebbe non essere compatibile con l' AgentCore ambiente di esecuzione Runtime.
Se la tua funzione utilizza solo pacchetti e moduli Python puri, puoi usare il comando uv pip install per installare le tue dipendenze su qualsiasi computer di compilazione locale e creare il file .zip. Molte librerie Python popolari, tra cui NumPy e Pandas, non sono Python puro e contengono codice scritto in C o C. Quando si aggiungono librerie contenenti C/C codice al pacchetto di distribuzione, è necessario creare il pacchetto correttamente per renderlo compatibile con l'ambiente di esecuzione Runtime. AgentCore
La maggior parte dei pacchetti disponibili nel Python Package Index (PyPI) sono disponibili come «wheels» (file.whl). Un file .whl è un tipo di file ZIP che contiene una distribuzione compilata con file binari precompilati per un particolare sistema operativo e un'architettura di set di istruzioni. Per rendere il tuo pacchetto di distribuzione compatibile con Amazon Bedrock AgentCore AgentCore Runtime, installa la ruota per i sistemi operativi Linux e l'architettura del set di istruzioni arm64.
Alcuni pacchetti possono essere disponibili solo come distribuzioni di origine. Per questi pacchetti, devi compilare e creare tu stesso i componenti C/C ++.
Per vedere quali distribuzioni sono disponibili per il pacchetto richiesto, procedi come segue:
Se il tuo pacchetto è disponibile solo come distribuzione sorgente, devi creare tu stesso le librerie C/C ++. Per rendere il tuo pacchetto compatibile con l'ambiente di esecuzione Amazon Bedrock AgentCore AgentCore Runtime, devi crearlo in un ambiente che utilizzi lo stesso sistema operativo Amazon Linux con set di istruzioni arm64. Puoi farlo creando il tuo pacchetto in un'istanza Linux Amazon Elastic Compute Cloud (Amazon EC2).
Per informazioni su come avviare e connettersi a un'istanza Amazon EC2 Linux, consulta la Guida introduttiva ad Amazon EC2 nella Amazon EC2 User Guide.
