Pular para o conteúdo
@aws/nx-plugin
Blog

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?

Seção intitulada “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

Seção intitulada “Uso”

Gerar um Agent

Seção intitulada “Gerar um Agent”

Você pode gerar um TypeScript Agent de duas maneiras:

Execute este gerador@aws/nx-plugin:ts#agent

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

Obrigatório

infra = agentcore | agentcore-ecr

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

Opções

Seção intitulada “Opções”
Opções do gerador9 opções
projectObrigatóriostring

O projeto ao qual adicionar o Agent

frameworkenumPadrão: strands

O SDK do agente a ser usado.

strands
authenuminfra = agentcore | agentcore-ecrPadrão: iam

O método usado para autenticar com seu Agent. Aplicável apenas quando infra está definido (ignorado quando infra é none).

iamcognito
protocolenumPadrão: 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.

httpa2aag-ui
iacenumPadrão: inherit

O provedor IaC preferido. Por padrão, isso é herdado da sua seleção inicial.

inheritcdkterraform
infraenumPadrão: agentcore

O tipo de infraestrutura para hospedar seu Agent. agentcore implanta seu código como um zip em um runtime gerenciado pelo AgentCore para o ciclo de build e deploy mais rápido. agentcore-ecr constrói e hospeda uma imagem de contêiner, para controle em nível de sistema operacional ou um pipeline de contêiner estabelecido.

agentcoreagentcore-ecrnone
sessionenumPadrão: s3

O armazenamento usado para persistir a sessão do seu Agent.

s3in-memory
namestring

O nome do seu Agent (padrão: agent)

preferInstallDependenciesbooleanPadrão: 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

Seção intitulada “Saída do Gerador”

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

protocol = http

Protocolo HTTP (padrão)

Seção intitulada “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
        • Directoryschema/
          • z-async-iterable.ts Zod schema for the router’s streamed responses
        • client.ts Vended client for invoking your agent
        • agent-core-trpc-client.ts Client factory for connecting to agents on AgentCore Runtime
        • Dockerfile Container image definition (only when infra is agentcore-ecr)
    • package.json Updated with Strands dependencies
    • project.json Updated with agent serve targets
protocol = a2a

Protocolo A2A

Seção intitulada “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
        • Directorymiddleware/
          • session-id-middleware.ts Binds the inbound AgentCore session ID for the request
        • Dockerfile Container image definition (only when infra is agentcore-ecr)
    • package.json Updated with Strands and Express dependencies
    • project.json Updated with agent serve targets
protocol = ag-ui

Protocolo AG-UI

Seção intitulada “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
        • Directorymiddleware/
          • session-id-middleware.ts Binds the inbound AgentCore session ID for the request
        • Dockerfile Container image definition (only when infra is agentcore-ecr)
    • package.json Updated with Strands and AG-UI dependencies
    • project.json Updated with agent serve targets

Infraestrutura

Seção intitulada “Infraestrutura”

A opção infra seleciona como seu código é empacotado e hospedado no Amazon Bedrock AgentCore Runtime:

  • agentcore (padrão) usa implantação direta de código: seu código compilado é empacotado como um .zip, enviado para o S3 e executado em um runtime de linguagem gerenciado pelo AgentCore. Não há imagem de contêiner para construir, nenhum repositório ECR para gerenciar e nenhuma imagem para enviar, o que resulta em um ciclo de compilação e implantação substancialmente mais rápido.
  • agentcore-ecr constrói uma imagem de contêiner arm64 a partir de um Dockerfile fornecido e a hospeda no registro compartilhado core/asset-ecr, juntamente com todos os outros contêineres no workspace. Escolha esta opção quando você precisar de controle sobre a imagem do sistema operacional — por exemplo, para instalar bibliotecas nativas do sistema — ou quando você tiver um pipeline de contêiner estabelecido. Esta opção também fornece um alvo de varredura de imagem Trivy (veja Varredura de Imagem abaixo).
  • none não gera nenhuma infraestrutura, então o projeto só pode ser executado localmente.
infra = agentcore | agentcore-ecr

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:

  • 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

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

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

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.

Arquitetura

Seção intitulada “Arquitetura”

Quando implantado no Bedrock AgentCore Runtime, o código do seu agente é empacotado como um zip e executado no runtime gerenciado do AgentCore. 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.

Loading the diagram…

Trabalhando com Seu Agent

Seção intitulada “Trabalhando com Seu Agent”

Protocolo

Seção intitulada “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.

protocol = http

tRPC sobre WebSocket (protocolo HTTP)

Seção intitulada “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

Seção intitulada “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

Seção intitulada “Configuração de Modelo”

Por padrão, os agentes Strands usam Claude Sonnet 4.6 no Amazon Bedrock, 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

Seção intitulada “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.

Execute este gerador@aws/nx-plugin:connection

pnpm nx g @aws/nx-plugin:connection
Monte seu comando5

Obrigatório

Obrigatório

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

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

Seção intitulada “Mais”

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

protocol = a2a

Servidor A2A (protocolo A2A)

Seção intitulada “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. A URL anunciada no cartão do agente vem da variável de ambiente AGENTCORE_RUNTIME_URL, retornando para http://localhost:<port>/ para desenvolvimento local.

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 a infraestrutura gerada já está configurada.

protocol = ag-ui

Servidor AG-UI (protocolo AG-UI)

Seção intitulada “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. 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 a infraestrutura gerada já está configurada.

Executando Seu Agent

Seção intitulada “Executando Seu Agent”

Desenvolvimento Local

Seção intitulada “Desenvolvimento Local”

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

Terminal window
pnpm 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:

Terminal window
pnpm 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 — leia-a de metadata.ports no project.json do projeto).

Um target <your-agent-name>-serve também é gerado, que executa o agente contra sua infraestrutura implantada e, portanto, requer que RUNTIME_CONFIG_APP_ID seja definido. Consulte o guia Desenvolvimento Local para a diferença entre dev e serve.

Conversar com Seu Agent

Seção intitulada “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):

Terminal window
pnpm nx agent-dev your-project

Em seguida, em outro terminal, inicie o chat:

Terminal window
pnpm 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).

infra = agentcore | agentcore-ecr

Conversar com seu agente implantado

Seção intitulada “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:

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:

Terminal window
RUNTIME_CONFIG_APP_ID=<app-id> pnpm nx run your-project:agent-chat
infra = agentcore | agentcore-ecr

Implantando Seu Agent no Bedrock AgentCore Runtime

Seção intitulada “Implantando Seu Agent no Bedrock AgentCore Runtime”

Infraestrutura como Código

Seção intitulada “Infraestrutura como Código”

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

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

Autenticação

Seção intitulada “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

Seção intitulada “IAM”

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

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

Autenticação Cognito

Seção intitulada “Autenticação Cognito”

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

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.

Target Bundle

Seção intitulada “Target Bundle”

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

Terminal window
pnpm 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.

infra = agentcore

Target Package

Seção intitulada “Target Package”

O gerador configura um target <your-agent-name>-package que monta o pacote de código implantável: o index.js empacotado mais uma instalação vendorizada do AWS Distro for OpenTelemetry, que o AgentCore requer estar presente no pacote. A infraestrutura gerada faz upload deste diretório como um .zip — via AgentRuntimeArtifact.fromCodeAsset no CDK, ou arquivado no bucket de ativos compartilhado no Terraform.

infra = agentcore-ecr

Target Docker

Seção intitulada “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

Seção intitulada “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. A verificação não é armazenada em cache, pois a imagem que ela lê reside no mecanismo de contêiner em vez de no disco — então ela sempre verifica a imagem real e falha de forma explícita em vez de relatar uma aprovação em cache para uma imagem que não está mais lá. Cada execução, portanto, leva dezenas de segundos por imagem e atualiza o banco de dados de vulnerabilidades do Trivy, então ela precisa de acesso à rede. O script raiz trivy fornecido verifica todas as imagens no workspace:

Terminal window
pnpm trivy

Suprimindo Descobertas do Trivy

Seção intitulada “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):

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

Seção intitulada “Observabilidade”

Seu agente é automaticamente configurado com observabilidade usando o AWS Distro for Open Telemetry (ADOT).

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

Seção intitulada “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.

Restringindo sessões ao seu proprietário

Seção intitulada “Restringindo sessões ao seu proprietário”

O ID da sessão chega do chamador, então por si só ele identifica uma conversa, mas não a quem a conversa pertence. O AgentCore Runtime autoriza uma invocação contra o ARN do recurso de runtime do agente em vez de contra uma sessão individual, o que deixa o agente livre para decidir o que uma sessão significa para sua aplicação.

Para restringir cada usuário às suas próprias conversas:

  1. Adicione uma API para criar uma sessão, usando tRPC, FastAPI ou Smithy. Gere um ID de sessão opaco (pelo menos 33 caracteres) e armazene-o junto com o ID do usuário chamador — por exemplo, em uma tabela criada com o gerador ts#dynamodb. Cada guia de API mostra como recuperar o ID do usuário chamador.
  2. Em seu agente, procure o ID de usuário armazenado para o ID de sessão que foi fornecido e rejeite a solicitação quando ele não corresponder ao chamador. Com auth=cognito, o JWT do chamador chega ao código do seu agente, então sua claim sub os identifica.

Gere o ID da sessão em vez de derivá-lo de valores fornecidos pelo usuário, como um nome de conversa — qualquer coisa que um chamador possa prever, um chamador pode enviar.

Invocando seu Agent

Seção intitulada “Invocando seu Agent”
protocol = http

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

Seção intitulada “Invocar o Servidor Local”

Inicie seu agente com o target <your-agent-name>-dev:

Terminal window
pnpm nx agent-dev your-project

Em seguida, invoque-o 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:

A classe do cliente é nomeada após seu agente, então um agente chamado my-agent exporta MyAgentClient.

scripts/test.ts
import { MyAgentClient } from '../packages/<project>/src/agent/client.js';


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


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

Substitua a porta atribuída ao seu agente — leia-a de metadata.ports no project.json do projeto.

Invocar o Agent Implantado

Seção intitulada “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:

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

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.

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 forma exata de invocar esta URL depende do método de autenticação usado.

NodeJS

Seção intitulada “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.

Autenticação IAM
Seção intitulada “Autenticação IAM”

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

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


const client = MyAgentClient.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'),
});

Navegador / Site React

Seção intitulada “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).

Execute este gerador@aws/nx-plugin:connection

pnpm nx g @aws/nx-plugin:connection
Monte seu comando5

Obrigatório

Obrigatório

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

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

protocol = a2a

Invocando um Agent A2A como Ferramenta

Seção intitulada “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.

Execute este gerador@aws/nx-plugin:connection

pnpm nx g @aws/nx-plugin:connection
Monte seu comando5

Obrigatório

Obrigatório

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

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

protocol = ag-ui

Invocando um Agent AG-UI

Seção intitulada “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).

Execute este gerador@aws/nx-plugin:connection

pnpm nx g @aws/nx-plugin:connection
Monte seu comando5

Obrigatório

Obrigatório

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

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

Protegendo seu Agent

Seção intitulada “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

Seção intitulada “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

Seção intitulada “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

Seção intitulada “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

Seção intitulada “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

Seção intitulada “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:

agent.ts
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

Seção intitulada “Conexões”

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

Strands AgentsTypeScript
React to TypeScript AgentCall a TypeScript Agent from a React website
CopilotKit
React to AG-UI AgentCall an Agent exposing the AG-UI protocol from a React website via CopilotKit
Strands AgentsTypeScriptModel Context Protocol
TypeScript Agent to MCPConnect a TypeScript Agent to an MCP server
Strands AgentsTypeScriptAgent2Agent
TypeScript Agent to A2A AgentConnect a TypeScript Agent to a remote A2A agent
Strands AgentsPythonAgent2Agent
Python Agent to A2A AgentConnect a Python Agent to a remote A2A agent
Strands AgentsTypeScriptAmazon Aurora
TypeScript Agent to Relational DatabaseConnect a TypeScript Agent to an Aurora relational database
Strands AgentsTypeScriptAmazon DynamoDB
TypeScript Agent to TypeScript DynamoDBConnect a TypeScript Agent to a DynamoDB table
Strands AgentsTypeScriptAmazon Bedrock AgentCore Gateway
TypeScript Agent to AgentCore GatewayConnect a TypeScript Agent to an AgentCore Gateway
Amazon Bedrock AgentCore GatewayStrands Agents
AgentCore Gateway to AgentFront an agent with an AgentCore Gateway as a runtime target