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 in un AgentCore Runtime.

Questo tutorial mostra come distribuire un agente personalizzato senza utilizzare la AgentCore CLI. 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 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 di avvio rapido

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 Enabling observability. AgentCore

Installa uv

Per questo esempio, useremo il gestore di uv pacchetti, sebbene sia possibile utilizzare qualsiasi utilità o gestore di pacchetti Python. 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 uv.

Crea il tuo progetto di agente

Configurazione del tuo progetto

Requisiti contrattuali per agenti

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 agente Strands

Crea agent.py nella radice del tuo progetto con il seguente contenuto:

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 user_message:
            raise HTTPException(
                status_code=400,
                detail="No prompt found in input. Please provide a 'prompt' key in the input."
            )

        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

Stai testando il tuo agente

Crea dockerfile

Crea Dockerfile nella radice del tuo progetto con il seguente contenuto:

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 file Dockerfile:

Crea e distribuisci l'immagine ARM64

Configura docker buildx

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

docker buildx create --use

Crea per ARM64 e prova localmente

Creazione e test della tua immagine

Crea un repository ECR e distribuiscilo

Distribuzione 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 AgentCore Bedrock. Assicurati di sostituirlo account-id con l'ID AWS dell'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 autenticazione in entrata e autenticazione in uscita.

Formato di risposta previsto

Quando richiami il tuo agente, riceverai una risposta come questa:

Esempio di risposta di esempio

{
  "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: 15 minuti) e risparmiare su eventuali costi inutili, 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.