Python Agent

Gere um agente de IA Python para construir agentes com ferramentas e, opcionalmente, implante-o no Amazon Bedrock AgentCore Runtime. Escolha o framework do agente com a opção framework: Strands (o padrão) ou LangChain (construído sobre LangGraph).

O gerador expõe seu agente através de um protocol de servidor. Ambos os frameworks suportam HTTP (o padrão), o protocolo Agent-to-Agent (A2A) para interoperabilidade com outros agentes compatíveis com A2A, e o protocolo AG-UI para integração direta com frontend via CopilotKit.

Uso

Gerar um Agente

Você pode gerar um Python Agent de duas maneiras:

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

Você também pode realizar uma execução simulada para ver quais arquivos seriam alterados

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

Instale o Nx Console VSCode Plugin se ainda não o fez
Abra o console Nx no VSCode
Clique em Generate (UI) na seção "Common Nx Commands"
Procure por @aws/nx-plugin - py#agent
Preencha os parâmetros obrigatórios
Clique em Generate

Opções

Parâmetro	Tipo	Padrão	Descrição
project Obrigatório	string	-	O projeto ao qual adicionar o Agent
framework	strands \| langchain	strands	O SDK do agente a ser usado.
name	string	-	O nome do seu Agent (padrão: agent)
auth	iam \| cognito	iam	O método usado para autenticar com seu Agent. Aplicável apenas quando infra está definido (ignorado quando infra é none).
protocol	http \| a2a \| ag-ui	http	O protocolo do servidor para o seu Agent. HTTP expõe um servidor HTTP FastAPI. A2A expõe um servidor de protocolo Agent-to-Agent. AG-UI expõe um servidor de protocolo Agent-User Interaction para integração direta com frontend.
iac	inherit \| cdk \| terraform	inherit	O provedor IaC preferido. Por padrão, isso é herdado da sua seleção inicial.
infra	agentcore \| none	agentcore	O tipo de infraestrutura para hospedar seu Agent.
session	s3 \| dynamodb-s3 \| in-memory	s3	O armazenamento usado para persistir a sessão do seu Agent. LangChain oferece suporte a 's3' ou 'dynamodb-s3'; Strands oferece suporte a 's3'; 'in-memory' é válido para ambos.
preferInstallDependencies	boolean	true	Se deve preferir instalar dependências após a execução do gerador. Defina como false para adiar a instalação ao executar múltiplos geradores em lote (uma instalação ainda é executada se necessário para que geradores subsequentes possam computar o grafo de projetos Nx); instale uma vez no final.

Saída do Gerador

O gerador adicionará os seguintes arquivos ao seu projeto Python existente. Os arquivos gerados dependem do protocol escolhido:

Protocolo HTTP (padrão)

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

Protocolo A2A

O ponto de entrada expõe seu agente através do protocolo A2A (Strands usa o Strands A2A Server; LangChain envolve o grafo em um executor a2a-sdk), montado em uma aplicação 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

Protocolo AG-UI

O ponto de entrada expõe seu agente através do protocolo AG-UI para integração direta com frontend usando CopilotKit. Agentes Strands usam a integração ag-ui-strands; agentes LangChain usam 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

Infraestrutura

Como este gerador fornece infraestrutura como código baseada no seu iac escolhido, ele criará um projeto em packages/common que inclui os constructs CDK relevantes ou módulos Terraform.

O projeto comum de infraestrutura como código é estruturado da seguinte forma:

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

Para implantar seu Agente, os seguintes arquivos são gerados:

CDK
Terraform

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

Se você selecionou none para infra, nenhum construto CDK ou módulo Terraform é gerado — o Agente só pode ser executado localmente. A opção auth é ignorada neste modo, pois não há endpoint hospedado para autenticar.

Quando implantado no Bedrock AgentCore Runtime, o agente é construído em uma imagem de contêiner, enviado para o Amazon ECR e executado no AgentCore Runtime. Os clientes invocam o endpoint do plano de dados do AgentCore Runtime, que encaminha as solicitações para o seu agente. O agente chama o Amazon Bedrock para inferência de modelo e pode invocar ferramentas, servidores MCP ou APIs downstream.

Com infra: none, nenhuma infraestrutura AWS é gerada. O agente é executado como um processo local e chama o Amazon Bedrock para inferência de modelo.

Trabalhando com Seu Agente

Você pode editar agent.py para adicionar ferramentas, configurar o modelo e personalizar o prompt do sistema. A API depende do framework que você escolheu.

Adicionando Ferramentas

Ferramentas são funções que o agente de IA pode chamar para executar ações. Ambos os frameworks usam uma abordagem baseada em decoradores para definir ferramentas, derivam o nome e a descrição da ferramenta do nome da função e da docstring, e geram o esquema de entrada a partir de suas dicas de tipo.

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

Usando Ferramentas Pré-construídas

Strands
LangChain

Strands fornece uma coleção de ferramentas pré-construídas através do pacote 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 fornece um grande ecossistema de ferramentas e integrações. Instale o pacote de integração relevante e, em seguida, passe as ferramentas para 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.",
)

Configuração do Modelo

Strands
LangChain

Por padrão, agentes Strands usam Claude 4 Sonnet, mas você pode personalizar o provedor do modelo. Consulte a documentação Strands sobre provedores de modelo para opções de configuração:

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)

Agentes LangChain usam um modelo ChatBedrockConverse. O agente gerado lê o id do modelo e a região das variáveis de ambiente MODEL_ID e AWS_REGION, mas você pode configurar o modelo diretamente em 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,
)

Consumindo Servidores MCP

Para consumir Servidores MCP que você criou usando os geradores py#mcp-server ou ts#mcp-server, você pode usar o gerador connection, que conecta as ferramentas do servidor MCP ao seu agente para ambos os frameworks.

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

Você também pode realizar uma execução simulada para ver quais arquivos seriam alterados

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

Instale o Nx Console VSCode Plugin se ainda não o fez
Abra o console Nx no VSCode
Clique em Generate (UI) na seção "Common Nx Commands"
Procure por @aws/nx-plugin - connection
Preencha os parâmetros obrigatórios
Clique em Generate

Consulte o guia do gerador connection para detalhes sobre como a conexão é configurada.

Para outros servidores MCP, consulte a documentação MCP do Strands ou LangChain.

Mais

Para um guia mais aprofundado sobre como escrever agentes, consulte a documentação do Strands ou LangChain.

Protocolo

O protocolo do servidor do seu agente determina como ele se comunica. Todas as opções são servidas por FastAPI — o ponto de entrada difere:

HTTP (padrão): Um servidor FastAPI padrão com um endpoint /invocations personalizado, CORS e streaming. Melhor para integrações de cliente personalizadas.
A2A: Um servidor Agent-to-Agent montado em uma aplicação FastAPI (Strands usa o Strands A2A Server; LangChain usa o a2a-sdk agnóstico de framework). Melhor quando seu agente precisa ser descoberto e invocável por outros agentes compatíveis com A2A.
AG-UI: O protocolo AG-UI sobre SSE (Strands usa ag-ui-strands; LangChain usa ag-ui-langgraph). Melhor para integração direta com frontend usando CopilotKit em um site React.

O ponto de entrada do servidor difere por framework (Strands produz um Agent gerenciado por contexto, enquanto LangChain conduz um grafo create_agent compilado), mas o contrato externo para cada protocolo é o mesmo.

Todos os protocolos expõem /ping para o contrato de verificação de saúde do runtime AgentCore. Agentes A2A escutam na porta 9000; agentes HTTP e AG-UI escutam na porta 8080. O Dockerfile e a infraestrutura gerados são configurados para você.

Servidor FastAPI (protocolo HTTP)

O servidor HTTP gerado inclui:

Configuração da aplicação FastAPI com middleware CORS
Middleware de tratamento de erros
Geração de esquema OpenAPI
Endpoint de verificação de saúde (/ping)
Endpoint de invocação do agente (/invocations)

Personalizando Entradas e Saídas de Invocação com Pydantic

O endpoint de invocação do agente usa modelos Pydantic para definir e validar os esquemas de solicitação e resposta. Você pode personalizar esses modelos em main.py para corresponder aos requisitos do seu agente.

Definindo Modelos de Entrada

O modelo InvokeInput padrão aceita um prompt.

from pydantic import BaseModel

class InvokeInput(BaseModel):
    prompt: str

Você pode estender este modelo para incluir quaisquer campos adicionais que seu agente precise.

O ID da sessão é extraído do cabeçalho HTTP x-amzn-bedrock-agentcore-runtime-session-id, consistente com o contrato de sessão do Bedrock AgentCore Runtime. Se o cabeçalho não for fornecido, um UUID aleatório é gerado como fallback.

Definindo Modelos de Saída

Para respostas de streaming, o gerador fornece JsonStreamingResponse que serializa automaticamente modelos Pydantic para o formato JSON Lines (application/jsonl). Este formato é compatível com a especificação de streaming do OpenAPI 3.2 e funciona perfeitamente com o cliente TypeScript gerado.

Por padrão, o agente produz objetos StreamChunk contendo o texto de resposta do agente:

class StreamChunk(BaseModel):
    content: str

Você pode personalizar o modelo StreamChunk para atender às suas necessidades:

from pydantic import BaseModel

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

Note que, como o FastAPI atualmente não suporta a geração de uma especificação OpenAPI para respostas de streaming, devemos definir explicitamente o modelo de resposta para cada operação de streaming, ou seja:

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

Há uma solicitação de recurso aberta para suporte nativo no FastAPI.

Bedrock AgentCore Python SDK

O gerador inclui uma dependência no Bedrock AgentCore Python SDK para as constantes PingStatus. Se desejar, é simples usar BedrockAgentCoreApp em vez de FastAPI, no entanto, note que a segurança de tipo é perdida.

Você pode encontrar mais detalhes sobre as capacidades do SDK na documentação aqui.

Servidor A2A (protocolo A2A)

O main.py gerado monta um servidor A2A em uma aplicação FastAPI pai que também expõe /ping. Agentes Strands usam o A2AServer do Strands; agentes LangChain envolvem o grafo compilado em um AgentExecutor a2a-sdk. Quando implantado no AgentCore, o ponto de entrada resolve o ARN público do runtime do AppConfig e o anuncia no cartão do agente.

A maioria dos usuários não precisará modificar este arquivo; edite agent.py para alterar ferramentas ou o prompt do sistema. O servidor A2A preenche o cartão do agente (/.well-known/agent-card.json) a partir do name e description do agente.

Servidor AG-UI (protocolo AG-UI)

O main.py gerado expõe um único endpoint POST que transmite eventos AG-UI através de Server-Sent Events (SSE), bem como /ping para a verificação de saúde do runtime AgentCore. A conexão depende do framework:

Strands: envolve seu Agent em um ag_ui_strands.StrandsAgent, construído dentro de um manipulador lifespan do FastAPI (para que a construção aconteça na inicialização do contêiner/sessão em vez do tempo de importação), e servido de um loop /invocations FastAPI feito à mão.
LangChain: envolve o grafo compilado em um ag_ui_langgraph.LangGraphAgent, construído da mesma forma dentro de lifespan, e servido de um loop /invocations FastAPI feito à mão.

A maioria dos usuários não precisará modificar este arquivo — edite agent.py para alterar ferramentas ou o prompt do sistema.

Executando Seu Agente

Desenvolvimento Local

Para executar seu Agente (e tudo conectado a ele) localmente, use o target dev do projeto:

pnpm nx dev your-project

yarn nx dev your-project

npx nx dev your-project

bunx nx dev your-project

Se você adicionou vários componentes ao seu projeto (agentes, servidores MCP, etc.), isso inicia todos eles. Para executar apenas este agente, direcione seu 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

Isso usa uv run para executar seu Agente usando o Bedrock AgentCore Python SDK.

Conversar com Seu Agente

O gerador configura um target Nx <your-agent-name>-chat que o coloca em um chat interativo de terminal com seu agente.

O target de chat é executado de forma independente. Por padrão, ele se conecta ao seu agente em execução local, então inicie o target <your-agent-name>-dev do agente primeiro (em um terminal separado):

pnpm nx agent-dev your-project

yarn nx agent-dev your-project

npx nx agent-dev your-project

bunx nx agent-dev your-project

Em seguida, em outro terminal, inicie o 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

O gerador emite um scripts/<your-agent-name>/chat.ts para cada protocolo. Ele se conecta ao agente local por padrão, ou ao seu agente implantado quando RUNTIME_CONFIG_APP_ID está definido (veja Conversar com seu agente implantado abaixo).

Para agentes HTTP, o script de chat usa um cliente TypeScript type-safe gerado a partir da especificação OpenAPI do agente. O gerador também emite:

scripts/<your-agent-name>_openapi.py — um pequeno script que exporta a especificação OpenAPI do agente
Um target Nx <your-agent-name>-openapi que o executa
Um target Nx <your-agent-name>-generate-client que produz um cliente TypeScript type-safe em scripts/<your-agent-name>/generated/

Quando você personaliza a forma de entrada do agente (por exemplo, adiciona novos campos a InvokeInput), atualize chat.ts para passar os novos campos ao invocar o agente e o resto funciona automaticamente.

Conversar com seu agente implantado

Para conversar com seu agente implantado no Bedrock AgentCore, defina a variável de ambiente RUNTIME_CONFIG_APP_ID para o id da aplicação AppConfig da implantação (saída como RuntimeConfigApplicationId pela stack implantada). O script de chat resolve o ARN do runtime do seu agente a partir da configuração do runtime e se conecta ao endpoint implantado:

IAM
Cognito

Para agentes autenticados por IAM, as requisições são assinadas com SigV4 usando suas credenciais AWS padrão. Certifique-se de que o ambiente tenha credenciais AWS com permissão para invocar o 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

Para agentes autenticados por Cognito, forneça um token de acesso Cognito através da variável de ambiente AGENT_ACCESS_TOKEN, que é enviado como um token bearer:

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

Você pode obter um token de acesso usando o comando cognito-idp admin-initiate-auth da AWS CLI, por exemplo:

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

Implantando Seu Agente no Bedrock AgentCore Runtime

Infraestrutura como Código

Se você selecionou agentcore para infra, a infraestrutura CDK ou Terraform relevante é gerada, que você pode usar para implantar seu Agent no Amazon Bedrock AgentCore Runtime.

CDK
Terraform

Um construto CDK é gerado para seu agent, nomeado com base no name que você escolheu ao executar o gerador, ou <ProjectName>Agent por padrão.

Você pode usar este construto CDK em uma aplicação CDK:

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

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

Um módulo Terraform é gerado para você, nomeado com base no name que você escolheu ao executar o gerador, ou <ProjectName>-agent por padrão.

Passe as saídas do módulo compartilhado runtime_config_appconfig para o módulo do 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 é necessário para construir e implantar seu Agent. Certifique-se de ter instalado e iniciado o Docker para evitar erros como:

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

Autenticação

O gerador fornece uma opção auth para configurar a autenticação para seu Agent. Você pode escolher entre autenticação IAM (padrão) ou Cognito ao gerar seu agent.

IAM

Por padrão, seu Agent será protegido usando autenticação IAM, simplesmente implante-o sem nenhum argumento:

CDK
Terraform

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

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

Você pode conceder acesso para invocar seu agent no Bedrock AgentCore Runtime usando o método grantInvokeAccess, por exemplo:

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
}

Para conceder acesso para invocar seu agent, você precisará adicionar uma política como a seguinte, referenciando a saída 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}/*"
  ]
}

Autenticação Cognito

Quando você seleciona autenticação Cognito, o gerador configura o agent para usar Cognito para autenticação.

CDK
Terraform

O construto gerado aceita uma prop identity que configura a autenticação 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,
    });
  }
}

O construto UserIdentity pode ser gerado usando o gerador ts#website#auth, ou você pode criar seu próprio UserPool e UserPoolClient CDK.

O módulo gerado aceita as variáveis user_pool_id e user_pool_client_ids para autenticação 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]
}

Targets de Bundle e Docker

Para construir seu Agente para o Bedrock AgentCore Runtime, um target bundle é adicionado ao seu projeto, que:

Exporta suas dependências Python para um arquivo requirements.txt usando uv export
Instala dependências para a plataforma de destino (aarch64-manylinux_2_28) usando uv pip install

Um target docker específico para seu Agente também é adicionado, que copia o Dockerfile e os artefatos empacotados em um diretório de contexto docker. Isso coloca o Dockerfile junto com a saída construída, permitindo que o CDK construa a imagem Docker diretamente usando AgentRuntimeArtifact.fromAsset.

Verificação de Imagem

A imagem Docker construída para este projeto pode ser verificada em busca de vulnerabilidades usando Trivy, executando a partir da imagem Trivy hospedada no ECR.

Um target trivy é adicionado ao seu projeto que verifica a imagem construída e sai com código diferente de zero se alguma vulnerabilidade de severidade HIGH ou CRITICAL for encontrada. O Dockerfile gerado usa uma imagem base sem vulnerabilidades corrigíveis conhecidas dessas severidades no momento da geração, e atualiza as ferramentas incluídas (como npm) para mantê-lo assim.

A verificação usa o mesmo mecanismo de contêiner que sua construção de imagem (docker ou finch), portanto nenhuma ferramenta adicional é necessária. Como a verificação só é executada novamente quando a imagem muda, uma imagem inalterada não é verificada novamente. O script raiz trivy fornecido verifica todas as imagens no workspace:

pnpm trivy

yarn trivy

npm run trivy

bun trivy

Suprimindo Descobertas do Trivy

Pode haver casos em que você deseja suprimir uma vulnerabilidade específica, por exemplo, quando nenhuma correção está disponível ainda e você avaliou o risco como aceitável.

Adicione o ID da vulnerabilidade (um por linha) ao arquivo .trivyignore na raiz do seu projeto (ou seja, ao lado do seu project.json):

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

Para mais detalhes sobre filtragem de descobertas, consulte a documentação de filtragem do Trivy.

Observabilidade

Seu agente é automaticamente configurado com observabilidade usando o AWS Distro for Open Telemetry (ADOT), configurando auto-instrumentação em seu Dockerfile.

Você pode encontrar traces no Console AWS do CloudWatch, selecionando “GenAI Observability” no menu. Note que para que os traces sejam preenchidos, você precisará habilitar Transaction Search.

Para mais detalhes, consulte a documentação do AgentCore sobre observabilidade.

Gerenciamento de Sessão

A opção session mapeia para um conceito de persistência subjacente diferente dependendo do framework escolhido: o conceito de gerenciamento de sessão do Strands para o framework strands, ou o conceito de checkpointer do LangGraph para o framework langchain.

A opção session controla como seu agente persiste o estado da conversa (histórico de mensagens, estado da ferramenta, etc.) entre invocações, usando o SessionManager do SDK Strands:

s3 (padrão): A infraestrutura CDK/Terraform provisiona um bucket S3 dedicado para dados de sessão, criptografado com uma chave KMS dedicada e com todo acesso público bloqueado; logs de acesso ao servidor são entregues a um grupo de logs do CloudWatch Logs através da mesma chave. A função IAM do agente recebe acesso de leitura/escrita/listagem/exclusão ao bucket e acesso de descriptografia/geração-de-chave-de-dados à chave, e o nome do bucket é registrado junto com o ARN do agente na configuração do runtime do AppConfig.
in-memory: Nenhum bucket é provisionado. O estado da conversa é mantido apenas na memória durante o tempo de vida do processo em execução e não sobrevive a reinicializações ou scale-in.

Isso é implementado no session.py gerado, que exporta uma função get_session_manager() resolvendo um SessionManager para a sessão atual.

Como o adaptador ag-ui-strands do AG-UI clona um Agent modelo por thread de conversa, get_session_manager é conectado como um session_manager_provider no StrandsAgentConfig passado para StrandsAgent em main.py, para que um SessionManager novo seja resolvido para cada thread em vez de ser incorporado ao agente modelo compartilhado.

Como with_session_id já armazena em cache uma instância de Agent por sessão, get_session_manager é chamado diretamente dentro da chamada Agent(session_manager=get_session_manager()) de get_agent em agent.py.

O próprio ID da sessão vem da sessão do AgentCore Runtime (propagada através do cabeçalho x-amzn-bedrock-agentcore-runtime-session-id) e é vinculado a um contexto baseado em contextvars.ContextVar para que get_current_session_id() possa resolvê-lo em qualquer lugar na requisição — incluindo em quaisquer clientes MCP ou A2A downstream conectados através do gerador connection, para que toda a cadeia de chamadas compartilhe uma sessão consistente.

A opção session controla como o checkpointer LangGraph do seu agente persiste o estado da conversa:

s3 (padrão): O agente implantado usa um S3CheckpointSaver com o bucket de sessão provisionado, armazenando checkpoints e escritas pendentes sob o prefixo checkpoints/. Esta classe reside em s3_checkpoint_saver_langchain.py no projeto compartilhado de conexão de agente.
dynamodb-s3: A infraestrutura CDK/Terraform provisiona uma tabela DynamoDB para checkpoints, configurada conforme recomendado na documentação AWS sobre o uso do DynamoDB como armazenamento de checkpoint para agentes LangGraph (esquema unificado PK/SK, cobrança PAY_PER_REQUEST, recuperação point-in-time e um atributo ttl), mais um bucket S3 para descarregar checkpoints acima de 350KB. Ambos são criptografados com uma chave KMS dedicada; os logs de acesso ao servidor do bucket são entregues a um grupo de logs do CloudWatch Logs através da mesma chave. A função IAM do agente recebe acesso de leitura/escrita à tabela e ao bucket, e os nomes da tabela/bucket são registrados junto com o ARN do agente na configuração do runtime do AppConfig.
in-memory: Nenhuma tabela ou bucket é provisionado. O estado da conversa é mantido apenas na memória durante o tempo de vida do processo em execução e não sobrevive a reinicializações ou scale-in.

Isso é implementado no session.py gerado, que exporta uma função get_checkpointer() chamada de create_agent(..., checkpointer=get_checkpointer()) em agent.py.

Invocando seu Agente

Invocar o Servidor Local

Para invocar um Agente em execução local através do target <your-agent-name>-serve, você pode enviar uma simples requisição POST para /invocations na porta em que seu agente local está sendo executado. Por exemplo, com curl:

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

Invocar o Agente Implantado

Para invocar seu Agent implantado no Bedrock AgentCore Runtime, você pode enviar uma requisição POST para o endpoint do dataplane do Bedrock AgentCore Runtime com seu ARN codificado em URL.

Você pode obter o ARN do runtime da sua infraestrutura da seguinte forma:

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
}

O ARN terá o seguinte formato: arn:aws:bedrock-agentcore:<region>:<account>:runtime/<agent-runtime-id>.

Você pode então codificar o ARN em URL substituindo : por %3A e / por %2F.

Isso é simples em um console de navegador ou Node REPL usando o método integrado encodeURIComponent:

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

A URL do dataplane do Bedrock AgentCore Runtime para invocar o agent é a seguinte:

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

Sua infraestrutura também pode gerar a URL de invocação completa diretamente, com a codificação do ARN tratada para você:

CDK
Terraform

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

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

A forma exata de invocar esta URL depende do método de autenticação usado.

IAM
Cognito

Autenticação IAM

Para Autenticação IAM, a requisição deve ser assinada 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 '{"prompt": "what is 3 + 5?"}' \
-H 'Content-Type: application/json'

Clique aqui para mais detalhes sobre como configurar o comando acurl acima

Autenticação JWT / Cognito

Para Autenticação Cognito, passe o Token de Acesso Cognito no cabeçalho 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>"

Você pode obter o token de acesso usando o comando cognito-idp admin-initiate-auth da AWS CLI, por exemplo:

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

Navegador / Site React

Para invocar seu Agente de um site React, você pode usar o gerador connection, que configura automaticamente um cliente com a autenticação correta (IAM ou 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

Você também pode realizar uma execução simulada para ver quais arquivos seriam alterados

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

Instale o Nx Console VSCode Plugin se ainda não o fez
Abra o console Nx no VSCode
Clique em Generate (UI) na seção "Common Nx Commands"
Procure por @aws/nx-plugin - connection
Preencha os parâmetros obrigatórios
Clique em Generate

Consulte o guia do gerador connection para detalhes sobre como a conexão é configurada.

Invocando um Agente A2A como Ferramenta

Para delegar trabalho deste agente para um agente A2A remoto (seja TypeScript ou Python), use o gerador connection. Ele fornece um cliente autenticado por SigV4 para o agente de destino e transforma por AST o agent.py deste agente para registrar o agente A2A remoto como um delegado decorado com @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

Você também pode realizar uma execução simulada para ver quais arquivos seriam alterados

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

Instale o Nx Console VSCode Plugin se ainda não o fez
Abra o console Nx no VSCode
Clique em Generate (UI) na seção "Common Nx Commands"
Procure por @aws/nx-plugin - connection
Preencha os parâmetros obrigatórios
Clique em Generate

Consulte o guia do gerador connection para detalhes sobre como a conexão é configurada.

Invocando um Agente AG-UI

Para invocar seu agente AG-UI de um site React, use o gerador connection, que conecta um cliente CopilotKit configurado para seu agente implantado com a autenticação correta (IAM ou 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

Você também pode realizar uma execução simulada para ver quais arquivos seriam alterados

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

Instale o Nx Console VSCode Plugin se ainda não o fez
Abra o console Nx no VSCode
Clique em Generate (UI) na seção "Common Nx Commands"
Procure por @aws/nx-plugin - connection
Preencha os parâmetros obrigatórios
Clique em Generate

Consulte o guia do gerador connection para detalhes sobre como a conexão é configurada.

Protegendo seu Agente

Agents atuam em entradas não confiáveis e podem executar ações reais através de suas ferramentas, por isso vale a pena considerar a segurança desde o início. As práticas a seguir se aplicam ao agent gerado.

Trate a entrada e saída do modelo como não confiáveis

Prompts podem conter instruções adversárias (injeção de prompt), e a saída do modelo é não determinística — nenhuma delas deve ser confiável em lógica sensível à segurança:

Defina esquemas de entrada estritos para suas ferramentas, como no exemplo de ferramenta gerado. Restrinja valores ao que a ferramenta realmente precisa (enums, limites de comprimento, intervalos numéricos) em vez de aceitar strings de formato livre.
Nunca passe a saída do modelo diretamente para comandos shell, consultas SQL, avaliação de código ou HTML renderizado sem validação ou codificação.
Aplique verificações de autorização em suas ferramentas e serviços downstream — não confie no prompt do sistema para impedir que o modelo use indevidamente uma ferramenta à qual ele tem acesso.

Os guias de Prompt Engineering e Responsible AI do Strands cobrem como escrever prompts de sistema robustos e conscientes da segurança.

Defina permissões de ferramentas de forma restrita

Conceda à role IAM do agent apenas as permissões que suas ferramentas precisam. Os constructs CDK e módulos Terraform fornecidos expõem métodos grant* e políticas com escopo definido para esse propósito — por exemplo, concedendo a um agent acesso para invocar uma API específica em vez de anexar políticas gerenciadas amplas. Quando uma ferramenta age em nome de um usuário, prefira autorizar a ação usando a identidade do usuário chamador (passada através do contexto da solicitação) em vez das permissões ambientes do próprio agent.

Forneça um interruptor de emergência

Como o comportamento do modelo pode mudar de maneiras inesperadas, planeje desabilitar ou trocar o modelo rapidamente sem uma mudança de código:

Leia o ID do modelo da configuração (por exemplo, uma variável de ambiente MODEL_ID) para que os operadores possam alternar ou reverter para um modelo diferente atualizando a configuração.
Coloque o agent atrás de uma feature flag para que sua funcionalidade de IA possa ser desabilitada completamente. Quando desabilitado, retorne uma mensagem genérica em vez de um erro, e garanta que o restante da sua aplicação degrade graciosamente.

Documente como acionar esses controles no seu runbook operacional.

Proteja dados sensíveis

Evite registrar prompts e completions, que podem conter dados do usuário. O hook de registro de erros do modelo do agent gerado registra apenas metadados de erro, não o conteúdo da conversa — mantenha essa propriedade ao adicionar seu próprio registro.
Retorne mensagens de erro genéricas aos usuários; registre erros detalhados no lado do servidor.
Isole o estado da conversa entre usuários e sessões, e autorize o acesso a quaisquer dados de sessão persistidos.
Remova informações pessoalmente identificáveis (PII) de prompts e saídas — seja com um filtro de informações sensíveis do Bedrock Guardrail (abaixo) ou, para agents Strands, as abordagens no guia PII Redaction.

Amazon Bedrock Guardrails

Amazon Bedrock Guardrails fornecem filtros de conteúdo configuráveis, tópicos negados e filtros de informações sensíveis (PII) que são avaliados na entrada e saída do modelo. Você pode anexar um guardrail ao modelo usado pelo agent gerado:

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)

Consulte o guia de Guardrails do Strands para mais detalhes.

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"),
    },
)

Consulte a documentação ChatBedrockConverse para os campos guardrail_config.

Conexões

Use o gerador connection para integrar este projeto com outros em seu workspace. As seguintes conexões envolvem este projeto:

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