Agente Python

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 del 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 Agente

Puoi generare un Agente Python in due modi:

VSCode
CLI

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

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

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.
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/ (o nome personalizzato se specificato)
    __init__.py Inizializzazione pacchetto Python
    init.py Configurazione applicazione FastAPI con middleware CORS e gestione errori
    agent.py Definizione principale dell’agente con strumenti di esempio
    main.py Punto d’ingresso FastAPI per Bedrock AgentCore Runtime
    Dockerfile Punto d’ingresso per ospitare il tuo agente (escluso se infra è impostato a None)
- pyproject.toml Aggiornato con le dipendenze Strands
- project.json Aggiornato con i target di servizio dell’agente

Protocollo A2A

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

Directoryyour-project/
- Directoryyour_module/
  - Directoryagent/ (o nome personalizzato se specificato)
    __init__.py Inizializzazione pacchetto Python
    agent.py Definizione principale dell’agente con strumenti di esempio
    main.py Punto d’ingresso server A2A
    Dockerfile Punto d’ingresso per ospitare il tuo agente (escluso se infra è impostato a None)
- pyproject.toml Aggiornato con le dipendenze del framework e A2A
- project.json Aggiornato con i target di servizio dell’agente

Protocollo AG-UI

Il punto d’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/ (o nome personalizzato se specificato)
    __init__.py Inizializzazione pacchetto Python
    agent.py Definizione principale dell’agente con strumenti di esempio
    main.py Punto d’ingresso server AG-UI
    Dockerfile Punto d’ingresso per ospitare il tuo agente (escluso se infra è impostato a None)
- pyproject.toml Aggiornato con le dipendenze del framework e AG-UI
- project.json Aggiornato con i target di servizio dell’agente

Infrastruttura

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

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

CDK
Terraform

Directorypackages/common/constructs
- Directorysrc
  - Directoryapp/ Construct per l’infrastruttura specifica di un progetto/generatore
    …
  - Directorycore/ Construct generici riutilizzati dai construct in app
    …
  - index.ts Punto di ingresso che esporta i construct da app
- project.json Target di build e configurazione del progetto

Directorypackages/common/terraform
- Directorysrc
  - Directoryapp/ Moduli Terraform per l’infrastruttura specifica di un progetto/generatore
    …
  - Directorycore/ Moduli generici riutilizzati dai moduli in app
    …
- project.json Target di build e configurazione del progetto

Per la distribuzione del tuo Agent, vengono generati i seguenti file:

CDK
Terraform

Directorypackages/common/constructs/src
- Directoryapp
  - Directoryagents
    Directory<project-name>
    <project-name>.ts Costrutto CDK per distribuire l’agente

Se hai selezionato None per infra, non vengono generati costrutti CDK o moduli Terraform — lo Agent può essere eseguito solo localmente. L’opzione auth viene ignorata in questa modalità poiché non esiste 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 piano dati 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:
    """Calcola la somma di una lista di numeri"""
    return sum(numbers)

@tool
def get_weather(city: str) -> str:
    """Ottieni informazioni meteo per una città"""
    # Integrazione con l'API meteo qui
    return f"Meteo a {city}: Soleggiato, 25°C"

# Aggiungi strumenti al tuo agente
agent = Agent(
    system_prompt="Sei un assistente utile con accesso a vari strumenti.",
    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:
    """Calcola la somma di una lista di numeri"""
    return sum(numbers)

@tool
def get_weather(city: str) -> str:
    """Ottieni informazioni meteo per una città"""
    # Integrazione con l'API meteo qui
    return f"Meteo a {city}: Soleggiato, 25°C"

# Aggiungi strumenti al tuo agente
agent = create_agent(
    model=ChatBedrockConverse(model=MODEL_ID, region_name=REGION),
    tools=[calculate_sum, get_weather],
    system_prompt="Sei un assistente utile con accesso a vari strumenti.",
)

Utilizzare Strumenti Predefiniti

Strands
LangChain

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

from strands_tools import current_time, http_request, file_read

agent = Agent(
    system_prompt="Sei un assistente utile.",
    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="Sei un assistente utile.",
)

Configurazione del Modello

Strands
LangChain

Di default, gli agenti Strands usano Claude 4 Sonnet, ma puoi personalizzare il provider del modello. Vedi la documentazione Strands sui provider di modelli per le opzioni di configurazione:

from strands import Agent
from strands.models import BedrockModel

# Crea un 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,
)

Utilizzare Server MCP

Per utilizzare server MCP creati con 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.

VSCode
CLI

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

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

Consulta la guida del generatore connection per dettagli su come viene configurata la connessione.

Per altri server MCP, consulta la documentazione MCP di Strands o LangChain.

Approfondimenti

Per una guida più dettagliata sulla scrittura di agenti, consulta la documentazione di Strands o LangChain.

Protocollo

Il protocollo del server del tuo agente determina come comunica. Tutte le opzioni sono servite da FastAPI — il punto d’ingresso è diverso:

HTTP (predefinito): Un server FastAPI standard con un endpoint personalizzato /invocations, CORS e streaming. Ideale per integrazioni client personalizzate.
A2A: Un server Agent-to-Agent montato su un’app FastAPI (Strands utilizza lo Strands A2A Server; LangChain utilizza l’a2a-sdk indipendente dal framework). 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 d’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 ciascun 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 Invocazione 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 adattarli ai requisiti del tuo agente.

Definire Modelli di Input

Il modello InvokeInput predefinito accetta un messaggio.

from pydantic import BaseModel

class InvokeInput(BaseModel):
    message: str

Puoi estendere questo modello per includere qualsiasi campo aggiuntivo di cui il tuo agente ha bisogno.

L’ID di sessione viene estratto dall’header HTTP x-amzn-bedrock-agentcore-runtime-session-id, coerentemente 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 in 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.

Di default, l’agente produce oggetti StreamChunk contenenti il testo di risposta dell’agente:

class StreamChunk(BaseModel):
    content: str

Puoi personalizzare il modello StreamChunk per adattarlo alle 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))

Esiste una richiesta di funzionalità aperta per il supporto nativo in FastAPI.

Bedrock AgentCore Python SDK

Il generatore include una dipendenza sul Bedrock AgentCore Python SDK per le costanti PingStatus. Se desiderato, è 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 a2a-sdk AgentExecutor. Quando distribuito su AgentCore, il punto d’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 collegamento dipende dal framework:

Strands: avvolge il tuo Agent in un ag_ui_strands.StrandsAgent e crea l’app FastAPI tramite create_strands_app().
LangChain: avvolge il grafo compilato in un ag_ui_langgraph.LangGraphAgent e lo serve da un ciclo FastAPI /invocations scritto manualmente.

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, utilizza il 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 usa uv run per eseguire il tuo Agent utilizzando il Bedrock AgentCore Python SDK.

Chattare con il tuo Agente

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 un 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 esempio aggiungi nuovi campi a InvokeInput), aggiorna chat.ts per passare i nuovi campi quando invochi l’agente e il resto funziona automaticamente.

Chat with your deployed agent

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 runtime del tuo agente dalla configurazione 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 durante l’esecuzione del 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 durante l’esecuzione del generatore, o <ProjectName>-agent per impostazione predefinita.

Passa gli output del modulo runtime_config_appconfig condiviso 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 l’autenticazione IAM (predefinita) o Cognito durante la generazione del tuo agent.

IAM

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

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, ad 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 dipendenze Python in un file requirements.txt usando uv export
Installa le dipendenze per la piattaforma target (aarch64-manylinux_2_28) usando uv pip install

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

Image Scanning

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

Un target trivy viene aggiunto al progetto che scansiona l’immagine creata e termina con codice di uscita non-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 di container della build dell’immagine (docker o finch), quindi non sono necessari 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 si desidera sopprimere una vulnerabilità specifica, ad esempio quando non è ancora disponibile una correzione e si è valutato il rischio come accettabile.

Aggiungi l’ID della vulnerabilità (uno per riga) al file .trivyignore nella radice del progetto (cioè accanto al file 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 è configurato automaticamente con osservabilità usando AWS Distro for Open Telemetry (ADOT), configurando auto-strumentazione nel tuo Dockerfile.

Puoi trovare le tracce nella Console AWS CloudWatch, selezionando “GenAI Observability” nel menu. Nota che per popolare le tracce dovrai abilitare Transaction Search.

Per maggiori dettagli, consulta la documentazione AgentCore sull’osservabilità.

Invocare il tuo Agent

Invocare il Server Locale

Per invocare un Agente in esecuzione localmente tramite il target <your-agent-name>-serve, puoi inviare una semplice richiesta POST a /invocations sulla porta su cui il tuo agente locale è in esecuzione. 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’Agente Distribuito

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

Puoi ottenere l’ARN 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 in URL l’ARN sostituendo : con %3A e / con %2F.

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

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

L’URL 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 usando AWS Signature Version 4 (SigV4).

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

Puoi ottenere il token di accesso usando 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).

VSCode
CLI

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

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

Consulta la guida del generatore connection per dettagli su come viene configurata la connessione.

Invocare un Agente A2A come Strumento

Per delegare 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 target e trasforma tramite AST il file agent.py di questo agente per registrare l’agente A2A remoto come delegato decorato con @tool.

VSCode
CLI

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

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

Consulta la guida del generatore connection per dettagli su come viene configurata la connessione.

Invocare un Agente AG-UI

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

VSCode
CLI

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

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

Consulta la guida del generatore connection per dettagli su come viene configurata la connessione.

Proteggere il tuo Agente

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.

Tratta 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 nello strumento di esempio 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 IA Responsabile di Strands spiegano come scrivere prompt di sistema robusti e attenti alla sicurezza.

Limita 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 propri dell’agent.

Fornisci un interruttore di emergenza

Poiché il comportamento del modello può cambiare in modi inaspettati, pianifica la possibilità di disabilitare o sostituire rapidamente il modello senza una modifica al 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 manuale operativo.

Proteggi i dati sensibili

Evita di registrare nei log 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 persistente.
Redigi le informazioni personalmente identificabili (PII) da prompt e output — sia con un filtro per informazioni sensibili di Bedrock Guardrail (sotto) sia, per gli agent Strands, con gli approcci nella guida PII Redaction.

Amazon Bedrock Guardrails

Amazon Bedrock Guardrails fornisce 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 Guardrails di Strands 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 di guardrail_config.

Connessioni

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

React to Python AgentChiama un Python Agent da un sito React

React to AG-UI AgentChiama un Agent che espone il protocollo AG-UI da un sito React tramite CopilotKit

Python Agent to MCPCollega un Python Agent a un server MCP

Python Agent to A2A AgentCollega un Python Agent a un agente A2A remoto

TypeScript Agent to A2A AgentCollega un TypeScript Agent a un agente A2A remoto

Python Agent to Python DynamoDBCollega un Python Agent a una tabella DynamoDB

Python Agent to AgentCore GatewayCollega un Python Agent a un AgentCore Gateway