Agente TypeScript Strands

Gere um Strands Agent TypeScript para construir agentes de IA com ferramentas e, opcionalmente, implante-o no Amazon Bedrock AgentCore Runtime. O gerador usa tRPC sobre WebSocket para aproveitar o suporte de streaming bidirecional do AgentCore para comunicação em tempo real com segurança de tipo.

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 em escala
• Agnóstico de modelo e provedor: Suporta muitos modelos diferentes de vários provedores
• Ferramentas orientadas 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 Strands Agent

Você pode gerar um Strands Agent TypeScript de duas maneiras:

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 - ts#strands-agent
5. Preencha os parâmetros obrigatórios
6. Clique em Generate

CLI

pnpm

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

yarn

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

npm

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

bun

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

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

pnpm

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

yarn

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

npm

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

bun

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

Pré-requisito do projeto

Primeiro use o gerador ts#project para criar um projeto ao qual adicionar seu Strands Agent.

Opções

Parâmetro	Tipo	Padrão	Descrição
project Obrigatório	string	-	O projeto ao qual adicionar o Strands Agent
computeType	string	BedrockAgentCoreRuntime	O tipo de computação para hospedar seu Strands Agent.
name	string	-	O nome do seu Strands Agent (padrão: agent)
auth	string	IAM	O método usado para autenticar com seu Strands Agent. Escolha entre IAM (padrão) ou Cognito.
iacProvider	string	Inherit	O provedor de IaC preferido. Por padrão, isso é herdado da sua seleção inicial.

Saída do Gerador

O gerador adicionará os seguintes arquivos ao seu projeto TypeScript existente:

• Directoryyour-project/

  • Directorysrc/

    • Directoryagent/ (ou nome personalizado se especificado)

      • index.ts Ponto de entrada para Bedrock AgentCore Runtime
      • init.ts Inicialização do tRPC
      • router.ts Roteador tRPC com procedimentos de agente
      • agent.ts Definição principal do agente com ferramentas de exemplo
      • client.ts Cliente fornecido para invocar seu agente
      • agent-core-trpc-client.ts Fábrica de cliente para conectar a agentes no AgentCore Runtime
      • Dockerfile Ponto de entrada para hospedar seu agente (excluído quando computeType está definido como None)
  • package.json Atualizado com dependências do Strands
  • project.json Atualizado com destinos de servir do agente

Infraestrutura

Implantação serverless

Se você selecionou None para computeType, o gerador não fornecerá nenhuma infraestrutura como código.

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 Strands Agent, os seguintes arquivos são gerados:

CDK

• Directorypackages/common/constructs/src

  • Directoryapp

    • Directoryagents

      • Directory<project-name>

        • <project-name>.ts Construto CDK para implantar seu agente
        • Dockerfile Arquivo docker passthrough usado pelo construto CDK

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 implantar no Bedrock AgentCore Runtime

Trabalhando com seu Strands Agent

tRPC sobre WebSocket

O Strands Agent TypeScript usa tRPC sobre WebSocket, aproveitando o suporte de streaming bidirecional do AgentCore para permitir comunicação em tempo real com segurança de tipo 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 assinatura 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 (sessionId: string) => {
  return new Agent({
    systemPrompt: 'You are a helpful assistant with access to various tools.',
    tools: [letterCounter],
  });
};

O framework Strands trata automaticamente:

• Validação de entrada usando esquemas Zod
• Geração de esquema JSON para chamada de ferramenta
• 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 alternar facilmente 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 fazer uso do gerador connection.

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

Mais

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

Executando seu Strands Agent

Desenvolvimento Local

O gerador configura um destino chamado <your-agent-name>-serve, que inicia seu Strands Agent localmente para desenvolvimento e testes.

pnpm

pnpm nx agent-serve your-project

yarn

yarn nx agent-serve your-project

npm

npx nx agent-serve your-project

bun

bunx nx agent-serve your-project

Este comando 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 múltiplos agentes).

Implantando seu Strands Agent no Bedrock AgentCore Runtime

Infraestrutura como Código

Se você selecionou BedrockAgentCoreRuntime para computeType, a infraestrutura CDK ou Terraform relevante é gerada, que você pode usar para implantar seu Strands 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) {
    // Add the agent to your stack
    const agent = new MyProjectAgent(this, 'MyProjectAgent');

    // Grant permissions to invoke the relevant models in bedrock
    agent.agentCoreRuntime.addToRolePolicy(
      new PolicyStatement({
        actions: [
          'bedrock:InvokeModel',
          'bedrock:InvokeModelWithResponseStream',
        ],
        // You can scope the below down to the specific models you use
        resources: [
          'arn:aws:bedrock:*:*:foundation-model/*',
          'arn:aws:bedrock:*:*:inference-profile/*',
        ],
      }),
    );
  }
}

Construto CDK Alpha

Este construto usa o módulo @aws-cdk/aws-bedrock-agentcore-alpha.

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.

Você pode usar este módulo terraform em um projeto 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"

  # Grant permissions to invoke the relevant models in bedrock
  additional_iam_policy_statements = [
    {
      Effect = "Allow"
      Action = [
        "bedrock:InvokeModel",
        "bedrock:InvokeModelWithResponseStream"
      ]
      # You can scope the below down to the specific models you use
      Resource = [
        "arn:aws:bedrock:*:*:foundation-model/*",
        "arn:aws:bedrock:*:*:inference-profile/*"
      ]
    }
  ]
}

Docker necessário

Docker é necessário para construir e implantar seu Strands 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 Strands Agent. Você pode escolher entre autenticação IAM (padrão) ou Cognito ao gerar seu agente.

IAM

Por padrão, seu Strands 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"
}

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#react-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"

  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.

Destino Bundle

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

pnpm

pnpm nx bundle <project-name>

yarn

yarn nx bundle <project-name>

npm

npx nx bundle <project-name>

bun

bunx nx bundle <project-name>

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

Configuração personalizada

Você pode ajustar a configuração do Rolldown em rolldown.config.ts. Por exemplo, se tiver dependências que dependem de caminhos de arquivo e não podem ser empacotadas, você pode adicioná-las à lista de módulos external.

O destino bundle usa index.ts como ponto de entrada para o servidor WebSocket hospedar no Bedrock AgentCore Runtime.

Destino Docker

O gerador configura um destino <your-agent-name>-docker que executa o servidor WebSocket empacotado na porta 8080 conforme o contrato de runtime do AgentCore.

Tags de imagem Docker

A imagem docker é construída usando uma tag (por exemplo my-scope-my-project-agent:latest), que é referenciada pela sua infraestrutura CDK ou Terraform, permitindo que seu Dockerfile seja co-localizado com seu projeto Strands Agent.

Um destino docker também é gerado que executa o docker build para todos os agentes se você tiver múltiplos definidos.

Observabilidade

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

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

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

Invocando seu Strands Agent

A comunicação do agente é transmitida via tRPC sobre WebSocket. Como tal, é recomendado usar a fábrica de cliente com segurança de tipo 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:

scripts/test.ts

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

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

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

Teste rápido

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

pnpm

pnpm tsx scripts/test.ts

yarn

yarn tsx scripts/test.ts

npm

npx tsx scripts/test.ts

bun

bunx tsx scripts/test.ts

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

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.

NodeJS

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

Autenticação por cabeçalhos HTTP

A fábrica de cliente usa cabeçalhos HTTP no handshake do WebSocket para autenticar solicitações ao Bedrock AgentCore Runtime. Isso não é possível em um navegador e, portanto, este cliente não é adequado para ambientes de navegador. Consulte a seção “Browser / React Website” abaixo para detalhes sobre invocação a partir de um navegador.

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({ message: 'what is 1 plus 1?' }, {
  onData: (message) => console.log(message),
  onError: (error) => console.error(error),
  onComplete: () => console.log('Done'),
});

Credenciais AWS

Isso usará a cadeia de provedores de credenciais AWS padrão para autenticar solicitações, portanto o ambiente no qual o código acima é executado deve ter credenciais AWS configuradas, com acesso para invocar o runtime.

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({ message: '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!;
  },
});

Browser / React Website

Para invocar seu Strands Agent a partir de um site React, você pode fazer uso do gerador connection, que configura automaticamente um cliente tRPC WebSocket 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.