# 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](https://docs.aws.amazon.com/bedrock-agentcore/latest/devguide/runtime-service-contract.html): disporre di un file entrypoint .py che utilizzi l'`@app.entrypoint`annotazione di [Amazon Bedrock AgentCore Python](https://github.com/aws/bedrock-agentcore-sdk-python) SDK o implementi gli endpoint del server POST e GET. `/invocations` `/ping` ## Prerequisiti Prima di iniziare, assicurati di disporre dei seguenti elementi: + ** 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). + [Uv](https://docs.astral.sh/uv/getting-started/installation/) **installato** e [Python](https://docs.astral.sh/uv/guides/install-python/) 3.10\+ installato + ** AWS Autorizzazioni**: per creare e distribuire un agente con la AgentCore CLI, è necessario disporre delle autorizzazioni appropriate. Per ulteriori 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 nella console](https://docs.aws.amazon.com/bedrock/latest/userguide/model-access-modify.html) Amazon Bedrock. [Per informazioni sull'utilizzo di un modello diverso con gli Strands Agents, consulta la sezione Model *Provider nella documentazione dell'SDK di* Strands Agents.](https://strandsagents.com/latest/documentation/docs/) ## 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](https://strandsagents.com/latest/) 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](https://docs.aws.amazon.com/xray/latest/devguide/xray-services-adot.html). 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](https://docs.aws.amazon.com/bedrock-agentcore/latest/devguide/runtime-get-started-cli.html#common-issues). 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](https://docs.aws.amazon.com/bedrock-agentcore/latest/devguide/observability.html) 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](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). ## Fase 5: Esegui la distribuzione su Runtime e richiama AgentCore Implementa il tuo agente utilizzando uno dei seguenti metodi: **Example** 1. Saranno necessari i seguenti passaggi per distribuire un agente in Runtime. AgentCore Per ulteriori informazioni, consulta [Guida introduttiva alla AgentCore CLI](https://docs.aws.amazon.com/bedrock-agentcore/latest/devguide/runtime-get-started-cli.html). 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 utilizzando`agentcore 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. 1. **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 ![AgentCore distribuisci i progressi mostrando gli aggiornamenti dello stack CloudFormation](https://docs.aws.amazon.com/it_it/bedrock-agentcore/latest/devguide/images/tui/code-deploy-progress.png) Una volta completata la distribuzione, usalo `agentcore invoke` per testare il tuo agente. 1. 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. **Nota** . 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 ` Per modificare le autorizzazioni file in Windows, consulta [Set, View, Change, or Remove Permissions on an Object](https://learn.microsoft.com/en-us/previous-versions/windows/it-pro/windows-server-2008-R2-and-2008/cc731667(v=ws.10)) 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](https://boto3.amazonaws.com/v1/documentation/api/latest/reference/services/s3/client/create_bucket.html) 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.](https://docs.aws.amazon.com/bedrock-agentcore/latest/devguide/runtime-get-started-cli.html#invoke-programmatically) 1. 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: 1. Dalla home page degli agenti, scegli **Host Agent** 1. 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 1. 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) 1. 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](https://docs.aws.amazon.com/bedrock-agentcore/latest/devguide/runtime-permissions.html). 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: **Example** 1. 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](https://docs.aws.amazon.com/bedrock-agentcore/latest/APIReference/API_StopRuntimeSession.html) 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 ``` 1. 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='', 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='' ) 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!") ``` 1. ====== 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. **Topics** ### Percorso di ricerca delle dipendenze e librerie incluse nel 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 ``` ### Bytecode Python e *pycache* cartelle 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. ### Pacchetti di distribuzione con librerie native 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](https://pypi.org/)) 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: 1. Cerca il nome del pacchetto nella [pagina principale di Python Package Index](https://pypi.org/). 1. Seleziona la versione del pacchetto da utilizzare. 1. Scegli **Scarica file**. ### Utilizzo delle distribuzioni di origine 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](https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/EC2_GetStarted.html) EC2 User *Guide*.