跳转到内容
@aws/nx-plugin
Blog

TypeScript Agent

生成用于构建带工具的 AI 代理的 TypeScript Strands Agent，并可选择将其部署到 Amazon Bedrock AgentCore Runtime。默认情况下，生成器使用基于 WebSocket 的 tRPC 来利用 AgentCore 的双向流支持，实现实时、类型安全的通信。或者，您可以选择 Agent-to-Agent (A2A) 协议以与其他兼容 A2A 的代理互操作，或选择 AG-UI 协议通过 CopilotKit 直接集成前端。

什么是 Strands？

Section titled “什么是 Strands？”

Strands 是一个用于构建 AI 代理的轻量级框架。主要特性包括：

  • 轻量且可定制：简单的代理循环，不会妨碍您的工作
  • 生产就绪：完整的可观测性、追踪和大规模部署选项
  • 模型和提供商无关：支持来自各种提供商的多种不同模型
  • 社区驱动的工具：强大的社区贡献工具集
  • 多代理支持：高级技术，如代理团队和自主代理
  • 灵活的交互模式：支持对话式、流式和非流式

使用方法

Section titled “使用方法”

生成 Agent

Section titled “生成 Agent”

您可以通过两种方式生成 TypeScript Agent：

运行此生成器@aws/nx-plugin:ts#agent

pnpm nx g @aws/nx-plugin:ts#agent
构建你的命令9

必需

infra = agentcore | agentcore-ecr

您还可以执行试运行以查看哪些文件会被更改

选项

Section titled “选项”
生成器选项9 个选项
project必需string

要添加 Agent 的项目

frameworkenum默认值: strands

要使用的代理 SDK。

strands
authenuminfra = agentcore | agentcore-ecr默认值: iam

用于对 Agent 进行身份验证的方法。仅在设置了 infra 时适用（当 infra 为 none 时忽略）。

iamcognito
protocolenum默认值: http

Agent 的服务器协议。HTTP 公开 tRPC/WebSocket 服务器。A2A 公开 Agent-to-Agent 协议服务器。AG-UI 公开 AG-UI 协议服务器，用于与 CopilotKit 的前端直接集成。

httpa2aag-ui
iacenum默认值: inherit

首选的 IaC 提供商。默认情况下，这继承自您的初始选择。

inheritcdkterraform
infraenum默认值: agentcore

托管 Agent 的基础设施类型。agentcore 将您的代码以 zip 形式部署到 AgentCore 托管的运行时，以实现最快的构建和部署周期。agentcore-ecr 则构建并托管容器镜像，适用于需要操作系统级控制或已有容器流水线的场景。

agentcoreagentcore-ecrnone
sessionenum默认值: s3

用于持久化 Agent 会话的存储。

s3in-memory
namestring

Agent 的名称（默认：agent）

preferInstallDependenciesboolean默认值: true

是否在生成器运行后优先安装依赖项。设置为 false 可在批量运行多个生成器时延迟安装（如果后续生成器需要计算 Nx 项目图，仍会运行安装）；在最后统一安装一次。

生成器输出

Section titled “生成器输出”

生成器将向您现有的 TypeScript 项目添加以下文件。生成的文件取决于所选的 protocol：

protocol = http

HTTP 协议（默认）

Section titled “HTTP 协议（默认）”
  • 文件夹your-project/
    • 文件夹src/
      • 文件夹agent/ (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
        • 文件夹schema/
          • 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

A2A 协议

Section titled “A2A 协议”

入口点使用 Strands A2A Express Server 而不是 tRPC：

  • 文件夹your-project/
    • 文件夹src/
      • 文件夹agent/ (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
        • 文件夹middleware/
          • 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

AG-UI 协议

Section titled “AG-UI 协议”

入口点使用 @ag-ui/aws-strands 通过 AG-UI 协议（基于 POST 的 SSE）公开代理，与 CopilotKit 兼容：

  • 文件夹your-project/
    • 文件夹src/
      • 文件夹agent/ (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
        • 文件夹middleware/
          • 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

基础设施

Section titled “基础设施”

infra 选项用于选择如何在 Amazon Bedrock AgentCore Runtime 上打包和托管您的代码：

  • agentcore（默认）使用直接代码部署：您构建的代码被打包为 .zip 文件，上传到 S3，并在 AgentCore 托管的语言运行时上运行。无需构建容器镜像，无需管理 ECR 存储库，也无需推送镜像，这使得构建和部署周期大大加快。
  • agentcore-ecr 从提供的 Dockerfile 构建 arm64 容器镜像，并从共享的 core/asset-ecr 注册表托管，与工作区中的所有其他容器一起。当您需要控制操作系统镜像时（例如安装原生系统库），或者当您有已建立的容器管道时，请选择此选项。此选项还提供 Trivy 镜像扫描目标（请参阅下面的镜像扫描）。
  • none 完全不生成基础设施，因此项目只能在本地运行。
infra = agentcore | agentcore-ecr

由于此生成器根据您选择的 iac 提供基础设施即代码，它将在 packages/common 中创建一个项目，其中包含相关的 CDK 构造或 Terraform 模块。

通用基础设施即代码项目的结构如下：

  • 文件夹packages/common/constructs
    • 文件夹src
      • 文件夹app/ Constructs for infrastructure specific to a project/generator
        • …
      • 文件夹core/ Generic constructs which are reused by constructs in app
        • …
      • index.ts Entry point exporting constructs from app
    • project.json Project build targets and configuration

为了部署您的 Agent，将生成以下文件：

  • 文件夹packages/common/constructs/src
    • 文件夹app
      • 文件夹agents
        • 文件夹<agent-name>
          • <agent-name>.ts CDK construct for deploying your agent
infra = none

如果您为 infra 选择了 none，则不会生成 CDK 构造或 Terraform 模块 — Agent 只能在本地运行。在此模式下，auth 选项将被忽略，因为没有需要进行身份验证的托管端点。

架构

Section titled “架构”

当部署到 Bedrock AgentCore Runtime 时,您的 agent 代码会被打包为 zip 文件并在 AgentCore 托管运行时中运行。客户端调用 AgentCore Runtime 数据平面端点,该端点将请求转发到您的 agent。agent 调用 Amazon Bedrock 进行模型推理,并可能调用工具、MCP 服务器或下游 API。

Loading the diagram…

使用您的 Agent

Section titled “使用您的 Agent”

协议

Section titled “协议”

您的代理的服务器协议决定了它如何通信。您可以在以下选项之间进行选择：

  • HTTP（默认）：使用基于 WebSocket 的 tRPC 进行实时、类型安全的通信。最适合自定义客户端集成和对代理 API 的细粒度控制。
  • A2A：使用 Agent-to-Agent (A2A) 协议进行标准化的代理间通信。最适合您的代理需要被其他兼容 A2A 的代理发现和调用的情况。
  • AG-UI：通过 @ag-ui/aws-strands 使用 AG-UI 协议（基于 POST 的 SSE）与 CopilotKit 直接集成前端。最适合您想要具有流式传输、工具调用可视化和状态管理的丰富聊天 UI 的情况。

协议在 CDK/Terraform 基础设施中设置，并相应地生成应用程序代码。

protocol = http

基于 WebSocket 的 tRPC（HTTP 协议）

Section titled “基于 WebSocket 的 tRPC（HTTP 协议）”

TypeScript Agent 使用基于 WebSocket 的 tRPC，利用 AgentCore 的双向流支持，在客户端和您的代理之间实现实时、类型安全的通信。

由于 tRPC 支持通过 WebSocket 进行 Query、Mutation 和 Subscription 过程，您可以定义任意数量的过程。默认情况下，在 router.ts 中为您定义了一个名为 invoke 的单个订阅过程。

添加工具

Section titled “添加工具”

工具是 AI 代理可以调用以执行操作的函数。您可以在 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],
  });
};

Strands 框架会自动处理：

  • 使用 Zod 模式进行输入验证
  • 为工具调用生成 JSON 模式
  • 错误处理和响应格式化

模型配置

Section titled “模型配置”

默认情况下，Strands 代理在 Amazon Bedrock 上使用 Claude Sonnet 4.6，但您可以轻松地在模型提供商之间切换：

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

有关更多配置选项，请参阅 Strands 关于模型提供商的文档。

使用 MCP 服务器

Section titled “使用 MCP 服务器”

您可以从 MCP 服务器添加工具到您的 Strands 代理。

对于使用 py#mcp-server 或 ts#mcp-server 生成器创建的 MCP 服务器，您可以使用 connection 生成器。

运行此生成器@aws/nx-plugin:connection

pnpm nx g @aws/nx-plugin:connection
构建你的命令5

必需

必需

您还可以执行试运行以查看哪些文件会被更改

有关如何设置连接的详细信息，请参阅 connection 生成器指南。

对于其他 MCP 服务器，请参阅 Strands 文档。

更多

Section titled “更多”

有关编写 Strands 代理的更深入指南，请参阅 Strands 文档。

protocol = a2a

A2A 服务器（A2A 协议）

Section titled “A2A 服务器（A2A 协议）”

生成的 index.ts 将 Strands A2A Express Server 挂载到 Express 应用程序上，因此生成的代理会公开 A2A 协议端点以及 /ping 健康检查。代理卡中公布的 URL 来自 AGENTCORE_RUNTIME_URL 环境变量，对于本地开发则回退到 http://localhost:<port>/。

大多数用户不需要修改此文件 — 编辑 agent.ts 以更改工具或系统提示。A2A 代理监听端口 9000（而 HTTP 为 8080），生成的基础设施已经为此进行了配置。

protocol = ag-ui

AG-UI 服务器（AG-UI 协议）

Section titled “AG-UI 服务器（AG-UI 协议）”

生成的 index.ts 将您的 Strands Agent 包装在 @ag-ui/aws-strands StrandsAgent 中，并构建一个 Express 应用程序。生成的应用程序公开一个单一的 POST 端点，通过服务器发送事件（SSE）流式传输 AG-UI 事件，以及用于 AgentCore 运行时健康检查的 /ping。

AG-UI 代理旨在直接由前端使用。使用 connection 生成器将您的 React 网站与代理连接，使用 CopilotKit 提供程序和 AG-UI HttpAgent 客户端。

大多数用户不需要修改 index.ts — 编辑 agent.ts 以更改工具或系统提示。AG-UI 代理监听端口 8080（与 HTTP 相同），生成的基础设施已经为此进行了配置。

运行您的 Agent

Section titled “运行您的 Agent”

本地开发

Section titled “本地开发”

要在本地运行您的 Agent（以及与其连接的所有内容），请使用项目的 dev 目标：

Terminal window
pnpm nx dev your-project

如果您已向项目添加了多个组件（代理、MCP 服务器等），这将启动所有组件。要仅运行此代理，请定位其 <your-agent-name>-dev 目标：

Terminal window
pnpm nx agent-dev your-project

这使用 tsx --watch 在文件更改时自动重启服务器。代理将在 http://localhost:8081（或如果您有多个代理，则为分配的端口 — 从项目的 project.json 中的 metadata.ports 读取）上可用。

还会生成一个 <your-agent-name>-serve 目标，它针对您已部署的基础设施运行代理，因此需要设置 RUNTIME_CONFIG_APP_ID。有关 dev 和 serve 之间的区别，请参阅本地开发指南。

与您的 Agent 聊天

Section titled “与您的 Agent 聊天”

生成器配置了一个 <your-agent-name>-chat Nx 目标，可让您进入与代理的交互式终端聊天。

聊天目标独立运行。默认情况下，它连接到您本地运行的代理，因此首先启动代理的 <your-agent-name>-dev 目标（在单独的终端中）：

Terminal window
pnpm nx agent-dev your-project

然后，在另一个终端中，启动聊天：

Terminal window
pnpm nx run your-project:agent-chat

生成器为每个协议生成一个 scripts/<your-agent-name>/chat.ts。您可以在演进代理的输入形状时对其进行自定义。默认情况下，它连接到本地代理，或者在设置了 RUNTIME_CONFIG_APP_ID 时连接到已部署的代理（请参阅下面的与已部署的代理聊天）。

infra = agentcore | agentcore-ecr

与已部署的代理聊天

Section titled “与已部署的代理聊天”

要与部署到 Bedrock AgentCore 的代理聊天，请将 RUNTIME_CONFIG_APP_ID 环境变量设置为部署的 AppConfig 应用程序 ID（由已部署的堆栈输出为 RuntimeConfigApplicationId）。聊天脚本从运行时配置解析您的代理的运行时 ARN，并连接到已部署的端点：

对于 IAM 身份验证的代理，请求使用您的默认 AWS 凭证通过 SigV4 签名。确保环境具有有权调用运行时的 AWS 凭证：

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

将您的 Agent 部署到 Bedrock AgentCore Runtime

Section titled “将您的 Agent 部署到 Bedrock AgentCore Runtime”

基础设施即代码

Section titled “基础设施即代码”

如果您为 infra 选择了 agentcore 或 agentcore-ecr，将生成相关的 CDK 或 Terraform 基础设施，您可以使用它将您的 Agent 部署到 Amazon Bedrock AgentCore Runtime。

将为您的 agent 生成一个 CDK 构造，根据您运行生成器时选择的 name 命名，或默认为 <ProjectName>Agent。

您可以在 CDK 应用程序中使用此 CDK 构造：

import { MyProjectAgent } from '@my-scope/common-constructs';


export class ExampleStack extends Stack {
  constructor(scope: Construct, id: string) {
    new MyProjectAgent(this, 'MyProjectAgent');
  }
}

身份验证

Section titled “身份验证”

生成器提供了一个 auth 选项来配置您的 Agent 的身份验证。在生成 agent 时，您可以选择 IAM（默认）或 Cognito 身份验证。

IAM

Section titled “IAM”

默认情况下，您的 Agent 将使用 IAM 身份验证进行保护，只需在不带任何参数的情况下部署它：

import { MyProjectAgent } from '@my-scope/common-constructs';


export class ExampleStack extends Stack {
  constructor(scope: Construct, id: string) {
    new MyProjectAgent(this, 'MyProjectAgent');
  }
}

您可以使用 grantInvokeAccess 方法授予在 Bedrock AgentCore Runtime 上调用您的 agent 的访问权限，例如：

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

Cognito 身份验证

Section titled “Cognito 身份验证”

当您选择 Cognito 身份验证时，生成器会将 agent 配置为使用 Cognito 进行身份验证。

生成的构造接受一个 identity 属性，用于配置 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,
    });
  }
}

UserIdentity 构造可以使用 ts#website#auth 生成器生成，或者您可以创建自己的 CDK UserPool 和 UserPoolClient。

Bundle 目标

Section titled “Bundle 目标”

生成器会自动配置一个 bundle 目标，它使用 Rolldown 来创建部署包：

Terminal window
pnpm nx bundle <project-name>

Rolldown 配置可以在 rolldown.config.ts 中找到，每个要生成的包都有一个入口。Rolldown 会管理并行创建多个包（如果已定义）。

bundle 目标使用 index.ts 作为 WebSocket 服务器的入口点，以托管在 Bedrock AgentCore Runtime 上。

infra = agentcore

Package 目标

Section titled “Package 目标”

生成器配置了一个 <your-agent-name>-package 目标，它组装可部署的代码包：打包的 index.js 加上 AWS Distro for OpenTelemetry 的供应商安装，AgentCore 要求它存在于包中。生成的基础设施将此目录上传为 .zip — 在 CDK 下通过 AgentRuntimeArtifact.fromCodeAsset，或在 Terraform 下归档到共享资产存储桶中。

infra = agentcore-ecr

Docker 目标

Section titled “Docker 目标”

生成器配置了一个 <your-agent-name>-docker 目标，它将 Dockerfile 从您的代理源目录复制到 bundle 输出目录。这将 Dockerfile 与打包的工件放在一起，允许 CDK 直接使用 AgentRuntimeArtifact.fromAsset 构建 Docker 镜像。

如果您定义了多个代理，还会生成一个 docker 目标，为所有代理准备 docker 上下文。

镜像扫描

Section titled “镜像扫描”

为此项目构建的 Docker 镜像可以使用 Trivy 进行漏洞扫描，该工具从 ECR 托管的 Trivy 镜像运行。

项目中会添加一个 trivy 目标，用于扫描构建的镜像，如果发现任何 HIGH 或 CRITICAL 严重级别的漏洞，将以非零状态退出。生成的 Dockerfile 使用的基础镜像在生成时没有已知的可修复漏洞（这些严重级别），并升级捆绑的工具（如 npm）以保持这种状态。

扫描使用与镜像构建相同的容器引擎（docker 或 finch），因此不需要额外的工具。扫描不会被缓存，因为它读取的镜像存在于容器引擎中而不是磁盘上——因此它始终扫描真实的镜像，并在镜像不再存在时大声失败，而不是报告缓存的通过结果。因此，每次运行每个镜像需要数十秒，并刷新 Trivy 的漏洞数据库，所以需要网络访问。提供的 trivy 根脚本会扫描工作区中的每个镜像：

Terminal window
pnpm trivy

抑制 Trivy 发现

Section titled “抑制 Trivy 发现”

在某些情况下，您可能希望抑制特定的漏洞，例如当尚无可用修复且您已评估风险为可接受时。

将漏洞 ID（每行一个）添加到项目根目录中的 .trivyignore 文件（即 project.json 旁边）：

.trivyignore
# node-tar arbitrary file write - not exploitable in our usage
CVE-2024-XXXXX

有关过滤发现的更多详细信息，请参阅 Trivy 过滤文档。

可观测性

Section titled “可观测性”

您的代理会自动配置可观测性，使用 AWS Distro for Open Telemetry (ADOT)。

您可以在 CloudWatch AWS 控制台中找到追踪，方法是在菜单中选择”GenAI Observability”。请注意，要填充追踪，您需要启用 Transaction Search。

有关更多详细信息，请参阅 AgentCore 关于可观测性的文档。

会话管理

Section titled “会话管理”

session 选项控制您的代理如何在调用之间持久化对话状态（消息历史、工具状态等），使用 Strands SDK 的 SessionManager：

  • s3（默认）：CDK/Terraform 基础设施为会话数据配置一个专用的 S3 存储桶，使用专用的 KMS 密钥加密并阻止所有公共访问；服务器访问日志通过相同的密钥传送到 CloudWatch Logs 日志组。代理的 IAM 角色被授予对存储桶的读/写/列表/删除访问权限以及对密钥的解密/生成数据密钥访问权限，存储桶名称与代理的 ARN 一起注册在 AppConfig 运行时配置中。
  • in-memory：不配置存储桶。对话状态仅在运行进程的生命周期内保存在内存中，不会在重启或缩容后保留。

这在生成的 session.ts 中实现，它导出一个 getSessionManager() 函数，为当前会话解析 SessionManager。

会话 ID 本身来自 AgentCore Runtime 会话（对于 A2A/AG-UI 通过 x-amzn-bedrock-agentcore-runtime-session-id 标头传播，或对于 HTTP/tRPC 通过 WebSocket 连接上下文传播），并绑定到基于 AsyncLocalStorage 的上下文，因此 getCurrentSessionId() 可以在请求的任何地方解析它 — 包括通过 connection 生成器连接的任何下游 MCP 或 A2A 客户端，因此整个调用链共享一致的会话。

将会话限制为其所有者

Section titled “将会话限制为其所有者”

会话 ID 来自调用者，因此它本身只能识别对话，但不能识别对话属于谁。AgentCore Runtime 针对代理运行时资源 ARN 而不是针对单个会话授权调用，这使代理可以自由决定会话对您的应用程序意味着什么。

要将每个用户限制为他们自己的对话：

  1. 添加一个 API 来创建会话，使用 tRPC、FastAPI 或 Smithy。生成一个不透明的会话 ID（至少 33 个字符）并将其与调用用户的 ID 一起存储 — 例如在使用 ts#dynamodb 生成器创建的表中。每个 API 指南都展示了如何检索调用用户的 ID。
  2. 在您的代理中，查找给定会话 ID 的存储用户 ID，并在它与调用者不匹配时拒绝请求。使用 auth=cognito 时，调用者的 JWT 会到达您的代理代码，因此其 sub 声明可以识别他们。

生成会话 ID，而不是从用户提供的值（如对话名称）派生它 — 调用者可以预测的任何内容，调用者都可以发送。

调用您的 Agent

Section titled “调用您的 Agent”
protocol = http

代理通信通过基于 WebSocket 的 tRPC 传输。因此，建议使用 client.ts 中生成的类型安全客户端工厂。

调用本地服务器

Section titled “调用本地服务器”

使用 <your-agent-name>-dev 目标启动您的代理：

Terminal window
pnpm nx agent-dev your-project

然后使用客户端工厂的 .local 工厂方法调用它。

例如，您可以在工作区中创建一个名为 scripts/test.ts 的文件，该文件导入客户端：

客户端类以您的代理命名，因此名为 my-agent 的代理会导出 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 });

替换分配给您的代理的端口 — 从项目的 project.json 中的 metadata.ports 读取。

调用已部署的 Agent

Section titled “调用已部署的 Agent”

要调用部署到 Bedrock AgentCore Runtime 的 Agent，您可以向 Bedrock AgentCore Runtime 数据平面端点发送 POST 请求，并使用 URL 编码的运行时 ARN。

您可以按以下方式从基础设施中获取运行时 ARN：

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

ARN 将具有以下格式：arn:aws:bedrock-agentcore:<region>:<account>:runtime/<agent-runtime-id>。

然后，您可以通过将 : 替换为 %3A 并将 / 替换为 %2F 来对 ARN 进行 URL 编码。

用于调用 Agent 的 Bedrock AgentCore Runtime 数据平面 URL 如下：

https://bedrock-agentcore.<region>.amazonaws.com/runtimes/<url-encoded-arn>/invocations

调用此 URL 的确切方式取决于所使用的身份验证方法。

NodeJS

Section titled “NodeJS”

生成的 client.ts 文件包含一个类型安全的客户端工厂，可用于调用已部署的代理。

IAM 身份验证
Section titled “IAM 身份验证”

您可以通过将其 ARN 传递给 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'),
});

浏览器 / React 网站

Section titled “浏览器 / React 网站”

要从 React 网站调用您的 Agent，您可以使用 connection 生成器，它会自动设置具有正确身份验证（IAM 或 Cognito）的 tRPC WebSocket 客户端。

运行此生成器@aws/nx-plugin:connection

pnpm nx g @aws/nx-plugin:connection
构建你的命令5

必需

必需

您还可以执行试运行以查看哪些文件会被更改

有关如何设置连接的详细信息，请参阅 connection 生成器指南。

protocol = a2a

将 A2A Agent 作为工具调用

Section titled “将 A2A Agent 作为工具调用”

要从此代理将工作委托给远程 A2A 代理（TypeScript 或 Python），请使用 connection 生成器。它为目标代理提供 SigV4 身份验证的客户端，并对此代理的 agent.ts 进行 AST 转换，将远程 A2A 代理注册为 Strands tool。

运行此生成器@aws/nx-plugin:connection

pnpm nx g @aws/nx-plugin:connection
构建你的命令5

必需

必需

您还可以执行试运行以查看哪些文件会被更改

有关如何设置连接的详细信息，请参阅 connection 生成器指南。

protocol = ag-ui

调用 AG-UI Agent

Section titled “调用 AG-UI Agent”

要从 React 网站调用您的 AG-UI 代理，请使用 connection 生成器，它会连接一个为您的已部署代理配置了正确身份验证（IAM 或 Cognito）的 CopilotKit 客户端。

运行此生成器@aws/nx-plugin:connection

pnpm nx g @aws/nx-plugin:connection
构建你的命令5

必需

必需

您还可以执行试运行以查看哪些文件会被更改

有关如何设置连接的详细信息，请参阅 connection 生成器指南。

保护您的 Agent

Section titled “保护您的 Agent”

Agent 会处理不受信任的输入，并可以通过其工具驱动实际操作，因此从一开始就考虑安全性是值得的。以下实践适用于生成的 agent。

将模型输入和输出视为不受信任

Section titled “将模型输入和输出视为不受信任”

提示可能包含对抗性指令（提示注入），而模型输出是非确定性的——在安全敏感的逻辑中都不应信任它们：

  • 为您的工具定义严格的输入模式，就像生成的示例工具中那样。将值限制为工具实际需要的内容（枚举、长度限制、数值范围），而不是接受自由格式的字符串。
  • 切勿在没有验证或编码的情况下将模型输出直接传递到 shell 命令、SQL 查询、代码评估或渲染的 HTML 中。
  • 在您的工具和下游服务中应用授权检查——不要依赖系统提示来防止模型滥用它有权访问的工具。

Strands 的 Prompt Engineering 和 Responsible AI 指南涵盖了编写健壮、具有安全意识的系统提示。

严格限制工具权限范围

Section titled “严格限制工具权限范围”

仅授予 agent 的 IAM 角色其工具所需的权限。提供的 CDK 构造和 Terraform 模块公开了 grant* 方法和范围限定的策略以实现此目的——例如，授予 agent 访问权限以调用特定 API，而不是附加广泛的托管策略。当工具代表用户执行操作时，优先使用调用用户的身份（通过请求上下文传递）来授权操作，而不是使用 agent 自身的环境权限。

提供紧急开关

Section titled “提供紧急开关”

由于模型行为可能以意外方式发生变化，因此请计划在不更改代码的情况下快速禁用或切换模型：

  • 从配置中读取模型 ID（例如 MODEL_ID 环境变量），以便操作员可以通过更新配置来切换或回滚到不同的模型。
  • 在功能标志后面设置 agent，以便可以完全禁用其 AI 功能。禁用时，返回通用消息而不是错误，并确保应用程序的其余部分能够优雅降级。

在您的操作手册中记录如何切换这些控制。

保护敏感数据

Section titled “保护敏感数据”
  • 避免记录提示和完成内容，它们可能包含用户数据。生成的 agent 的模型错误日志记录钩子仅记录错误元数据，而不记录对话内容——在添加自己的日志记录时保持此属性。
  • 向用户返回通用错误消息；在服务器端记录详细错误。
  • 在用户和会话之间隔离对话状态，并授权访问任何持久化的会话数据。
  • 从提示和输出中编辑个人身份信息（PII）——可以使用 Bedrock Guardrail 敏感信息过滤器（见下文），或者对于 Strands agent，使用 PII Redaction 指南中的方法。

Amazon Bedrock Guardrails

Section titled “Amazon Bedrock Guardrails”

Amazon Bedrock Guardrails 提供可配置的内容过滤器、拒绝主题和敏感信息（PII）过滤器，这些过滤器会在模型输入和输出时进行评估。您可以将护栏附加到生成的 agent 使用的模型：

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

有关更多详细信息，请参阅 Strands Guardrails 指南。

连接

Section titled “连接”

使用 connection 生成器将此项目与工作区中的其他项目集成。以下连接涉及此项目：

Strands AgentsTypeScript
React to TypeScript Agent从 React 网站调用 TypeScript Agent
CopilotKit
React to AG-UI Agent通过 CopilotKit 从 React 网站调用公开 AG-UI 协议的 Agent
Strands AgentsTypeScriptModel Context Protocol
TypeScript Agent to MCP将 TypeScript Agent 连接到 MCP 服务器
Strands AgentsTypeScriptAgent2Agent
TypeScript Agent to A2A Agent将 TypeScript Agent 连接到远程 A2A 代理
Strands AgentsPythonAgent2Agent
Python Agent to A2A Agent将 Python Agent 连接到远程 A2A 代理
Strands AgentsTypeScriptAmazon Aurora
TypeScript Agent to Relational Database将 TypeScript Agent 连接到 Aurora 关系数据库
Strands AgentsTypeScriptAmazon DynamoDB
TypeScript Agent to TypeScript DynamoDB将 TypeScript Agent 连接到 DynamoDB 表
Strands AgentsTypeScriptAmazon Bedrock AgentCore Gateway
TypeScript Agent to AgentCore Gateway将 TypeScript Agent 连接到 AgentCore Gateway
Amazon Bedrock AgentCore GatewayStrands Agents
AgentCore Gateway to Agent使用 AgentCore Gateway 作为运行时目标为代理提供前端