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:

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

Puoi anche eseguire una prova per vedere quali file verrebbero modificati

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

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

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

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

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

Opzioni

Parametro	Tipo	Predefinito	Descrizione
project Obbligatorio	string	-	Il progetto a cui aggiungere lo Agent
framework	strands \| langchain	strands	L'SDK dell'agente da utilizzare.
name	string	-	Il nome del tuo Agent (predefinito: agent)
auth	iam \| cognito	iam	Il metodo utilizzato per autenticare con il tuo Agent. Applicabile solo quando infra è impostato (ignorato quando infra è none).
protocol	http \| a2a \| ag-ui	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.
iac	inherit \| cdk \| terraform	inherit	Il provider IaC preferito. Per impostazione predefinita viene ereditato dalla selezione iniziale.
infra	agentcore \| none	agentcore	Il tipo di infrastruttura per ospitare il tuo Agent.
session	s3 \| dynamodb-s3 \| in-memory	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.
preferInstallDependencies	boolean	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
    main.py FastAPI entry point for Bedrock AgentCore Runtime
    Dockerfile Entry point for hosting your agent (excluded when infra is set to None)
- 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
    main.py A2A server entry point
    Dockerfile Entry point for hosting your agent (excluded when infra is set to None)
- 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
    main.py AG-UI server entry point
    Dockerfile Entry point for hosting your agent (excluded when infra is set to None)
- pyproject.toml Updated with framework and AG-UI dependencies
- project.json Updated with agent serve targets

Infrastruttura

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<project-name>
    <project-name>.ts CDK construct for deploying your agent

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.

Quando viene distribuito su Bedrock AgentCore Runtime, l’agent viene compilato in un’immagine container, caricato su Amazon ECR ed eseguito in AgentCore Runtime. 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.

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.

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.

Strands
LangChain

from strands import Agent, tool

@tool
def calculate_sum(numbers: list[int]) -> int:
    """Calculate the sum of a list of numbers"""
    return sum(numbers)

@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"

# Add tools to your agent
agent = Agent(
    system_prompt="You are a helpful assistant with access to various tools.",
    tools=[calculate_sum, get_weather],
)

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

@tool
def calculate_sum(numbers: list[int]) -> int:
    """Calculate the sum of a list of numbers"""
    return sum(numbers)

@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"

# Add tools to your agent
agent = create_agent(
    model=ChatBedrockConverse(model=MODEL_ID, region_name=REGION),
    tools=[calculate_sum, get_weather],
    system_prompt="You are a helpful assistant with access to various tools.",
)

Utilizzare Strumenti Pre-costruiti

Strands
LangChain

Strands fornisce una collezione di strumenti pre-costruiti tramite il pacchetto strands-tools:

from strands_tools import current_time, http_request, file_read

agent = Agent(
    system_prompt="You are a helpful assistant.",
    tools=[current_time, http_request, file_read],
)

LangChain fornisce un ampio ecosistema di strumenti e integrazioni. Installa il pacchetto di integrazione pertinente, quindi passa gli strumenti a create_agent:

from langchain_community.tools import DuckDuckGoSearchRun

agent = create_agent(
    model=ChatBedrockConverse(model=MODEL_ID, region_name=REGION),
    tools=[DuckDuckGoSearchRun()],
    system_prompt="You are a helpful assistant.",
)

Configurazione del Modello

Strands
LangChain

Per impostazione predefinita, gli agenti Strands utilizzano Claude 4 Sonnet, ma puoi personalizzare il provider del modello. Consulta la documentazione Strands sui provider di modelli per le opzioni di configurazione:

from strands import Agent
from strands.models import BedrockModel

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

agent = Agent(model=bedrock_model)

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, ma puoi configurare il modello direttamente in agent.py:

from langchain_aws import ChatBedrockConverse

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

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.

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

Puoi anche eseguire una prova per vedere quali file verrebbero modificati

pnpm nx g @aws/nx-plugin:connection --dry-run

yarn nx g @aws/nx-plugin:connection --dry-run

npx nx g @aws/nx-plugin:connection --dry-run

bunx nx g @aws/nx-plugin:connection --dry-run

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

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. Il Dockerfile e l’infrastruttura generati sono configurati 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

class InvokeInput(BaseModel):
    prompt: str

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. Quando distribuito su AgentCore, il punto di ingresso risolve l’ARN pubblico del runtime da AppConfig e lo pubblicizza nella scheda dell’agente.

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.

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

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
}

Docker è richiesto per compilare e distribuire il tuo Agent. Assicurati di aver installato e avviato Docker per evitare errori come:

ERROR: Cannot connect to the Docker daemon at unix://path/to/docker.sock.

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);
  }
}

# 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
}

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 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. Poiché la scansione viene rieseguita solo quando l’immagine cambia, un’immagine non modificata non viene scansionata nuovamente. 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), configurando l’auto-instrumentazione nel tuo Dockerfile.

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.

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

Per invocare un Agent in esecuzione localmente tramite il target <your-agent-name>-serve, puoi inviare una semplice richiesta POST a /invocations sulla porta su cui è in esecuzione il tuo agente locale. Ad esempio, con curl:

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'

Clicca qui per maggiori dettagli sulla configurazione del comando acurl sopra

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).

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

Puoi anche eseguire una prova per vedere quali file verrebbero modificati

pnpm nx g @aws/nx-plugin:connection --dry-run

yarn nx g @aws/nx-plugin:connection --dry-run

npx nx g @aws/nx-plugin:connection --dry-run

bunx nx g @aws/nx-plugin:connection --dry-run

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

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.

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

Puoi anche eseguire una prova per vedere quali file verrebbero modificati

pnpm nx g @aws/nx-plugin:connection --dry-run

yarn nx g @aws/nx-plugin:connection --dry-run

npx nx g @aws/nx-plugin:connection --dry-run

bunx nx g @aws/nx-plugin:connection --dry-run

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

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).

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

Puoi anche eseguire una prova per vedere quali file verrebbero modificati

pnpm nx g @aws/nx-plugin:connection --dry-run

yarn nx g @aws/nx-plugin:connection --dry-run

npx nx g @aws/nx-plugin:connection --dry-run

bunx nx g @aws/nx-plugin:connection --dry-run

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

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