Le traduzioni sono generate tramite traduzione automatica. In caso di conflitto tra il contenuto di una traduzione e la versione originale in Inglese, quest'ultima prevarrà.

Inizia senza la AgentCore CLI

È possibile creare un agente AgentCore Runtime senza la AgentCore CLI. È invece possibile utilizzare una combinazione di strumenti da riga di comando per configurare e distribuire l'agente su un AgentCore Runtime.

Questo tutorial mostra come distribuire un agente personalizzato senza utilizzare la CLI AgentCore . Un agente personalizzato è un agente creato senza utilizzare l'SDK AgentCore Python. In questo tutorial, l'agente personalizzato viene creato utilizzando FastAPI e Docker. L'agente personalizzato segue i requisiti AgentCore di runtime, il che significa che l'agente deve esporre gli endpoint /invocations POST e /ping GET ed essere impacchettato in un contenitore Docker. Amazon Bedrock AgentCore richiede l'architettura ARM64 per tutti gli agenti distribuiti.

Configurazione rapida

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 osservare un agente, abilita innanzitutto CloudWatch Transaction Search seguendo le istruzioni in Abilitazione dell'osservabilità. AgentCore

Installa uv

Per questo esempio, useremo il gestore di uv pacchetti, anche se puoi usare qualsiasi utilità Python o gestore di pacchetti. Per installarlo uv su macOS:

curl -LsSf https://astral.sh/uv/install.sh | sh

Per le istruzioni di installazione su altre piattaforme, consulta la documentazione https://docs.astral.sh/uv/getting-started/installation/ uv.

Crea il tuo progetto di agente

Configurazione del progetto

Requisiti del contratto di agente

Il tuo agente personalizzato deve soddisfare questi requisiti fondamentali:

Struttura del progetto

Nota: per comodità, l'esempio seguente utilizza FastAPI Server come framework del server Web per la gestione delle richieste.

Il progetto dovrebbe avere la seguente struttura:

my-custom-agent/
├── agent.py                 # FastAPI application
├── Dockerfile               # ARM64 container configuration
├── pyproject.toml           # Created by uv init
└── uv.lock                  # Created automatically by uv

Esempio completo di Strands Agent

Crea agent.py nella radice del tuo progetto i seguenti contenuti:

Esempio agent.py

from fastapi import FastAPI, HTTPException
from pydantic import BaseModel
from typing import Dict, Any
from datetime import datetime
from strands import Agent

app = FastAPI(title="Strands Agent Server", version="1.0.0")

# Initialize Strands agent
strands_agent = Agent()

class InvocationRequest(BaseModel):
    input: Dict[str, Any]

class InvocationResponse(BaseModel):
    output: Dict[str, Any]

@app.post("/invocations", response_model=InvocationResponse)
async def invoke_agent(request: InvocationRequest):
    try:
        user_message = request.input.get("prompt", "")
        if not isinstance(user_message, str) or not user_message.strip():
            raise HTTPException(
                status_code=400,
                detail="Invalid input: 'prompt' must be a non-empty string"
            )

        result = strands_agent(user_message)
        response = {
            "message": result.message,
            "timestamp": datetime.utcnow().isoformat()
        }

        return InvocationResponse(output=response)

    except Exception as e:
        raise HTTPException(status_code=500, detail=f"Agent processing failed: {str(e)}")

@app.get("/ping")
async def ping():
    return {"status": "healthy"}

if __name__ == "__main__":
    import uvicorn
    uvicorn.run(app, host="0.0.0.0", port=8080)

Questa implementazione:

Test in locale

Testare il tuo agente

Crea un dockerfile

Crea Dockerfile nella radice del tuo progetto i seguenti contenuti:

Esempio: Dockerfile

# Use uv's ARM64 Python base image
FROM --platform=linux/arm64 ghcr.io/astral-sh/uv:python3.11-bookworm-slim

WORKDIR /app

# Copy uv files
COPY pyproject.toml uv.lock ./

# Install dependencies (including strands-agents)
RUN uv sync --frozen --no-cache

# Copy agent file
COPY agent.py ./

# Expose port
EXPOSE 8080

# Run application
CMD ["uv", "run", "uvicorn", "agent:app", "--host", "0.0.0.0", "--port", "8080"]

Questo Dockerfile:

Crea e distribuisci un'immagine ARM64

Configura docker buildx

Docker buildx consente di creare immagini per diverse architetture. Configuralo con:

docker buildx create --use

Compila per ARM64 ed esegui il test localmente

Creazione e test dell'immagine

Crea un repository ECR e distribuiscilo

Implementazione su ECR

Implementa il runtime dell'agente

Crea un file denominato deploy_agent.py con i seguenti contenuti:

Esempio deploy_agent.py

import boto3

client = boto3.client('bedrock-agentcore-control', region_name='us-west-2')

response = client.create_agent_runtime(
    agentRuntimeName='strands_agent',
    agentRuntimeArtifact={
        'containerConfiguration': {
            'containerUri': 'account-id.dkr.ecr.us-west-2.amazonaws.com/my-strands-agent:latest'
        }
    },
    networkConfiguration={"networkMode": "PUBLIC"},
    roleArn='arn:aws:iam::account-id:role/AgentRuntimeRole',
    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']}")

Esegui lo script per distribuire il tuo agente:

uv run deploy_agent.py

Questo script utilizza l'create_agent_runtimeoperazione per distribuire il tuo agente su Amazon Bedrock. AgentCore Assicurati di sostituirlo account-id con il tuo ID AWS account effettivo e assicurati che il ruolo IAM disponga delle autorizzazioni necessarie. Per ulteriori informazioni, consulta IAM Permissions for AgentCore Runtime.

Richiamo dell'agente

Crea un file denominato invoke_agent.py con i seguenti contenuti:

Esempio: invoke_agent.py

import boto3
import json

agent_core_client = boto3.client('bedrock-agentcore', region_name='us-west-2')
payload = json.dumps({
    "input": {"prompt": "Explain machine learning in simple terms"}
})

response = agent_core_client.invoke_agent_runtime(
    agentRuntimeArn='arn:aws:bedrock-agentcore:us-west-2:account-id:runtime/myStrandsAgent-suffix',
    runtimeSessionId='dfmeoagmreaklgmrkleafremoigrmtesogmtrskhmtkrlshmt',  # Must be 33+ chars
    payload=payload,
    qualifier="DEFAULT"
)

response_body = response['response'].read()
response_data = json.loads(response_body)
print("Agent Response:", response_data)

Esegui lo script per richiamare il tuo agente:

uv run invoke_agent.py

Questo script utilizza l'operazione InvokeAgentRuntime AWS SDK per inviare una richiesta all'agente distribuito. Assicurati di sostituire account-id e agentArn con i tuoi valori effettivi.

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 Inbound Auth e Outbound Auth.

Formato di risposta previsto

Quando invocate il vostro agente, riceverete una risposta come questa:

Esempio di risposta

{
  "output": {
    "message": {
      "role": "assistant",
      "content": [
        {
          "text": "# Artificial Intelligence in Simple Terms\n\nArtificial Intelligence (AI) is technology that allows computers to do tasks that normally need human intelligence. Think of it as teaching machines to:\n\n- Learn from information (like how you learn from experience)\n- Make decisions based on what they've learned\n- Recognize patterns (like identifying faces in photos)\n- Understand language (like when I respond to your questions)\n\nInstead of following specific step-by-step instructions for every situation, AI systems can adapt to new information and improve over time.\n\nExamples you might use every day include voice assistants like Siri, recommendation systems on streaming services, and email spam filters that learn which messages are unwanted."
        }
      ]
    },
    "timestamp": "2025-07-13T01:48:06.740668"
  }
}

Interrompi la sessione di runtime

Per interrompere la sessione in esecuzione prima di quella configurabile IdleRuntimeSessionTimeout (impostazione predefinita a 15 minuti) e risparmiare su eventuali costi irreversibili, esegui: stop_runtime_session

Crea un file denominato stop_runtime_session.py con i seguenti contenuti:

Esempio stop_runtime_session.py

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/myStrandsAgent-suffix',
    runtimeSessionId='dfmeoagmreaklgmrkleafremoigrmtesogmtrskhmtkrlshmt',
    qualifier="DEFAULT"
)

Riepilogo dei AgentCore requisiti di Amazon Bedrock

Conclusioni

In questa guida, hai imparato a:

Seguendo questi passaggi, puoi creare e distribuire agenti personalizzati che sfruttano la potenza di Amazon Bedrock AgentCore mantenendo il pieno controllo sull'implementazione del tuo agente.