Agente Python

Gere um agente de IA em 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 Agente Python de duas formas:

VSCode
CLI

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

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

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.
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/ (ou nome personalizado se especificado)
    __init__.py Inicialização do pacote Python
    init.py Configuração da aplicação FastAPI com middleware CORS e tratamento de erros
    agent.py Definição principal do agente com ferramentas de exemplo
    main.py Ponto de entrada FastAPI para Bedrock AgentCore Runtime
    Dockerfile Ponto de entrada para hospedar seu agente (excluído quando infra é None)
- pyproject.toml Atualizado com dependências do Strands
- project.json Atualizado com alvos de serviço do agente

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/ (ou nome personalizado se especificado)
    __init__.py Inicialização do pacote Python
    agent.py Definição principal do agente com ferramentas de exemplo
    main.py Ponto de entrada do servidor A2A
    Dockerfile Ponto de entrada para hospedar seu agente (excluído quando infra é None)
- pyproject.toml Atualizado com dependências do framework e A2A
- project.json Atualizado com alvos de serviço do agente

Protocolo AG-UI

O ponto de entrada expõe seu agente via 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/ (ou nome personalizado se especificado)
    __init__.py Inicialização do pacote Python
    agent.py Definição principal do agente com ferramentas de exemplo
    main.py Ponto de entrada do servidor AG-UI
    Dockerfile Ponto de entrada para hospedar seu agente (excluído quando infra é None)
- pyproject.toml Atualizado com dependências do framework e AG-UI
- project.json Atualizado com alvos de serviço do agente

Infraestrutura

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

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

CDK
Terraform

Directorypackages/common/constructs
- Directorysrc
  - Directoryapp/ Constructs para infraestrutura específica de um projeto/gerador
    …
  - Directorycore/ Constructs genéricos reutilizados pelos constructs em app
    …
  - index.ts Ponto de entrada exportando os constructs de app
- project.json Metas de build e configuração do projeto

Directorypackages/common/terraform
- Directorysrc
  - Directoryapp/ Módulos Terraform para infraestrutura específica de um projeto/gerador
    …
  - Directorycore/ Módulos genéricos reutilizados pelos módulos em app
    …
- project.json Metas de build e configuração do projeto

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

CDK
Terraform

Directorypackages/common/constructs/src
- Directoryapp
  - Directoryagents
    Directory<project-name>
    <project-name>.ts Construct CDK para implantar seu agente

Se você selecionou None para infra, nenhum construct 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 a partir do nome da função e da docstring, e geram o schema 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 então 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 de Modelo

Strands
LangChain

Por padrão, agentes Strands usam Claude 4 Sonnet, mas você pode personalizar o provedor de modelo. Consulte a documentação do Strands sobre provedores de modelos 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 criados 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.

VSCode
CLI

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

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

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 detalhado sobre escrita de agentes, consulte a documentação do Strands ou LangChain.

Protocolo

O protocolo de servidor do seu agente determina como ele se comunica. Todas as opções são servidas pelo 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 clientes personalizados.
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 invocado por outros agentes compatíveis com A2A.
AG-UI: O protocolo AG-UI via SSE (Strands usa ag-ui-strands; LangChain usa ag-ui-langgraph). Melhor para integração direta com frontend usando CopilotKit em um website 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 schema 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 schemas de requisição e resposta. Você pode personalizar esses modelos em main.py para atender aos requisitos do seu agente.

Definindo Modelos de Entrada

O modelo padrão InvokeInput 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 necessite.

O ID de 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 em 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 em 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))

Existe 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, porém note que a segurança de tipos é 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 do a2a-sdk. Quando implantado no AgentCore, o ponto de entrada resolve o ARN público do runtime a partir 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 popula 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 via Server-Sent Events (SSE), além de /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 e cria a aplicação FastAPI via create_strands_app().
LangChain: envolve o grafo compilado em um ag_ui_langgraph.LangGraphAgent e o serve a partir de um loop FastAPI /invocations feito manualmente.

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 alvo 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 múltiplos componentes ao seu projeto (agentes, servidores MCP, etc.), isso inicia todos eles. Para executar apenas este agente, use seu alvo <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.

Converse com Seu Agente

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

O alvo de chat é executado de forma independente. Por padrão, ele se conecta ao seu agente em execução local, então inicie primeiro o alvo <your-agent-name>-dev do agente (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 Converse com seu agente implantado abaixo).

Para agentes HTTP, o script de chat usa um cliente TypeScript com segurança de tipos 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 alvo Nx <your-agent-name>-openapi que o executa
Um alvo Nx <your-agent-name>-generate-client que produz um cliente TypeScript com segurança de tipos em scripts/<your-agent-name>/generated/

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

Converse 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 de runtime do seu agente a partir da configuração de 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 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

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 o seu agente, 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 runtime_config_appconfig compartilhado para o módulo do agente:

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 o seu Agent. Você pode escolher entre autenticação IAM (padrão) ou Cognito ao gerar seu agente.

IAM

Por padrão, seu Agent será protegido usando autenticação IAM, basta implantá-lo 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 agente 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 agente, 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 agente para usar Cognito para autenticação.

CDK
Terraform

O construto gerado aceita uma propriedade 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 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]
}

Alvos Bundle e Docker

Para construir seu Agente para o Bedrock AgentCore Runtime, um alvo 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 alvo (aarch64-manylinux_2_28) usando uv pip install

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

Image Scanning

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 qualquer 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 ferramentas incluídas (como npm) para mantê-la assim.

A verificação usa o mesmo mecanismo de contêiner que a construção da sua 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 é configurado automaticamente com observabilidade usando o AWS Distro for Open Telemetry (ADOT), através da configuração de auto-instrumentação em seu Dockerfile.

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

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

Invocando seu Agente

Invocar o Servidor Local

Para invocar um Agente executando localmente através do alvo <your-agent-name>-serve, você pode enviar uma requisição POST simples 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 '{"message": "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 de runtime codificado em URL.

Você pode obter o ARN de 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 do 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 maneira 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 '{"message": "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 '{"message": "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 / Website React

Para invocar seu Agente a partir de um website React, você pode usar o gerador connection, que configura automaticamente um cliente com a autenticação correta (IAM ou Cognito).

VSCode
CLI

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

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

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 com SigV4 para o agente alvo e transforma via AST o agent.py deste agente para registrar o agente A2A remoto como um delegado decorado com @tool.

VSCode
CLI

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

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

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 a partir de um website React, use o gerador connection, que configura um cliente CopilotKit configurado para seu agente implantado com a autenticação correta (IAM ou Cognito).

VSCode
CLI

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

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

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

Protegendo seu Agente

Os agentes 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 agente gerado.

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

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

Defina esquemas de entrada estritos para suas ferramentas, como na ferramenta de exemplo gerada. Restrinja os 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 tem acesso.

Os guias de Engenharia de Prompts e IA Responsável do Strands abordam como escrever prompts de sistema robustos e conscientes da segurança.

Defina permissões de ferramentas de forma restrita

Conceda ao papel IAM do agente apenas as permissões que suas ferramentas precisam. Os construtos 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 agente 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 próprias do agente.

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 alteração 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 agente 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 resto da sua aplicação degrade graciosamente.

Documente como ativar esses controles em seu manual operacional.

Proteja dados sensíveis

Evite registrar prompts e conclusões, que podem conter dados do usuário. O hook de registro de erros do modelo do agente 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 de identificação pessoal (PII) de prompts e saídas — seja com um filtro de informações sensíveis do Bedrock Guardrail (abaixo) ou, para agentes Strands, as abordagens no guia de 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 agente 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 do ChatBedrockConverse para os campos de 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 para Python AgentChame um Python Agent de um site React

React para AG-UI AgentChame um Agent que expõe o protocolo AG-UI de um site React via CopilotKit

Python Agent para MCPConecte um Python Agent a um servidor MCP

Python Agent para A2A AgentConecte um Python Agent a um agente A2A remoto

TypeScript Agent para A2A AgentConecte um TypeScript Agent a um agente A2A remoto

Python Agent para Python DynamoDBConecte um Python Agent a uma tabela DynamoDB

Python Agent para AgentCore GatewayConecte um Python Agent a um AgentCore Gateway