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

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

CLI

pnpm

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

yarn

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

npm

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

bun

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

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

pnpm

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

yarn

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

npm

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

bun

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

Pré-requisito do projeto

Primeiro use o gerador py#project para criar um projeto onde adicionar seu Agente.

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:

protocol = http

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

protocol = a2a

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

protocol = ag-ui

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

Conectar a um website React

Agentes AG-UI podem ser conectados a um frontend React usando o gerador connection, que configurará componentes do CopilotKit para uma experiência de chat rica.

Infraestrutura

infra = agentcore

Como este gerador fornece infraestrutura como código com base no iacProvider 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

• 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

Projeto gerado

Este projeto é gerado usando o gerador ts#project e portanto configura as mesmas metas de build.

Terraform

• 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

Projeto gerado

Este projeto é gerado usando o gerador terraform#project e portanto configura as mesmas metas de build.

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

CDK

• Directorypackages/common/constructs/src

  • Directoryapp

    • Directoryagents

      • Directory<project-name>

        • <project-name>.ts Construct CDK para implantar seu agente

Terraform

• Directorypackages/common/terraform/src

  • Directoryapp

    • Directoryagents

      • Directory<project-name>

        • <project-name>.tf Módulo para implantar seu agente
  • Directorycore

    • Directoryagent-core

      • runtime.tf Módulo genérico para implantação no Bedrock AgentCore Runtime

infra = none

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.

Arquitetura

Bedrock AgentCore Runtime

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.

None (local only)

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

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],
)

LangChain

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

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

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

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)

LangChain

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

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

CLI

pnpm

pnpm nx g @aws/nx-plugin:connection

yarn

yarn nx g @aws/nx-plugin:connection

npm

npx nx g @aws/nx-plugin:connection

bun

bunx nx g @aws/nx-plugin:connection

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

pnpm

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

yarn

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

npm

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

bun

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

protocol = http

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 uma mensagem.

from pydantic import BaseModel

class InvokeInput(BaseModel):
    message: 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.

Organização do código

Você provavelmente desejará abstrair parte ou todo o ID de sessão do chamador se os usuários forem invocar seu agente diretamente. Por exemplo, você pode usar o ID do usuário autenticado como parte do ID de sessão.

Também vale a pena notar que, dependendo do seu caso de uso, você pode precisar implementar autorização para sessões, por exemplo, garantindo que os usuários possam acessar apenas suas próprias sessões e não as de outros usuários.

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

Limitação de streaming do FastAPI

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.

Infraestrutura como código

Como o gerador fornece infraestrutura CDK ou Terraform que gerencia a implantação do seu agente, você não precisa utilizar o bedrock-agentcore-starter-toolkit mencionado na documentação para implantar seu agente.

protocol = a2a

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.

protocol = ag-ui

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.

Conectar a um website React

Agentes AG-UI são projetados para serem consumidos diretamente por um frontend. Use o gerador connection para conectar seu website React ao agente com um provedor CopilotKit e cliente AG-UI HttpAgent.

Executando Seu Agente

Desenvolvimento Local

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

pnpm

pnpm nx dev your-project

yarn

yarn nx dev your-project

npm

npx nx dev your-project

bun

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

pnpm nx agent-dev your-project

yarn

yarn nx agent-dev your-project

npm

npx nx agent-dev your-project

bun

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

pnpm nx agent-dev your-project

yarn

yarn nx agent-dev your-project

npm

npx nx agent-dev your-project

bun

bunx nx agent-dev your-project

Em seguida, em outro terminal, inicie o chat:

pnpm

pnpm nx run your-project:agent-chat

yarn

yarn nx run your-project:agent-chat

npm

npx nx run your-project:agent-chat

bun

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.

infra = agentcore

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

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:

pnpm

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

yarn

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

npm

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

bun

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

Cognito

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:

pnpm

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

yarn

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

npm

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

bun

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

infra = agentcore

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

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

Construto CDK

Este construto usa o módulo aws-cdk-lib/aws-bedrockagentcore.

Terraform

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
}

Permissões de Modelo Bedrock

O construto de agente gerado concede permissão para invocar todos os modelos de fundação e perfis de inferência do Bedrock por padrão (bedrock:InvokeModel e bedrock:InvokeModelWithResponseStream em arn:aws:bedrock:*:*:foundation-model/* e arn:aws:bedrock:*:*:inference-profile/*).

Você pode querer restringir isso aos modelo(s) específico(s) que seu agente usa. Você pode encontrar o modelo padrão usado pelos agentes Strands na documentação do Strands; veja o guia de provedores de modelo Strands para configurar um modelo diferente.

Docker necessário

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

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

Terraform

# 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

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.

Terraform

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

Provedores OIDC personalizados

Se você precisar de autenticação JWT personalizada com um provedor OIDC não-Cognito, você pode modificar o construto CDK gerado ou o módulo Terraform para o seu agente diretamente. Note que o gerador de conexão suportará apenas autenticação IAM ou Cognito.

Melhores Práticas de Segurança

Ao implementar a lógica de negócios do seu agente, revise as melhores práticas de segurança do Bedrock AgentCore Runtime.

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.

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

protocol = http

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"

Flag de streaming do Curl

O argumento -N dado ao curl desabilita o buffering do fluxo de saída, para que você possa ver a resposta em streaming em tempo real.

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

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

Terraform

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

Console do navegador

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

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

IAM

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

Cognito

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

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

CLI

pnpm

pnpm nx g @aws/nx-plugin:connection

yarn

yarn nx g @aws/nx-plugin:connection

npm

npx nx g @aws/nx-plugin:connection

bun

bunx nx g @aws/nx-plugin:connection

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

pnpm

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

yarn

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

npm

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

bun

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

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

protocol = a2a

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

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

CLI

pnpm

pnpm nx g @aws/nx-plugin:connection

yarn

yarn nx g @aws/nx-plugin:connection

npm

npx nx g @aws/nx-plugin:connection

bun

bunx nx g @aws/nx-plugin:connection

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

pnpm

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

yarn

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

npm

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

bun

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

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

protocol = ag-ui

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

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

CLI

pnpm

pnpm nx g @aws/nx-plugin:connection

yarn

yarn nx g @aws/nx-plugin:connection

npm

npx nx g @aws/nx-plugin:connection

bun

bunx nx g @aws/nx-plugin:connection

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

pnpm

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

yarn

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

npm

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

bun

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

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

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 Agent Chame um Python Agent de um site React

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

Python Agent para MCP Conecte um Python Agent a um servidor MCP

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

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

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

Python Agent para AgentCore Gateway Conecte um Python Agent a um AgentCore Gateway