Python Agent

Genera un agente AI Python per costruire agenti con strumenti e, opzionalmente, distribuiscilo su Amazon Bedrock AgentCore Runtime. Scegli il framework dell’agente con l’opzione framework: Strands (predefinito) o LangChain (basato su LangGraph).

Il generatore espone il tuo agente tramite un protocol server. Entrambi i framework supportano HTTP (predefinito), il protocollo Agent-to-Agent (A2A) per l’interoperabilità con altri agenti compatibili A2A, e il protocollo AG-UI per l’integrazione diretta con il frontend tramite CopilotKit.

Utilizzo

Genera un Agent

Puoi generare un Python Agent in due modi:

Esegui questo generatore@aws/nx-plugin:py#agent

CLI
VSCode

$ pnpm nx g @aws/nx-plugin:py#agent

$ yarn nx g @aws/nx-plugin:py#agent

$ npx nx g @aws/nx-plugin:py#agent

$ bunx nx g @aws/nx-plugin:py#agent

Installa il Nx Console VSCode Plugin se non l'hai già fatto
Apri la console Nx in VSCode
Clicca su Generate (UI) nella sezione "Common Nx Commands"
Cerca @aws/nx-plugin - py#agent
Compila i parametri richiesti
Clicca su Generate

Componi il tuo comando9

projectObbligatorio

framework

authinfra = agentcore | agentcore-ecr

protocol

iac

infra

session

name

preferInstallDependencies

true

--dry-runPuoi anche eseguire una prova per vedere quali file verrebbero modificati

Opzioni

Opzioni del generatore9 opzioni

projectObbligatoriostring: Il progetto a cui aggiungere lo Agent
frameworkenumPredefinito: strands: L'SDK dell'agente da utilizzare.
strandslangchain
authenuminfra = agentcore | agentcore-ecrPredefinito: iam: Il metodo utilizzato per autenticare con il tuo Agent. Applicabile solo quando infra è impostato (ignorato quando infra è none).
iamcognito
protocolenumPredefinito: http: Il protocollo server per il tuo Agent. HTTP espone un server HTTP FastAPI. A2A espone un server con protocollo Agent-to-Agent. AG-UI espone un server con protocollo Agent-User Interaction per l'integrazione diretta con il frontend.
httpa2aag-ui
iacenumPredefinito: inherit: Il provider IaC preferito. Per impostazione predefinita viene ereditato dalla selezione iniziale.
inheritcdkterraform
infraenumPredefinito: agentcore: Il tipo di infrastruttura per ospitare il tuo Agent. agentcore distribuisce il tuo codice come zip in un runtime gestito da AgentCore per il ciclo di build e deploy più veloce. agentcore-ecr costruisce e ospita un'immagine container invece, per il controllo a livello di sistema operativo o per una pipeline container consolidata.
agentcoreagentcore-ecrnone
sessionenumPredefinito: s3: L'archiviazione utilizzata per persistere la sessione del tuo Agent. LangChain supporta 's3' o 'dynamodb-s3'; Strands supporta 's3'; 'in-memory' è valido per entrambi.
s3dynamodb-s3in-memory
namestring: Il nome del tuo Agent (predefinito: agent)
preferInstallDependenciesbooleanPredefinito: true: Se preferire l'installazione delle dipendenze dopo l'esecuzione del generatore. Impostare su false per rimandare l'installazione quando si eseguono più generatori in batch (l'installazione viene comunque eseguita se necessaria affinché i generatori successivi possano calcolare il grafo dei progetti Nx); installare una volta alla fine.

Output del Generatore

Il generatore aggiungerà i seguenti file al tuo progetto Python esistente. I file generati dipendono dal protocol scelto:

Protocollo HTTP (predefinito)

Directoryyour-project/
- Directoryyour_module/
  - Directoryagent/ (or custom name if specified)
    __init__.py Python package initialization
    init.py FastAPI application setup with CORS and error handling middleware
    agent.py Main agent definition with sample tools
    session.py Resolves the framework-specific session persistence implementation
    Directorymiddleware/
    __init__.py Python package initialization
    session_id_middleware.py Binds the inbound AgentCore session ID for the request
    main.py FastAPI entry point for Bedrock AgentCore Runtime
    Dockerfile Container image definition (only when infra is agentcore-ecr)
- pyproject.toml Updated with Strands dependencies
- project.json Updated with agent serve targets

Protocollo A2A

Il punto di ingresso espone il tuo agente tramite il protocollo A2A (Strands utilizza il Strands A2A Server; LangChain avvolge il grafo in un esecutore a2a-sdk), montato su un’app FastAPI:

Directoryyour-project/
- Directoryyour_module/
  - Directoryagent/ (or custom name if specified)
    __init__.py Python package initialization
    agent.py Main agent definition with sample tools
    session.py Resolves the framework-specific session persistence implementation
    Directorymiddleware/
    __init__.py Python package initialization
    session_id_middleware.py Binds the inbound AgentCore session ID for the request
    main.py A2A server entry point
    Dockerfile Container image definition (only when infra is agentcore-ecr)
- pyproject.toml Updated with framework and A2A dependencies
- project.json Updated with agent serve targets

Protocollo AG-UI

Il punto di ingresso espone il tuo agente tramite il protocollo AG-UI per l’integrazione diretta con il frontend tramite CopilotKit. Gli agenti Strands utilizzano l’integrazione ag-ui-strands; gli agenti LangChain utilizzano ag-ui-langgraph:

Directoryyour-project/
- Directoryyour_module/
  - Directoryagent/ (or custom name if specified)
    __init__.py Python package initialization
    agent.py Main agent definition with sample tools
    session.py Resolves the framework-specific session persistence implementation
    Directorymiddleware/
    __init__.py Python package initialization
    session_id_middleware.py Binds the inbound AgentCore session ID for the request
    main.py AG-UI server entry point
    Dockerfile Container image definition (only when infra is agentcore-ecr)
- pyproject.toml Updated with framework and AG-UI dependencies
- project.json Updated with agent serve targets

Infrastruttura

L’opzione infra seleziona come il tuo codice viene impacchettato e ospitato su Amazon Bedrock AgentCore Runtime:

agentcore (predefinito) utilizza il deployment diretto del codice: il tuo codice compilato viene impacchettato come un file .zip, caricato su S3 ed eseguito su un runtime del linguaggio gestito da AgentCore. Non c’è alcuna immagine container da costruire, nessun repository ECR da gestire e nessuna immagine da inviare, il che rende il ciclo di build e deploy sostanzialmente più veloce.
agentcore-ecr costruisce un’immagine container arm64 da un Dockerfile fornito e la ospita dal registro condiviso core/asset-ecr, insieme a tutti gli altri container nel workspace. Scegli questa opzione quando hai bisogno di controllare l’immagine del sistema operativo — ad esempio per installare librerie di sistema native — o quando hai una pipeline di container consolidata. Questa opzione fornisce inoltre un target di scansione immagini Trivy (vedi Image Scanning di seguito).
none non genera alcuna infrastruttura, quindi il progetto può essere eseguito solo localmente.

Poiché questo generatore fornisce infrastruttura come codice basata sul tuo iac scelto, creerà un progetto in packages/common che include i costrutti CDK o i moduli Terraform pertinenti.

Il progetto comune di infrastruttura come codice è strutturato come segue:

CDK
Terraform

Directorypackages/common/constructs
- Directorysrc
  - Directoryapp/ Constructs for infrastructure specific to a project/generator
    …
  - Directorycore/ Generic constructs which are reused by constructs in app
    …
  - index.ts Entry point exporting constructs from app
- project.json Project build targets and configuration

Directorypackages/common/terraform
- Directorysrc
  - Directoryapp/ Terraform modules for infrastructure specific to a project/generator
    …
  - Directorycore/ Generic modules which are reused by modules in app
    …
- project.json Project build targets and configuration

Per distribuire il tuo Agent, vengono generati i seguenti file:

CDK
Terraform

Directorypackages/common/constructs/src
- Directoryapp
  - Directoryagents
    Directory<agent-name>
    <agent-name>.ts CDK construct for deploying your agent

Directorypackages/common/terraform/src
- Directoryapp
  - Directoryagents
    Directory<agent-name>
    <agent-name>.tf Module for deploying your agent
- Directorycore
  - Directoryagent-core
    runtime.tf Generic module for deploying to Bedrock AgentCore Runtime
  - Directoryagent-core-code (when infra is agentcore)
    runtime.tf Packages your agent’s code and delegates to agent-core
  - Directoryagent-core-container (when infra is agentcore-ecr)
    runtime.tf Builds and publishes your agent’s image and delegates to agent-core

Se hai selezionato none per infra, non vengono generati costrutti CDK o moduli Terraform — l’Agent può essere eseguito solo localmente. L’opzione auth viene ignorata in questa modalità poiché non c’è un endpoint ospitato da autenticare.

Architettura

Quando viene distribuito su Bedrock AgentCore Runtime, il codice del tuo agent viene impacchettato come zip ed eseguito nel runtime gestito di AgentCore. I client invocano l’endpoint del data plane di AgentCore Runtime, che inoltra le richieste al tuo agent. L’agent chiama Amazon Bedrock per l’inferenza del modello e può invocare strumenti, server MCP o API downstream.

Loading the diagram…

Con infra: agentcore-ecr, l’agent viene compilato in un’immagine container, caricato su Amazon ECR ed eseguito in AgentCore Runtime. Questo ti dà il controllo a livello di sistema operativo sull’ambiente di runtime, al costo di un ciclo di build e deploy più lungo rispetto al packaging zip sopra descritto.

Loading the diagram…

Con infra: none, non viene generata alcuna infrastruttura AWS. L’agent viene eseguito come processo locale e chiama Amazon Bedrock per l’inferenza del modello.

Loading the diagram…

Lavorare con il Tuo Agent

Puoi modificare agent.py per aggiungere strumenti, configurare il modello e personalizzare il prompt di sistema. L’API dipende dal framework che hai scelto.

Aggiungere Strumenti

Gli strumenti sono funzioni che l’agente AI può chiamare per eseguire azioni. Entrambi i framework utilizzano un approccio basato su decoratori per definire gli strumenti, derivano il nome e la descrizione dello strumento dal nome della funzione e dalla docstring e generano lo schema di input dai tuoi type hint.

Definisci lo strumento, quindi aggiungilo alla lista tools all’interno di get_agent():

Strands
LangChain

from contextlib import contextmanager

from strands import Agent, tool
from strands.hooks import HookCallback, HookProvider
from strands_tools import current_time
from my_scope_agent_connection import log_model_errors, log_tool_errors

from .session import get_session_manager


@tool
def subtract(a: int, b: int) -> int:
    return a - b


@tool
def get_weather(city: str) -> str:
    """Get weather information for a city"""
    # Your weather API integration here
    return f"Weather in {city}: Sunny, 25°C"


AGENT_HOOKS: list[HookProvider | HookCallback] = [log_model_errors, log_tool_errors]


@contextmanager
def get_agent():
    yield Agent(
        name="MyAgent",
        description="MyAgent Strands Agent",
        system_prompt="You are a helpful assistant with access to various tools.",
        tools=[subtract, current_time, get_weather],
        hooks=AGENT_HOOKS,
        session_manager=get_session_manager(),
    )

import os

from langchain.agents import create_agent
from langchain_aws import ChatBedrockConverse
from langchain_core.tools import tool

from .session import get_checkpointer

REGION = os.environ.get("AWS_REGION", "us-east-1")
MODEL_ID = os.environ.get("MODEL_ID", "global.anthropic.claude-haiku-4-5-20251001-v1:0")


@tool
def subtract(a: int, b: int) -> int:
    """Subtract b from a."""
    return a - b


@tool
def get_weather(city: str) -> str:
    """Get weather information for a city"""
    # Your weather API integration here
    return f"Weather in {city}: Sunny, 25°C"


def get_agent():
    model = ChatBedrockConverse(model=MODEL_ID, region_name=REGION)
    return create_agent(
        model=model,
        tools=[subtract, get_weather],
        system_prompt="You are a helpful assistant with access to various tools.",
        checkpointer=get_checkpointer(),
    )

Strands fornisce una collezione di strumenti pre-costruiti tramite il pacchetto strands-agents-tools, che il generatore aggiunge già al pyproject.toml del tuo progetto. Importa gli strumenti che desideri e aggiungili a get_agent():

from strands_tools import current_time, file_read, http_request

# ...

@contextmanager
def get_agent():
    yield Agent(
        name="MyAgent",
        description="MyAgent Strands Agent",
        system_prompt="You are a helpful assistant.",
        tools=[current_time, file_read, http_request],
        hooks=AGENT_HOOKS,
        session_manager=get_session_manager(),
    )

LangChain fornisce un ampio ecosistema di strumenti e integrazioni, ciascuno distribuito nel proprio pacchetto. Il generatore non li aggiunge, quindi installa prima quello di cui hai bisogno — ad esempio langchain-community, da cui proviene lo strumento di ricerca qui sotto:

pnpm nx run <project-name>:add langchain-community

yarn nx run <project-name>:add langchain-community

npx nx run <project-name>:add langchain-community

bunx nx run <project-name>:add langchain-community

Quindi importa gli strumenti e aggiungili a get_agent():

from langchain_community.tools import DuckDuckGoSearchRun

# ...

def get_agent():
    model = ChatBedrockConverse(model=MODEL_ID, region_name=REGION)
    return create_agent(
        model=model,
        tools=[DuckDuckGoSearchRun()],
        system_prompt="You are a helpful assistant.",
        checkpointer=get_checkpointer(),
    )

Configurazione del Modello

Strands
LangChain

L’agente generato utilizza il modello Strands predefinito su Amazon Bedrock. Per configurarlo, passa un model all’Agent. Consulta la documentazione Strands sui provider di modelli per i provider disponibili e le loro opzioni:

from strands.models import BedrockModel

# ...

MODEL = BedrockModel(
    model_id="anthropic.claude-sonnet-4-20250514-v1:0",
    region_name="us-west-2",
    temperature=0.3,
)

@contextmanager
def get_agent():
    yield Agent(
        model=MODEL,
        name="MyAgent",
        description="MyAgent Strands Agent",
        system_prompt="You are a helpful assistant.",
        tools=[subtract, current_time],
        hooks=AGENT_HOOKS,
        session_manager=get_session_manager(),
    )

Gli agenti LangChain utilizzano un modello ChatBedrockConverse. L’agente generato legge l’id del modello e la regione dalle variabili d’ambiente MODEL_ID e AWS_REGION, che l’infrastruttura imposta per l’agente distribuito. Per configurare ulteriormente il modello, aggiungi argomenti dove viene costruito in get_agent():

# ...

def get_agent():
    model = ChatBedrockConverse(
        model=MODEL_ID,
        region_name=REGION,
        temperature=0.3,
    )
    return create_agent(
        model=model,
        tools=[subtract],
        system_prompt="You are a helpful assistant.",
        checkpointer=get_checkpointer(),
    )

Consumare Server MCP

Per consumare Server MCP che hai creato utilizzando i generatori py#mcp-server o ts#mcp-server puoi utilizzare il generatore connection, che collega gli strumenti del server MCP al tuo agente per entrambi i framework.

Esegui questo generatore@aws/nx-plugin:connection

CLI
VSCode

$ pnpm nx g @aws/nx-plugin:connection

$ yarn nx g @aws/nx-plugin:connection

$ npx nx g @aws/nx-plugin:connection

$ bunx nx g @aws/nx-plugin:connection

Installa il Nx Console VSCode Plugin se non l'hai già fatto
Apri la console Nx in VSCode
Clicca su Generate (UI) nella sezione "Common Nx Commands"
Cerca @aws/nx-plugin - connection
Compila i parametri richiesti
Clicca su Generate

Componi il tuo comando5

sourceProjectObbligatorio

targetProjectObbligatorio

sourceComponent

targetComponent

preferInstallDependencies

true

--dry-runPuoi anche eseguire una prova per vedere quali file verrebbero modificati

Fai riferimento alla guida del generatore connection per i dettagli su come viene configurata la connessione.

Per altri server MCP, fai riferimento alla documentazione MCP di Strands o LangChain.

Altro

Per una guida più approfondita sulla scrittura di agenti, fai riferimento alla documentazione di Strands o LangChain.

Protocollo

Il protocollo server del tuo agente determina come comunica. Tutte le opzioni sono servite da FastAPI — il punto di ingresso differisce:

HTTP (predefinito): Un server FastAPI standard con un endpoint /invocations personalizzato, CORS e streaming. Ideale per integrazioni client personalizzate.
A2A: Un server Agent-to-Agent montato su un’app FastAPI (Strands utilizza il Strands A2A Server; LangChain utilizza l’a2a-sdk framework-agnostic). Ideale quando il tuo agente deve essere individuabile e invocabile da altri agenti compatibili A2A.
AG-UI: Il protocollo AG-UI tramite SSE (Strands utilizza ag-ui-strands; LangChain utilizza ag-ui-langgraph). Ideale per l’integrazione diretta con il frontend tramite CopilotKit in un sito web React.

Il punto di ingresso del server differisce per framework (Strands produce un Agent gestito dal contesto, mentre LangChain guida un grafo create_agent compilato), ma il contratto esterno per ogni protocollo è lo stesso.

Tutti i protocolli espongono /ping per il contratto di controllo dello stato del runtime AgentCore. Gli agenti A2A ascoltano sulla porta 9000; gli agenti HTTP e AG-UI ascoltano sulla porta 8080. L’infrastruttura generata è configurata per te.

Server FastAPI (protocollo HTTP)

Il server HTTP generato include:

Configurazione dell’applicazione FastAPI con middleware CORS
Middleware per la gestione degli errori
Generazione dello schema OpenAPI
Endpoint di controllo dello stato (/ping)
Endpoint di invocazione dell’agente (/invocations)

Personalizzare Input e Output di Invoke con Pydantic

L’endpoint di invocazione dell’agente utilizza modelli Pydantic per definire e validare gli schemi di richiesta e risposta. Puoi personalizzare questi modelli in main.py per soddisfare i requisiti del tuo agente.

Definire Modelli di Input

Il modello InvokeInput predefinito accetta un prompt.

from pydantic import BaseModel, Field

class InvokeInput(BaseModel):
    prompt: str = Field(max_length=100000)

Puoi estendere questo modello per includere eventuali campi aggiuntivi di cui il tuo agente ha bisogno.

L’ID di sessione viene estratto dall’header HTTP x-amzn-bedrock-agentcore-runtime-session-id, coerente con il contratto di sessione di Bedrock AgentCore Runtime. Se l’header non viene fornito, viene generato un UUID casuale come fallback.

Definire Modelli di Output

Per le risposte in streaming, il generatore fornisce JsonStreamingResponse che serializza automaticamente i modelli Pydantic nel formato JSON Lines (application/jsonl). Questo formato è compatibile con la specifica di streaming di OpenAPI 3.2 e funziona perfettamente con il client TypeScript generato.

Per impostazione predefinita, l’agente produce oggetti StreamChunk contenenti il testo di risposta dell’agente:

class StreamChunk(BaseModel):
    content: str

Puoi personalizzare il modello StreamChunk per soddisfare le tue esigenze:

from pydantic import BaseModel

class StreamChunk(BaseModel):
    content: str
    timestamp: str
    token_count: int

Nota che poiché FastAPI attualmente non supporta la generazione di una specifica OpenAPI per le risposte in streaming, dobbiamo impostare esplicitamente il modello di risposta per ogni operazione di streaming, cioè:

@app.post(
    "/invocations",
    response_class=JsonStreamingResponse,
    responses={200: JsonStreamingResponse.openapi_response(StreamChunk)},
)
async def invoke(input: InvokeInput) -> JsonStreamingResponse:
    return JsonStreamingResponse(handle_invoke(input))

C’è una richiesta di funzionalità aperta per il supporto nativo in FastAPI.

Bedrock AgentCore Python SDK

Il generatore include una dipendenza dal Bedrock AgentCore Python SDK per le costanti PingStatus. Se lo desideri, è semplice utilizzare BedrockAgentCoreApp invece di FastAPI, tuttavia nota che la type-safety viene persa.

Puoi trovare maggiori dettagli sulle capacità dell’SDK nella documentazione qui.

Server A2A (protocollo A2A)

Il main.py generato monta un server A2A su un’app FastAPI padre che espone anche /ping. Gli agenti Strands utilizzano lo Strands A2AServer; gli agenti LangChain avvolgono il grafo compilato in un AgentExecutor a2a-sdk. L’URL pubblicizzato nella scheda dell’agente proviene dalla variabile d’ambiente AGENTCORE_RUNTIME_URL, con fallback a http://localhost:<port>/ per lo sviluppo locale.

La maggior parte degli utenti non avrà bisogno di modificare questo file; modifica agent.py per cambiare strumenti o il prompt di sistema. Il server A2A popola la scheda dell’agente (/.well-known/agent-card.json) dal name e dalla description dell’agente.

Server AG-UI (protocollo AG-UI)

Il main.py generato espone un singolo endpoint POST che trasmette eventi AG-UI tramite Server-Sent Events (SSE), oltre a /ping per il controllo dello stato del runtime AgentCore. Il cablaggio dipende dal framework:

Strands: avvolge il tuo Agent in un ag_ui_strands.StrandsAgent, costruito all’interno di un gestore lifespan di FastAPI (quindi la costruzione avviene all’avvio del contenitore/sessione piuttosto che al momento dell’importazione), e servito da un ciclo /invocations FastAPI scritto a mano.
LangChain: avvolge il grafo compilato in un ag_ui_langgraph.LangGraphAgent, costruito allo stesso modo all’interno di lifespan, e servito da un ciclo /invocations FastAPI scritto a mano.

La maggior parte degli utenti non avrà bisogno di modificare questo file — modifica agent.py per cambiare strumenti o il prompt di sistema.

Eseguire il Tuo Agent

Sviluppo Locale

Per eseguire il tuo Agent (e tutto ciò che è connesso ad esso) localmente, utilizza il target dev del progetto:

pnpm nx dev your-project

yarn nx dev your-project

npx nx dev your-project

bunx nx dev your-project

Se hai aggiunto più componenti al tuo progetto (agenti, server MCP, ecc.), questo li avvia tutti. Per eseguire solo questo agente, punta al suo target <your-agent-name>-dev:

pnpm nx agent-dev your-project

yarn nx agent-dev your-project

npx nx agent-dev your-project

bunx nx agent-dev your-project

Questo utilizza uv run per eseguire il tuo Agent utilizzando il Bedrock AgentCore Python SDK.

L’agente ascolta su una porta assegnata dal pool del workspace quando è stato generato. Leggila da metadata.ports nel project.json del progetto, o dal flag --port nel comando del target <your-agent-name>-dev. Gli esempi seguenti utilizzano 8081, la porta assegnata a un primo agente HTTP in un workspace nuovo.

Viene anche generato un target <your-agent-name>-serve, che esegue l’agente contro la tua infrastruttura distribuita e quindi richiede che RUNTIME_CONFIG_APP_ID sia impostato. Consulta la guida Sviluppo Locale per la differenza tra dev e serve.

Chattare con il Tuo Agent

Il generatore configura un target Nx <your-agent-name>-chat che ti porta in una chat interattiva da terminale con il tuo agente.

Il target chat funziona in modo autonomo. Per impostazione predefinita si connette al tuo agente in esecuzione localmente, quindi avvia prima il target <your-agent-name>-dev dell’agente (in un terminale separato):

pnpm nx agent-dev your-project

yarn nx agent-dev your-project

npx nx agent-dev your-project

bunx nx agent-dev your-project

Quindi, in un altro terminale, avvia la chat:

pnpm nx run your-project:agent-chat

yarn nx run your-project:agent-chat

npx nx run your-project:agent-chat

bunx nx run your-project:agent-chat

Il generatore emette uno scripts/<your-agent-name>/chat.ts per ogni protocollo. Si connette all’agente locale per impostazione predefinita, o al tuo agente distribuito quando RUNTIME_CONFIG_APP_ID è impostato (vedi Chattare con il tuo agente distribuito di seguito).

Per gli agenti HTTP, lo script di chat utilizza un client TypeScript type-safe generato dalla specifica OpenAPI dell’agente. Il generatore emette anche:

scripts/<your_agent_name>_openapi.py — un piccolo script che esporta la specifica OpenAPI dell’agente (nominato con il nome del tuo agente in snake_case)
Un target Nx <your-agent-name>-openapi che lo esegue
Un target Nx <your-agent-name>-generate-client che produce un client TypeScript type-safe sotto scripts/<your-agent-name>/generated/

Quando personalizzi la forma di input dell’agente (ad es. aggiungi nuovi campi a InvokeInput), aggiorna chat.ts per passare i nuovi campi quando invochi l’agente e il resto funziona automaticamente.

Chattare con il tuo agente distribuito

Per chattare con il tuo agente distribuito su Bedrock AgentCore, imposta la variabile d’ambiente RUNTIME_CONFIG_APP_ID sull’id dell’applicazione AppConfig della distribuzione (output come RuntimeConfigApplicationId dallo stack distribuito). Lo script di chat risolve l’ARN del runtime del tuo agente dalla configurazione del runtime e si connette all’endpoint distribuito:

IAM
Cognito

Per gli agenti autenticati con IAM, le richieste sono firmate con SigV4 utilizzando le tue credenziali AWS predefinite. Assicurati che l’ambiente abbia credenziali AWS con il permesso di invocare il runtime:

RUNTIME_CONFIG_APP_ID=<app-id> pnpm nx run your-project:agent-chat

RUNTIME_CONFIG_APP_ID=<app-id> yarn nx run your-project:agent-chat

RUNTIME_CONFIG_APP_ID=<app-id> npx nx run your-project:agent-chat

RUNTIME_CONFIG_APP_ID=<app-id> bunx nx run your-project:agent-chat

Per gli agenti autenticati con Cognito, fornisci un token di accesso Cognito tramite la variabile d’ambiente AGENT_ACCESS_TOKEN, che viene inviato come bearer token:

RUNTIME_CONFIG_APP_ID=<app-id> AGENT_ACCESS_TOKEN=<access-token> pnpm nx run your-project:agent-chat

RUNTIME_CONFIG_APP_ID=<app-id> AGENT_ACCESS_TOKEN=<access-token> yarn nx run your-project:agent-chat

RUNTIME_CONFIG_APP_ID=<app-id> AGENT_ACCESS_TOKEN=<access-token> npx nx run your-project:agent-chat

RUNTIME_CONFIG_APP_ID=<app-id> AGENT_ACCESS_TOKEN=<access-token> bunx nx run your-project:agent-chat

Puoi ottenere un token di accesso utilizzando il comando cognito-idp admin-initiate-auth dell’AWS CLI, ad esempio:

aws cognito-idp admin-initiate-auth \
  --user-pool-id <user-pool-id> \
  --client-id <user-pool-client-id> \
  --auth-flow ADMIN_NO_SRP_AUTH \
  --auth-parameters USERNAME=<username>,PASSWORD=<password> \
  --query 'AuthenticationResult.AccessToken' \
  --output text

Distribuire il Tuo Agent su Bedrock AgentCore Runtime

Infrastructure as Code

Se hai selezionato agentcore o agentcore-ecr per infra, viene generata l’infrastruttura CDK o Terraform rilevante che puoi utilizzare per distribuire il tuo Agent su Amazon Bedrock AgentCore Runtime.

CDK
Terraform

Viene generato un costrutto CDK per il tuo agent, denominato in base al name che hai scelto quando hai eseguito il generatore, o <ProjectName>Agent per impostazione predefinita.

Puoi utilizzare questo costrutto CDK in un’applicazione CDK:

import { MyProjectAgent } from '@my-scope/common-constructs';

export class ExampleStack extends Stack {
  constructor(scope: Construct, id: string) {
    new MyProjectAgent(this, 'MyProjectAgent');
  }
}

Viene generato un modulo Terraform per te, denominato in base al name che hai scelto quando hai eseguito il generatore, o <ProjectName>-agent per impostazione predefinita.

Passa gli output del modulo condiviso runtime_config_appconfig nel modulo agent, insieme all’archivio di artefatti condiviso utilizzato dal suo packaging. Con il packaging predefinito agentcore, il codice dell’agent viene messo in staging nel bucket di asset condiviso, quindi istanzia il modulo core/asset-bucket una volta per deployment, come fanno già i moduli Lambda e API:

module "asset_bucket" {
  source = "../../common/terraform/src/core/asset-bucket"
}

module "my_project_agent" {
  source = "../../common/terraform/src/app/agents/my-project-agent"

  appconfig_application_id  = module.runtime_config_appconfig.application_id
  appconfig_application_arn = module.runtime_config_appconfig.application_arn

  asset_bucket_name = module.asset_bucket.bucket_name
  asset_bucket_arn  = module.asset_bucket.bucket_arn
}

Con agentcore-ecr l’immagine dell’agent viene invece pubblicata nel registro di asset condiviso, quindi passa gli output di core/asset-ecr invece di quelli del bucket. Un registro serve tutti i container nel workspace, quindi nessun agent ha bisogno di un proprio repository:

module "asset_ecr" {
  source = "../../common/terraform/src/core/asset-ecr"
}

module "my_project_agent" {
  source = "../../common/terraform/src/app/agents/my-project-agent"

  appconfig_application_id  = module.runtime_config_appconfig.application_id
  appconfig_application_arn = module.runtime_config_appconfig.application_arn

  asset_ecr_repository_url = module.asset_ecr.repository_url
  asset_ecr_repository_arn = module.asset_ecr.repository_arn
}

Autenticazione

Il generatore fornisce un’opzione auth per configurare l’autenticazione per il tuo Agent. Puoi scegliere tra autenticazione IAM (predefinita) o Cognito quando generi il tuo agent.

IAM

Per impostazione predefinita, il tuo Agent sarà protetto utilizzando l’autenticazione IAM, semplicemente distribuiscilo senza argomenti:

CDK
Terraform

import { MyProjectAgent } from '@my-scope/common-constructs';

export class ExampleStack extends Stack {
  constructor(scope: Construct, id: string) {
    new MyProjectAgent(this, 'MyProjectAgent');
  }
}

Puoi concedere l’accesso per invocare il tuo agent su Bedrock AgentCore Runtime utilizzando il metodo grantInvokeAccess, per esempio:

import { MyProjectAgent } from '@my-scope/common-constructs';

export class ExampleStack extends Stack {
  constructor(scope: Construct, id: string) {
    const agent = new MyProjectAgent(this, 'MyProjectAgent');
    const lambdaFunction = new Function(this, ...);

    agent.grantInvokeAccess(lambdaFunction);
  }
}

module "asset_bucket" {
  source = "../../common/terraform/src/core/asset-bucket"
}

# Agent
module "my_project_agent" {
  # Relative path to the generated module in the common/terraform project
  source = "../../common/terraform/src/app/agents/my-project-agent"

  appconfig_application_id  = module.runtime_config_appconfig.application_id
  appconfig_application_arn = module.runtime_config_appconfig.application_arn

  # Under `agentcore-ecr`, pass `core/asset-ecr`'s outputs instead.
  asset_bucket_name = module.asset_bucket.bucket_name
  asset_bucket_arn  = module.asset_bucket.bucket_arn
}

Per concedere l’accesso per invocare il tuo agent, dovrai aggiungere una policy come la seguente, facendo riferimento all’output module.my_project_agent.agent_core_runtime_arn:

{
  Effect = "Allow"
  Action = [
    "bedrock-agentcore:InvokeAgentRuntime"
  ]
  Resource = [
    module.my_project_agent.agent_core_runtime_arn,
    "${module.my_project_agent.agent_core_runtime_arn}/*"
  ]
}

Autenticazione Cognito

Quando selezioni l’autenticazione Cognito, il generatore configura l’agent per utilizzare Cognito per l’autenticazione.

CDK
Terraform

Il costrutto generato accetta una prop identity che configura l’autenticazione Cognito:

import { MyProjectAgent, UserIdentity } from '@my-scope/common-constructs';

export class ExampleStack extends Stack {
  constructor(scope: Construct, id: string) {
    const identity = new UserIdentity(this, 'Identity');

    new MyProjectAgent(this, 'MyProjectAgent', {
      identity,
    });
  }
}

Il costrutto UserIdentity può essere generato utilizzando il generatore ts#website#auth, oppure puoi creare il tuo UserPool e UserPoolClient CDK.

Il modulo generato accetta le variabili user_pool_id e user_pool_client_ids per l’autenticazione Cognito:

module "user_identity" {
  source = "../../common/terraform/src/core/user-identity"
}

module "my_project_agent" {
  source = "../../common/terraform/src/app/agents/my-project-agent"

  appconfig_application_id  = module.runtime_config_appconfig.application_id
  appconfig_application_arn = module.runtime_config_appconfig.application_arn

  user_pool_id         = module.user_identity.user_pool_id
  user_pool_client_ids = [module.user_identity.user_pool_client_id]
}

Target Bundle e Docker

Per costruire il tuo Agent per Bedrock AgentCore Runtime, viene aggiunto un target bundle al tuo progetto, che:

Esporta le tue dipendenze Python in un file requirements.txt utilizzando uv export
Installa le dipendenze per la piattaforma di destinazione (aarch64-manylinux_2_28) utilizzando uv pip install

Viene anche aggiunto un target <your-agent-name>-package, che assembla il pacchetto di codice distribuibile: il bundle di dipendenze aarch64, l’albero dei moduli Python e un punto di ingresso main.py radice. L’infrastruttura generata carica questa directory come .zip — tramite AgentRuntimeArtifact.fromCodeAsset sotto CDK, o archiviata nel bucket di asset condiviso sotto Terraform.

Viene anche aggiunto un target docker specifico per il tuo Agent, che copia il Dockerfile e gli artefatti raggruppati in una directory di contesto docker. Questo co-localizza il Dockerfile con l’output costruito, consentendo a CDK di costruire l’immagine Docker direttamente utilizzando AgentRuntimeArtifact.fromAsset.

Scansione delle Immagini

L’immagine Docker costruita per questo progetto può essere scansionata per vulnerabilità utilizzando Trivy, eseguito dall’immagine Trivy ospitata su ECR.

Un target trivy viene aggiunto al tuo progetto che scansiona l’immagine costruita ed esce con codice diverso da zero se viene trovata qualsiasi vulnerabilità di gravità HIGH o CRITICAL. Il Dockerfile generato utilizza un’immagine base senza vulnerabilità risolvibili note di queste gravità al momento della generazione, e aggiorna gli strumenti inclusi (come npm) per mantenerla tale.

La scansione utilizza lo stesso motore container della tua build dell’immagine (docker o finch), quindi non sono richiesti strumenti aggiuntivi. La scansione non è memorizzata in cache, poiché l’immagine che legge risiede nel motore container anziché su disco — quindi scansiona sempre l’immagine reale e fallisce in modo evidente anziché riportare un successo memorizzato in cache per un’immagine che non è più presente. Ogni esecuzione richiede quindi decine di secondi per immagine e aggiorna il database delle vulnerabilità di Trivy, quindi necessita di accesso alla rete. Lo script root trivy fornito scansiona ogni immagine nel workspace:

pnpm trivy

yarn trivy

npm run trivy

bun trivy

Soppressione dei Risultati di Trivy

Potrebbero esserci casi in cui desideri sopprimere una vulnerabilità specifica, ad esempio quando non è ancora disponibile una correzione e hai valutato il rischio come accettabile.

Aggiungi l’ID della vulnerabilità (uno per riga) al file .trivyignore nella root del tuo progetto (cioè accanto al tuo project.json):

# node-tar arbitrary file write - not exploitable in our usage
CVE-2024-XXXXX

Per maggiori dettagli sul filtraggio dei risultati, consulta la documentazione sul filtraggio di Trivy.

Osservabilità

Il tuo agente è automaticamente configurato con l’osservabilità utilizzando l’AWS Distro for Open Telemetry (ADOT).

Puoi trovare le tracce nella Console AWS CloudWatch, selezionando “GenAI Observability” nel menu. Nota che affinché le tracce vengano popolate dovrai abilitare Transaction Search.

Per maggiori dettagli, fai riferimento alla documentazione AgentCore sull’osservabilità.

Gestione delle Sessioni

L’opzione session si associa a un diverso concetto di persistenza sottostante a seconda del framework scelto: il concetto di gestione delle sessioni di Strands per il framework strands, o il concetto di checkpointer di LangGraph per il framework langchain.

L’opzione session controlla come il tuo agente persiste lo stato della conversazione (cronologia dei messaggi, stato degli strumenti, ecc.) tra le invocazioni, utilizzando il SessionManager dell’SDK Strands:

s3 (predefinito): L’infrastruttura CDK/Terraform fornisce un bucket S3 dedicato per i dati di sessione, crittografato con una chiave KMS dedicata e con tutto l’accesso pubblico bloccato; i log di accesso al server vengono consegnati a un gruppo di log CloudWatch Logs tramite la stessa chiave. Il ruolo IAM dell’agente riceve l’accesso in lettura/scrittura/elenco/eliminazione al bucket e l’accesso decrypt/generate-data-key alla chiave, e il nome del bucket viene registrato insieme all’ARN dell’agente nella configurazione del runtime AppConfig.
in-memory: Nessun bucket viene fornito. Lo stato della conversazione viene mantenuto in memoria solo per la durata del processo in esecuzione e non sopravvive ai riavvii o allo scale-in.

Questo è implementato nel session.py generato, che esporta una funzione get_session_manager() che risolve un SessionManager per la sessione corrente.

L’ID di sessione stesso proviene dalla sessione AgentCore Runtime (propagata tramite l’header x-amzn-bedrock-agentcore-runtime-session-id) ed è legato a un contesto basato su contextvars.ContextVar in modo che get_current_session_id() possa risolverlo ovunque nella richiesta — incluso in qualsiasi client MCP o A2A downstream collegato tramite il generatore connection, in modo che l’intera catena di chiamate condivida una sessione coerente.

Limitare le sessioni al loro proprietario

L’ID di sessione arriva dal chiamante, quindi da solo identifica una conversazione ma non a chi appartiene la conversazione. AgentCore Runtime autorizza un’invocazione contro l’ARN della risorsa runtime dell’agente piuttosto che contro una singola sessione, il che lascia l’agente libero di decidere cosa significa una sessione per la tua applicazione.

Per limitare ogni utente alle proprie conversazioni:

Aggiungi un’API per creare una sessione, utilizzando tRPC, FastAPI o Smithy. Genera un ID di sessione opaco (almeno 33 caratteri) e memorizzalo insieme all’ID dell’utente chiamante — ad esempio in una tabella creata con il generatore py#dynamodb. Ogni guida API mostra come recuperare l’ID dell’utente chiamante.
Nel tuo agente, cerca l’ID utente memorizzato per l’ID di sessione che gli è stato fornito e rifiuta la richiesta quando non corrisponde al chiamante. Con auth=cognito il JWT del chiamante raggiunge il codice del tuo agente, quindi il suo claim sub li identifica.

Genera l’ID di sessione piuttosto che derivarlo da valori forniti dall’utente come un nome di conversazione — qualsiasi cosa un chiamante possa prevedere, un chiamante può inviare.

L’opzione session controlla come il checkpointer LangGraph del tuo agente persiste lo stato della conversazione:

s3 (predefinito): L’agente distribuito utilizza un S3CheckpointSaver con il bucket di sessione fornito, memorizzando checkpoint e scritture in sospeso sotto il prefisso checkpoints/. Questa classe si trova in s3_checkpoint_saver_langchain.py nel progetto di connessione agente condiviso.
dynamodb-s3: L’infrastruttura CDK/Terraform fornisce una tabella DynamoDB per i checkpoint, configurata come raccomandato nella documentazione AWS sull’utilizzo di DynamoDB come archivio di checkpoint per gli agenti LangGraph (schema unificato PK/SK, fatturazione PAY_PER_REQUEST, ripristino point-in-time e un attributo ttl), più un bucket S3 per l’offload di checkpoint superiori a 350KB. Entrambi sono crittografati con una chiave KMS dedicata; i log di accesso al server del bucket vengono consegnati a un gruppo di log CloudWatch Logs tramite la stessa chiave. Il ruolo IAM dell’agente riceve l’accesso in lettura/scrittura alla tabella e al bucket, e i nomi della tabella/bucket vengono registrati insieme all’ARN dell’agente nella configurazione del runtime AppConfig.
in-memory: Nessuna tabella o bucket viene fornito. Lo stato della conversazione viene mantenuto in memoria solo per la durata del processo in esecuzione e non sopravvive ai riavvii o allo scale-in.

Questo è implementato nel session.py generato, che esporta una funzione get_checkpointer() chiamata dalla chiamata create_agent(..., checkpointer=get_checkpointer()) di agent.py.

Invocare il Tuo Agent

Invocare il Server Locale

Avvia il tuo agente con il target <your-agent-name>-dev:

pnpm nx agent-dev your-project

yarn nx agent-dev your-project

npx nx agent-dev your-project

bunx nx agent-dev your-project

Quindi invia una richiesta POST a /invocations sulla porta su cui è in esecuzione il tuo agente locale. Sostituisci la porta assegnata al tuo agente — leggila da metadata.ports nel project.json del progetto, o dal flag --port nel comando del target <your-agent-name>-dev. Un primo agente HTTP in un workspace nuovo è assegnato a 8081:

curl -N -X POST http://localhost:8081/invocations \
  -d '{"prompt": "what is 3 + 5?"}' \
  -H "Content-Type: application/json"

Invocare l’Agent Distribuito

Per invocare il tuo Agent distribuito su Bedrock AgentCore Runtime, puoi inviare una richiesta POST all’endpoint del dataplane di Bedrock AgentCore Runtime con il tuo ARN codificato in URL.

Puoi ottenere l’ARN del runtime dalla tua infrastruttura come segue:

CDK
Terraform

import { CfnOutput } from 'aws-cdk-lib';
import { MyProjectAgent } from '@my-scope/common-constructs';

export class ExampleStack extends Stack {
  constructor(scope: Construct, id: string) {
    const agent = new MyProjectAgent(this, 'MyProjectAgent');

    new CfnOutput(this, 'AgentArn', {
      value: agent.agentCoreRuntime.agentRuntimeArn,
    });
  }
}

# Agent
module "my_project_agent" {
  # Relative path to the generated module in the common/terraform project
  source = "../../common/terraform/src/app/agents/my-project-agent"

  appconfig_application_id  = module.runtime_config_appconfig.application_id
  appconfig_application_arn = module.runtime_config_appconfig.application_arn
}

output "agent_arn" {
  value = module.my_project_agent.agent_core_runtime_arn
}

L’ARN avrà il seguente formato: arn:aws:bedrock-agentcore:<region>:<account>:runtime/<agent-runtime-id>.

Puoi quindi codificare l’ARN in URL sostituendo : con %3A e / con %2F.

Questo è semplice in una console del browser o in un REPL di Node utilizzando il metodo integrato encodeURIComponent:

encodeURIComponent('arn:aws:bedrock-agentcore:<region>:<account>:runtime/<agent-runtime-id>')

L’URL del dataplane di Bedrock AgentCore Runtime per invocare l’agent è il seguente:

https://bedrock-agentcore.<region>.amazonaws.com/runtimes/<url-encoded-arn>/invocations

La tua infrastruttura può anche restituire direttamente l’URL di invocazione completo, con la codifica dell’ARN gestita per te:

CDK
Terraform

new CfnOutput(this, 'AgentUrl', {
  value: agent.invocationUrl,
});

output "agent_url" {
  value = module.my_project_agent.invocation_url
}

Il modo esatto per invocare questo URL dipende dal metodo di autenticazione utilizzato.

IAM
Cognito

Autenticazione IAM

Per l’autenticazione IAM, la richiesta deve essere firmata utilizzando AWS Signature Version 4 (SigV4).

acurl <region> bedrock-agentcore -N -X POST \
'https://bedrock-agentcore.<region>.amazonaws.com/runtimes/<url-encoded-arn>/invocations' \
-d '{"prompt": "what is 3 + 5?"}' \
-H 'Content-Type: application/json'

Click here for more details on configuring the above acurl command

Autenticazione JWT / Cognito

Per l’autenticazione Cognito, passa il Token di Accesso Cognito nell’header Authorization:

curl -N -X POST 'https://bedrock-agentcore.<region>.amazonaws.com/runtimes/<url-encoded-arn>/invocations' \
  -d '{"prompt": "what is 3 + 5?"}' \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <access-token>"

Puoi ottenere il token di accesso utilizzando il comando cognito-idp admin-initiate-auth dell’AWS CLI, ad esempio:

aws cognito-idp admin-initiate-auth \
  --user-pool-id <user-pool-id> \
  --client-id <user-pool-client-id> \
  --auth-flow ADMIN_NO_SRP_AUTH \
  --auth-parameters USERNAME=<username>,PASSWORD=<password> \
  --region <region> \
  --query 'AuthenticationResult.AccessToken' \
  --output text

Browser / Sito Web React

Per invocare il tuo Agent da un sito web React, puoi utilizzare il generatore connection, che configura automaticamente un client con l’autenticazione corretta (IAM o Cognito).

Esegui questo generatore@aws/nx-plugin:connection

CLI
VSCode

$ pnpm nx g @aws/nx-plugin:connection

$ yarn nx g @aws/nx-plugin:connection

$ npx nx g @aws/nx-plugin:connection

$ bunx nx g @aws/nx-plugin:connection

Installa il Nx Console VSCode Plugin se non l'hai già fatto
Apri la console Nx in VSCode
Clicca su Generate (UI) nella sezione "Common Nx Commands"
Cerca @aws/nx-plugin - connection
Compila i parametri richiesti
Clicca su Generate

Componi il tuo comando5

sourceProjectObbligatorio

targetProjectObbligatorio

sourceComponent

targetComponent

preferInstallDependencies

true

--dry-runPuoi anche eseguire una prova per vedere quali file verrebbero modificati

Fai riferimento alla guida del generatore connection per i dettagli su come viene configurata la connessione.

Invocare un Agent A2A come Strumento

Per delegare il lavoro da questo agente a un agente A2A remoto (sia TypeScript che Python), utilizza il generatore connection. Fornisce un client autenticato con SigV4 per l’agente di destinazione e trasforma tramite AST l’agent.py di questo agente per registrare l’agente A2A remoto come delegato decorato con @tool.

Esegui questo generatore@aws/nx-plugin:connection

CLI
VSCode

$ pnpm nx g @aws/nx-plugin:connection

$ yarn nx g @aws/nx-plugin:connection

$ npx nx g @aws/nx-plugin:connection

$ bunx nx g @aws/nx-plugin:connection

Installa il Nx Console VSCode Plugin se non l'hai già fatto
Apri la console Nx in VSCode
Clicca su Generate (UI) nella sezione "Common Nx Commands"
Cerca @aws/nx-plugin - connection
Compila i parametri richiesti
Clicca su Generate

Componi il tuo comando5

sourceProjectObbligatorio

targetProjectObbligatorio

sourceComponent

targetComponent

preferInstallDependencies

true

--dry-runPuoi anche eseguire una prova per vedere quali file verrebbero modificati

Fai riferimento alla guida del generatore connection per i dettagli su come viene configurata la connessione.

Invocare un Agent AG-UI

Per invocare il tuo agente AG-UI da un sito web React, utilizza il generatore connection, che collega un client CopilotKit configurato per il tuo agente distribuito con l’autenticazione corretta (IAM o Cognito).

Esegui questo generatore@aws/nx-plugin:connection

CLI
VSCode

$ pnpm nx g @aws/nx-plugin:connection

$ yarn nx g @aws/nx-plugin:connection

$ npx nx g @aws/nx-plugin:connection

$ bunx nx g @aws/nx-plugin:connection

Installa il Nx Console VSCode Plugin se non l'hai già fatto
Apri la console Nx in VSCode
Clicca su Generate (UI) nella sezione "Common Nx Commands"
Cerca @aws/nx-plugin - connection
Compila i parametri richiesti
Clicca su Generate

Componi il tuo comando5

sourceProjectObbligatorio

targetProjectObbligatorio

sourceComponent

targetComponent

preferInstallDependencies

true

--dry-runPuoi anche eseguire una prova per vedere quali file verrebbero modificati

Fai riferimento alla guida del generatore connection per i dettagli su come viene configurata la connessione.

Proteggere il Tuo Agent

Gli agent agiscono su input non attendibili e possono eseguire azioni reali attraverso i loro strumenti, quindi vale la pena considerare la sicurezza fin dall’inizio. Le seguenti pratiche si applicano all’agent generato.

Trattare input e output del modello come non attendibili

I prompt possono contenere istruzioni avversarie (prompt injection), e l’output del modello è non deterministico — nessuno dei due dovrebbe essere considerato attendibile nella logica sensibile alla sicurezza:

Definisci schemi di input rigorosi per i tuoi strumenti, come nell’esempio di strumento generato. Vincola i valori a ciò di cui lo strumento ha effettivamente bisogno (enum, limiti di lunghezza, intervalli numerici) piuttosto che accettare stringhe in formato libero.
Non passare mai l’output del modello direttamente in comandi shell, query SQL, valutazione di codice o HTML renderizzato senza validazione o codifica.
Applica controlli di autorizzazione nei tuoi strumenti e servizi downstream — non fare affidamento sul prompt di sistema per impedire al modello di utilizzare in modo improprio uno strumento a cui ha accesso.

Le guide Prompt Engineering e Responsible AI di Strands coprono la scrittura di prompt di sistema robusti e attenti alla sicurezza.

Limitare rigorosamente i permessi degli strumenti

Concedi al ruolo IAM dell’agent solo i permessi di cui i suoi strumenti hanno bisogno. I costrutti CDK e i moduli Terraform forniti espongono metodi grant* e policy con ambito limitato per questo scopo — ad esempio concedendo a un agent l’accesso per invocare un’API specifica piuttosto che allegare policy gestite ampie. Quando uno strumento agisce per conto di un utente, preferisci autorizzare l’azione utilizzando l’identità dell’utente chiamante (passata attraverso il contesto della richiesta) rispetto ai permessi ambientali dell’agent stesso.

Fornire un kill switch

Poiché il comportamento del modello può cambiare in modi inaspettati, pianifica la possibilità di disabilitare o sostituire rapidamente il modello senza una modifica del codice:

Leggi l’ID del modello dalla configurazione (ad esempio una variabile d’ambiente MODEL_ID) in modo che gli operatori possano cambiare o ripristinare un modello diverso aggiornando la configurazione.
Proteggi l’agent dietro un feature flag in modo che la sua funzionalità AI possa essere disabilitata completamente. Quando disabilitato, restituisci un messaggio generico piuttosto che un errore, e assicurati che il resto della tua applicazione si degradi in modo elegante.

Documenta come attivare questi controlli nel tuo runbook operativo.

Proteggere i dati sensibili

Evita di registrare prompt e completamenti, che potrebbero contenere dati utente. L’hook di logging degli errori del modello dell’agent generato registra solo i metadati degli errori, non il contenuto della conversazione — mantieni questa proprietà quando aggiungi il tuo logging.
Restituisci messaggi di errore generici agli utenti; registra gli errori dettagliati lato server.
Isola lo stato della conversazione tra utenti e sessioni, e autorizza l’accesso a qualsiasi dato di sessione persistito.
Redigi le informazioni personalmente identificabili (PII) da prompt e output — sia con un filtro per informazioni sensibili di Bedrock Guardrail (sotto) o, per gli agent Strands, gli approcci nella guida PII Redaction.

Amazon Bedrock Guardrails

Amazon Bedrock Guardrails forniscono filtri di contenuto configurabili, argomenti negati e filtri per informazioni sensibili (PII) che vengono valutati sull’input e output del modello. Puoi allegare un guardrail al modello utilizzato dall’agent generato:

Strands
LangChain

import os

from strands import Agent
from strands.models import BedrockModel

model = BedrockModel(
    model_id=os.environ.get("MODEL_ID"),
    guardrail_id=os.environ["GUARDRAIL_ID"],
    guardrail_version=os.environ.get("GUARDRAIL_VERSION", "DRAFT"),
)

agent = Agent(model=model)

Consulta la guida Strands sui Guardrails per maggiori dettagli.

import os

from langchain_aws import ChatBedrockConverse

model = ChatBedrockConverse(
    model=os.environ.get("MODEL_ID"),
    guardrail_config={
        "guardrailIdentifier": os.environ["GUARDRAIL_ID"],
        "guardrailVersion": os.environ.get("GUARDRAIL_VERSION", "DRAFT"),
    },
)

Consulta la documentazione di ChatBedrockConverse per i campi guardrail_config.

Connessioni

Utilizza il generatore connection per integrare questo progetto con altri nel tuo workspace. Le seguenti connessioni coinvolgono questo progetto:

React to Python AgentCall a Python Agent from a React website

React to AG-UI AgentCall an Agent exposing the AG-UI protocol from a React website via CopilotKit

Python Agent to MCPConnect a Python Agent to an MCP server

Python Agent to A2A AgentConnect a Python Agent to a remote A2A agent

TypeScript Agent to A2A AgentConnect a TypeScript Agent to a remote A2A agent

Python Agent to Python DynamoDBConnect a Python Agent to a DynamoDB table

Python Agent to AgentCore GatewayConnect a Python Agent to an AgentCore Gateway

AgentCore Gateway to AgentFront an agent with an AgentCore Gateway as a runtime target