TypeScript Agent

Gere um Strands Agent TypeScript para construir agentes de IA com ferramentas e, opcionalmente, implante-o no Amazon Bedrock AgentCore Runtime. Por padrão, o gerador usa tRPC sobre WebSocket para aproveitar o suporte de streaming bidirecional do AgentCore para comunicação em tempo real e com segurança de tipos. Alternativamente, você pode escolher o protocolo Agent-to-Agent (A2A) para interoperabilidade com outros agentes compatíveis com A2A, ou o protocolo AG-UI para integração direta com frontend via CopilotKit.

O que é Strands?

Strands é um framework leve para construir agentes de IA. Os principais recursos incluem:

Leve e personalizável: Loop de agente simples que não atrapalha
Pronto para produção: Observabilidade completa, rastreamento e opções de implantação para escala
Agnóstico de modelo e provedor: Suporta muitos modelos diferentes de vários provedores
Ferramentas impulsionadas pela comunidade: Conjunto poderoso de ferramentas contribuídas pela comunidade
Suporte multi-agente: Técnicas avançadas como equipes de agentes e agentes autônomos
Modos de interação flexíveis: Suporte conversacional, streaming e não-streaming

Uso

Gerar um Agent

Você pode gerar um TypeScript Agent de duas maneiras:

CLI
VSCode

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

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

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

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

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

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

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

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

bunx nx g @aws/nx-plugin:ts#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 - ts#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	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 tRPC/WebSocket. A2A expõe um servidor de protocolo Agent-to-Agent. AG-UI expõe um servidor de protocolo AG-UI para integração direta de frontend com CopilotKit.
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 \| in-memory	s3	O armazenamento usado para persistir a sessão do 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 calcular o grafo de projetos Nx); instale uma vez no final.

Saída do Gerador

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

Protocolo HTTP (padrão)

Directoryyour-project/
- Directorysrc/
  - Directoryagent/ (or custom name if specified)
    index.ts Entry point for Bedrock AgentCore Runtime (tRPC/WebSocket server)
    init.ts tRPC initialization
    router.ts tRPC router with agent procedures
    agent.ts Main agent definition with sample tools
    session.ts Resolves the SessionManager used to persist conversation state
    client.ts Vended client for invoking your agent
    agent-core-trpc-client.ts Client factory for connecting to agents on AgentCore Runtime
    Dockerfile Entry point for hosting your agent (excluded when infra is set to None)
- package.json Updated with Strands dependencies
- project.json Updated with agent serve targets

Protocolo A2A

O ponto de entrada usa o Strands A2A Express Server em vez de tRPC:

Directoryyour-project/
- Directorysrc/
  - Directoryagent/ (or custom name if specified)
    index.ts A2A Express server entry point
    agent.ts Main agent definition with sample tools
    session.ts Resolves the SessionManager used to persist conversation state
    Dockerfile Entry point for hosting your agent (excluded when infra is set to None)
- package.json Updated with Strands and Express dependencies
- project.json Updated with agent serve targets

Protocolo AG-UI

O ponto de entrada usa @ag-ui/aws-strands para expor o agente via protocolo AG-UI (SSE sobre POST), compatível com CopilotKit:

Directoryyour-project/
- Directorysrc/
  - Directoryagent/ (or custom name if specified)
    index.ts AG-UI server entry point (Express + SSE)
    agent.ts Main agent definition with sample tools
    session.ts Resolves the SessionManager used to persist conversation state
    Dockerfile Entry point for hosting your agent (excluded when infra is set to None)
- package.json Updated with Strands 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 Agent, 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 Agent 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 Agent

Protocolo

O protocolo do servidor do seu agente determina como ele se comunica. Você pode escolher entre:

HTTP (padrão): Usa tRPC sobre WebSocket para comunicação em tempo real e com segurança de tipos. Melhor para integrações de cliente personalizadas e controle refinado sobre a API do agente.
A2A: Usa o protocolo Agent-to-Agent (A2A) para comunicação padronizada entre agentes. Melhor quando seu agente precisa ser descoberto e invocável por outros agentes compatíveis com A2A.
AG-UI: Usa o protocolo AG-UI (SSE sobre POST) via @ag-ui/aws-strands para integração direta com frontend usando CopilotKit. Melhor quando você deseja uma interface de chat rica com streaming, visualização de chamadas de ferramentas e gerenciamento de estado.

O protocolo é definido na infraestrutura CDK/Terraform, e o código da aplicação é gerado de acordo.

tRPC sobre WebSocket (protocolo HTTP)

O TypeScript Agent usa tRPC sobre WebSocket, aproveitando o suporte de streaming bidirecional do AgentCore para permitir comunicação em tempo real e com segurança de tipos entre clientes e seu agente.

Como o tRPC suporta procedimentos Query, Mutation e Subscription sobre WebSocket, você pode definir qualquer número de procedimentos. Por padrão, um único procedimento de subscription chamado invoke é definido para você em router.ts.

Adicionando Ferramentas

Ferramentas são funções que o agente de IA pode chamar para executar ações. Você pode adicionar novas ferramentas no arquivo agent.ts:

import { Agent, tool } from '@strands-agents/sdk';
import { z } from 'zod';

const letterCounter = tool({
  name: 'letter_counter',
  description: 'Count occurrences of a specific letter in a word',
  inputSchema: z.object({
    word: z.string().describe('The input word to search in'),
    letter: z.string().length(1).describe('The specific letter to count'),
  }),
  callback: (input) => {
    const { word, letter } = input;
    const count = word.toLowerCase().split(letter.toLowerCase()).length - 1;
    return `The letter '${letter}' appears ${count} time(s) in '${word}'`;
  },
});

// Add tools to your agent
export const getAgent = async () => {
  return new Agent({
    systemPrompt: 'You are a helpful assistant with access to various tools.',
    tools: [letterCounter],
  });
};

O framework Strands lida automaticamente com:

Validação de entrada usando esquemas Zod
Geração de esquema JSON para chamada de ferramentas
Tratamento de erros e formatação de resposta

Configuração de Modelo

Por padrão, os agentes Strands usam Claude 4 Sonnet, mas você pode facilmente alternar entre provedores de modelo:

import { Agent } from '@strands-agents/sdk';
import { BedrockModel } from '@strands-agents/sdk/models/bedrock';
import { OpenAIModel } from '@strands-agents/sdk/models/openai';

// Use Bedrock
const bedrockModel = new BedrockModel({
  modelId: 'anthropic.claude-sonnet-4-20250514-v1:0',
});
let agent = new Agent({ model: bedrockModel });
let response = await agent.invoke('What can you help me with?');

// Alternatively, use OpenAI by just switching model provider
const openaiModel = new OpenAIModel({
  apiKey: process.env.OPENAI_API_KEY,
  modelId: 'gpt-4o',
});
agent = new Agent({ model: openaiModel });
response = await agent.invoke('What can you help me with?');

Consulte a documentação do Strands sobre provedores de modelo para mais opções de configuração.

Consumindo Servidores MCP

Você pode adicionar ferramentas de servidores MCP ao seu agente Strands.

Para consumir Servidores MCP que você criou usando os geradores py#mcp-server ou ts#mcp-server, você pode usar o gerador connection.

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 do Strands.

Mais

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

Servidor A2A (protocolo A2A)

O index.ts gerado monta o Strands A2A Express Server em um aplicativo Express para que o agente gerado exponha os endpoints do protocolo A2A junto com uma verificação de saúde /ping. 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.ts para alterar ferramentas ou o prompt do sistema. Os agentes A2A escutam na porta 9000 (vs 8080 para HTTP), para a qual o Dockerfile e a infraestrutura gerados já estão configurados.

Servidor AG-UI (protocolo AG-UI)

O index.ts gerado envolve seu Agent Strands em um @ag-ui/aws-strands StrandsAgent e cria um aplicativo Express via createStrandsApp(). O aplicativo resultante 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.

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

A maioria dos usuários não precisará modificar index.ts — edite agent.ts para alterar ferramentas ou o prompt do sistema. Os agentes AG-UI escutam na porta 8080 (igual ao HTTP), para a qual o Dockerfile e a infraestrutura gerados já estão configurados.

Executando Seu Agent

Desenvolvimento Local

Para executar seu Agent (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 tsx --watch para reiniciar automaticamente o servidor quando os arquivos mudam. O agente estará disponível em http://localhost:8081 (ou a porta atribuída se você tiver vários agentes).

Conversar com Seu Agent

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. Você pode personalizá-lo conforme evolui a forma de entrada do agente. 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).

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 do aplicativo 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 com IAM, as solicitaçõ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 com Cognito, forneça um token de acesso Cognito via 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 Agent 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]
}

Target Bundle

O gerador configura automaticamente um target bundle que usa Rolldown para criar um pacote de implantação:

pnpm nx bundle <project-name>

yarn nx bundle <project-name>

npx nx bundle <project-name>

bunx nx bundle <project-name>

A configuração do Rolldown pode ser encontrada em rolldown.config.ts, com uma entrada por pacote a ser gerado. O Rolldown gerencia a criação de múltiplos pacotes em paralelo, se definidos.

O target bundle usa index.ts como ponto de entrada para o servidor WebSocket a ser hospedado no Bedrock AgentCore Runtime.

Target Docker

O gerador configura um target <your-agent-name>-docker que copia o Dockerfile do diretório de origem do seu agente para o diretório de saída do bundle. Isso coloca o Dockerfile junto com os artefatos empacotados, permitindo que o CDK construa a imagem Docker diretamente usando AgentRuntimeArtifact.fromAsset.

Um target docker também é gerado, que prepara o contexto docker para todos os agentes se você tiver vários definidos.

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 CloudWatch, selecionando “GenAI Observability” no menu. Observe 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 controla como seu agente persiste o estado da conversa (histórico de mensagens, estado de ferramentas, 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 via a mesma chave. A função IAM do agente recebe acesso de leitura/gravação/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 de 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.ts gerado, que exporta uma função getSessionManager() resolvendo um SessionManager para a sessão atual.

O ID da sessão em si vem da sessão do AgentCore Runtime (propagado via cabeçalho x-amzn-bedrock-agentcore-runtime-session-id para A2A/AG-UI, ou o contexto de conexão WebSocket para HTTP/tRPC) e é vinculado a um contexto baseado em AsyncLocalStorage para que getCurrentSessionId() possa resolvê-lo em qualquer lugar na solicitação — incluindo em quaisquer clientes MCP ou A2A downstream conectados via gerador connection, para que toda a cadeia de chamadas compartilhe uma sessão consistente.

Invocando seu Agent

A comunicação do agente é transmitida via tRPC sobre WebSocket. Como tal, é recomendado usar a fábrica de cliente com segurança de tipos gerada em client.ts.

Invocar o Servidor Local

Você pode invocar um agente em execução local usando o método de fábrica .local da fábrica de cliente.

Você pode, por exemplo, criar um arquivo chamado scripts/test.ts em seu workspace que importa o cliente:

import { AgentClient } from '../packages/<project>/src/agent/client.js';

const client = AgentClient.local({ url: 'http://localhost:8081/ws' });

client.invoke.subscribe({ prompt: 'what is 1 plus 1?' }, { onData: console.log });

Execute com tsx como uma maneira rápida de testar seu agente.

pnpm tsx scripts/test.ts

yarn tsx scripts/test.ts

npx tsx scripts/test.ts

bunx tsx scripts/test.ts

Invocar o Agent 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.

NodeJS

O arquivo client.ts gerado inclui uma fábrica de cliente com segurança de tipos que pode ser usada para invocar seu agente implantado.

IAM
Cognito

Autenticação IAM

Você pode invocar seu agente implantado passando seu ARN para o método de fábrica withIamAuth:

import { AgentClient } from './agent/client.js';

const client = AgentClient.withIamAuth({
  agentRuntimeArn: 'arn:aws:bedrock-agentcore:us-west-2:123456789012:runtime/my-agent',
});

client.invoke.subscribe({ prompt: 'what is 1 plus 1?' }, {
  onData: (message) => console.log(message),
  onError: (error) => console.error(error),
  onComplete: () => console.log('Done'),
});

Autenticação JWT / Cognito

Use o método de fábrica withJwtAuth para autenticar com o token de acesso JWT / Cognito.

const client = AgentClient.withJwtAuth({
  agentRuntimeArn: 'arn:aws:bedrock-agentcore:us-west-2:123456789012:runtime/my-agent',
  accessTokenProvider: async () => `<access-token>`,
});

client.invoke.subscribe({ prompt: 'what is 1 plus 1?' }, {
  onData: console.log,
});

O accessTokenProvider deve retornar o token usado para autenticar a solicitação. Você pode, por exemplo, obter um token dentro deste método para garantir que credenciais atualizadas sejam reutilizadas quando o tRPC reiniciar uma conexão WebSocket. O exemplo abaixo demonstra o uso do AWS SDK para obter o token do Cognito:

import { CognitoIdentityProvider } from "@aws-sdk/client-cognito-identity-provider";

const cognito = new CognitoIdentityProvider();

const jwtClient = AgentClient.withJwtAuth({
  agentRuntimeArn: 'arn:aws:bedrock-agentcore:us-west-2:123456789012:runtime/my-agent',
  accessTokenProvider: async () => {
    const response = await cognito.adminInitiateAuth({
      UserPoolId: '<user-pool-id>',
      ClientId: '<user-pool-client-id>',
      AuthFlow: 'ADMIN_NO_SRP_AUTH',
      AuthParameters: {
        USERNAME: '<username>',
        PASSWORD: '<password>',
      },
    });
    return response.AuthenticationResult!.AccessToken!;
  },
});

Navegador / Site React

Para invocar seu Agent de um site React, você pode usar o gerador connection, que configura automaticamente um cliente tRPC WebSocket 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 Agent 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 de destino e transforma por AST o agent.ts deste agente para registrar o agente A2A remoto como uma tool Strands.

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 Agent AG-UI

Para invocar seu agente AG-UI de um site React, use o gerador connection, que configura 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 Agent

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:

import { Agent } from '@strands-agents/sdk';
import { BedrockModel } from '@strands-agents/sdk/models/bedrock';

const model = new BedrockModel({
  modelId: process.env.MODEL_ID,
  guardrailConfig: {
    guardrailIdentifier: process.env.GUARDRAIL_ID!,
    guardrailVersion: process.env.GUARDRAIL_VERSION ?? 'DRAFT',
  },
});

const agent = new Agent({ model, /* ... */ });

Consulte o guia Guardrails do Strands para mais detalhes.

Conexões

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

React to TypeScript AgentCall a TypeScript Agent from a React website

React to AG-UI AgentCall an Agent exposing the AG-UI protocol from a React website via CopilotKit

TypeScript Agent to MCPConnect a TypeScript Agent to an MCP server

TypeScript Agent to A2A AgentConnect a TypeScript Agent to a remote A2A agent

Python Agent to A2A AgentConnect a Python Agent to a remote A2A agent

TypeScript Agent to Relational DatabaseConnect a TypeScript Agent to an Aurora relational database

TypeScript Agent to TypeScript DynamoDBConnect a TypeScript Agent to a DynamoDB table

TypeScript Agent to AgentCore GatewayConnect a TypeScript Agent to an AgentCore Gateway

AgentCore Gateway to AgentFront an agent with an AgentCore Gateway as a runtime target