TypeScript Strands 代理

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

什么是 Strands?

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

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

用法

生成 Agent

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

VSCode

1. 安装 Nx Console VSCode Plugin 如果您尚未安装
2. 在VSCode中打开Nx控制台
3. 点击 Generate (UI) 在"Common Nx Commands"部分
4. 搜索 @aws/nx-plugin - ts#agent
5. 填写必需参数
6. 点击 Generate

CLI

pnpm

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

yarn

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

npm

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

bun

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

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

pnpm

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

yarn

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

npm

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

bun

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

项目前提条件

首先使用 ts#project 生成器创建一个项目,然后将您的 Agent 添加到其中。

选项

参数	类型	默认值	描述
project 必需	string	-	要添加 Agent 的项目
framework	strands	strands	要使用的代理 SDK。
name	string	-	Agent 的名称（默认：agent）
auth	iam | cognito	iam	用于对 Agent 进行身份验证的方法。仅在设置了 infra 时适用（当 infra 为 none 时忽略）。
protocol	http | a2a | ag-ui	http	Agent 的服务器协议。HTTP 公开 tRPC/WebSocket 服务器。A2A 公开 Agent-to-Agent 协议服务器。AG-UI 公开 AG-UI 协议服务器，用于与 CopilotKit 的前端直接集成。
iac	inherit | cdk | terraform	inherit	首选的 IaC 提供商。默认情况下，这继承自您的初始选择。
infra	agentcore | none	agentcore	用于托管 Agent 的基础设施类型。
preferInstallDependencies	boolean	true	是否在生成器运行后优先安装依赖项。设置为 false 可在批量运行多个生成器时延迟安装（如果后续生成器需要计算 Nx 项目图，仍会运行安装）；在最后统一安装一次。

生成器输出

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

protocol = http

HTTP 协议(默认)

• 文件夹your-project/

  • 文件夹src/

    • 文件夹agent/ (如果指定,则为自定义名称)

      • index.ts Bedrock AgentCore Runtime 的入口点(tRPC/WebSocket 服务器)
      • init.ts tRPC 初始化
      • router.ts 带有代理过程的 tRPC 路由器
      • agent.ts 带有示例工具的主代理定义
      • client.ts 用于调用代理的客户端
      • agent-core-trpc-client.ts 用于连接到 AgentCore Runtime 上的代理的客户端工厂
      • Dockerfile 托管代理的入口点(当 infra 设置为 None 时排除)
  • package.json 已更新 Strands 依赖项
  • project.json 已更新代理服务目标

protocol = a2a

A2A 协议

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

• 文件夹your-project/

  • 文件夹src/

    • 文件夹agent/ (如果指定,则为自定义名称)

      • index.ts A2A Express 服务器入口点
      • agent.ts 带有示例工具的主代理定义
      • Dockerfile 托管代理的入口点(当 infra 设置为 None 时排除)
  • package.json 已更新 Strands 和 Express 依赖项
  • project.json 已更新代理服务目标

protocol = ag-ui

AG-UI 协议

入口点使用 @ag-ui/aws-strands 通过 AG-UI 协议(基于 POST 的 SSE)公开代理,与 CopilotKit 兼容:

• 文件夹your-project/

  • 文件夹src/

    • 文件夹agent/ (如果指定,则为自定义名称)

      • index.ts AG-UI 服务器入口点(Express + SSE)
      • agent.ts 带有示例工具的主代理定义
      • Dockerfile 托管代理的入口点(当 infra 设置为 None 时排除)
  • package.json 已更新 Strands 和 AG-UI 依赖项
  • project.json 已更新代理服务目标

基础设施

infra = agentcore

由于该生成器会根据您选择的 iac 以基础设施即代码的形式输出，它将在 packages/common 目录下创建一个包含相关 CDK 构造体或 Terraform 模块的项目。

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

CDK

• 文件夹packages/common/constructs

  • 文件夹src

    • 文件夹app/ 针对特定项目/生成器的基础设施构造体

      • …
    • 文件夹core/ 被 app 目录构造体重用的通用构造体

      • …
    • index.ts 导出 app 目录构造体的入口文件
  • project.json 项目构建目标与配置

生成的项目

此项目使用 ts#project 生成器创建，因此配置了相同的构建目标。

Terraform

• 文件夹packages/common/terraform

  • 文件夹src

    • 文件夹app/ 针对特定项目/生成器的 Terraform 模块

      • …
    • 文件夹core/ 被 app 目录模块重用的通用模块

      • …
  • project.json 项目构建目标与配置

生成的项目

此项目使用 terraform#project 生成器创建，因此配置了相同的构建目标。

为了部署您的 Agent,将生成以下文件:

CDK

• 文件夹packages/common/constructs/src

  • 文件夹app

    • 文件夹agents

      • 文件夹<project-name>

        • <project-name>.ts 用于部署代理的 CDK 构造

Terraform

• 文件夹packages/common/terraform/src

  • 文件夹app

    • 文件夹agents

      • 文件夹<project-name>

        • <project-name>.tf 用于部署代理的模块
  • 文件夹core

    • 文件夹agent-core

      • runtime.tf 用于部署到 Bedrock AgentCore Runtime 的通用模块

infra = none

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

架构

Bedrock AgentCore Runtime

当部署到 Bedrock AgentCore Runtime 时，代理会被构建为容器镜像，推送到 Amazon ECR 并在 AgentCore Runtime 中运行。客户端调用 AgentCore Runtime 数据平面端点，该端点将请求转发到您的代理。代理调用 Amazon Bedrock 进行模型推理，并可能调用工具、MCP 服务器或下游 API。

None (local only)

使用 infra: None 时，不会生成 AWS 基础设施。代理作为本地进程运行，并调用 Amazon Bedrock 进行模型推理。

使用您的 Agent

协议

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

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

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

protocol = http

基于 WebSocket 的 tRPC(HTTP 协议)

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

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

添加工具

工具是 AI 代理可以调用以执行操作的函数。您可以在 agent.ts 文件中添加新工具:

import { Agent, tool } from '@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],
  });
};

Strands 框架自动处理:

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

模型配置

默认情况下,Strands 代理使用 Claude 4 Sonnet,但您可以轻松切换模型提供商:

import { Agent } from '@agents/sdk';
import { BedrockModel } from '@agents/sdk/models/bedrock';
import { OpenAIModel } from '@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 服务器

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

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

VSCode

1. 安装 Nx Console VSCode Plugin 如果您尚未安装
2. 在VSCode中打开Nx控制台
3. 点击 Generate (UI) 在"Common Nx Commands"部分
4. 搜索 @aws/nx-plugin - connection
5. 填写必需参数
6. 点击 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

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

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

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

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

更多

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

protocol = a2a

A2A 服务器(A2A 协议)

生成的 index.ts 将 Strands A2A Express Server 挂载到 Express 应用上,因此生成的代理会公开 A2A 协议端点以及 /ping 健康检查。当部署到 AgentCore 时,入口点会从 AppConfig 解析运行时的公共 ARN,并在代理卡中进行公告。

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

protocol = ag-ui

AG-UI 服务器(AG-UI 协议)

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

AG-UI 代理设计为直接由前端使用。使用 connection 生成器将您的 React 网站连接到代理,配置 CopilotKit 提供程序和 AG-UI HttpAgent 客户端。

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

运行您的 Agent

本地开发

要在本地运行您的 Agent(以及与其连接的所有内容),请使用项目的 dev 目标:

pnpm

pnpm nx dev your-project

yarn

yarn nx dev your-project

npm

npx nx dev your-project

bun

bunx nx dev your-project

如果您已向项目添加了多个组件(代理、MCP 服务器等),这将启动所有组件。要仅运行此代理,请使用其 <your-agent-name>-dev 目标:

pnpm

pnpm nx agent-dev your-project

yarn

yarn nx agent-dev your-project

npm

npx nx agent-dev your-project

bun

bunx nx agent-dev your-project

此命令使用 tsx --watch 在文件更改时自动重启服务器。代理将在 http://localhost:8081 上可用(如果您有多个代理,则为分配的端口)。

与您的代理聊天

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

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

pnpm

pnpm nx agent-dev your-project

yarn

yarn nx agent-dev your-project

npm

npx nx agent-dev your-project

bun

bunx nx agent-dev your-project

然后,在另一个终端中启动聊天:

pnpm

pnpm nx run your-project:agent-chat

yarn

yarn nx run your-project:agent-chat

npm

npx nx run your-project:agent-chat

bun

bunx nx run your-project:agent-chat

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

infra = agentcore

Chat with your deployed agent

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

IAM

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

pnpm

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

yarn

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

npm

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

bun

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

Cognito

对于 Cognito 身份验证的代理,通过 AGENT_ACCESS_TOKEN 环境变量提供 Cognito 访问令牌,该令牌作为 bearer 令牌发送:

pnpm

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

yarn

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

npm

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

bun

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

您可以使用 AWS CLI 的 cognito-idp admin-initiate-auth 命令获取访问令牌,例如:

aws cognito-idp admin-initiate-auth \
  --user-pool-id <user-pool-id> \
  --client-id <user-pool-client-id> \
  --auth-flow ADMIN_NO_SRP_AUTH \
  --auth-parameters USERNAME=<username>,PASSWORD=<password> \
  --query 'AuthenticationResult.AccessToken' \
  --output text

infra = agentcore

将您的 Agent 部署到 Bedrock AgentCore Runtime

基础设施即代码

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

CDK

系统会为您的代理生成一个 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');
  }
}

CDK构造

此构造使用 aws-cdk-lib/aws-bedrockagentcore 模块。

Terraform

系统会为您生成一个 Terraform 模块，其名称基于您运行生成器时选择的 name，或默认为 <ProjectName>-agent。

将共享的 runtime_config_appconfig 模块的输出传递给代理模块：

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
}

Bedrock 模型权限

生成的代理构造默认授予调用所有 Bedrock 基础模型和推理配置文件的权限（对 arn:aws:bedrock:*:*:foundation-model/* 和 arn:aws:bedrock:*:*:inference-profile/* 的 bedrock:InvokeModel 和 bedrock:InvokeModelWithResponseStream 权限）。

您可能希望将其范围缩小到您的代理使用的特定模型。您可以在 Strands 文档中找到 Strands 代理使用的默认模型；有关配置不同模型的信息，请参阅 Strands 模型提供商指南。

需要Docker

构建和部署 Agent 需要 Docker。请确保您已安装并启动 Docker，以避免出现如下错误：

ERROR: Cannot connect to the Docker daemon at unix://path/to/docker.sock.

身份验证

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

IAM

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

CDK

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 上代理的访问权限，例如：

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

export class ExampleStack extends Stack {
  constructor(scope: Construct, id: string) {
    const agent = new MyProjectAgent(this, 'MyProjectAgent');
    const lambdaFunction = new Function(this, ...);

    agent.grantInvokeAccess(lambdaFunction);
  }
}

Terraform

# Agent
module "my_project_agent" {
  # Relative path to the generated module in the common/terraform project
  source = "../../common/terraform/src/app/agents/my-project-agent"

  appconfig_application_id  = module.runtime_config_appconfig.application_id
  appconfig_application_arn = module.runtime_config_appconfig.application_arn
}

要授予调用代理的访问权限，您需要添加如下策略，引用 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}/*"
  ]
}

Cognito 身份验证

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

CDK

生成的构造接受一个 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。

Terraform

生成的模块接受 user_pool_id 和 user_pool_client_ids 变量用于 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]
}

自定义OIDC提供者

如果您需要使用非 Cognito OIDC 提供商的自定义 JWT 身份验证，您可以直接修改为您的代理生成的 CDK 构造或 Terraform 模块。请注意，连接生成器仅支持 IAM 或 Cognito 身份验证。

安全最佳实践

在实现代理的业务逻辑时，请查看 Bedrock AgentCore Runtime 安全最佳实践。

Bundle 目标

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

pnpm

pnpm nx bundle <project-name>

yarn

yarn nx bundle <project-name>

npm

npx nx bundle <project-name>

bun

bunx nx bundle <project-name>

Rolldown 配置位于 rolldown.config.ts 文件中，每个要生成的包都有对应的入口配置。如果定义了多个包，Rolldown 会并行管理这些包的创建过程。

自定义配置

您可以通过修改 rolldown.config.ts 来调整 Rolldown 的配置。例如，如果有依赖项需要依赖文件路径且无法被打包，可以将它们添加到 external 模块列表中。

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

Docker 目标

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

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

镜像扫描

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

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

扫描使用与镜像构建相同的容器引擎（docker 或 finch），因此不需要额外的工具。由于扫描仅在镜像更改时重新运行，未更改的镜像不会被重新扫描。提供的 trivy 根脚本会扫描工作区中的每个镜像：

pnpm

pnpm trivy

yarn

yarn trivy

npm

npm run trivy

bun

bun trivy

在 CI 中运行 Trivy

扫描故意不连接到 build，因为这可能会在开发过程中迭代时引入不必要的摩擦，因为 Trivy 的漏洞数据库会不断更新新的 CVE。

相反，我们建议在部署到生产阶段之前，将上述命令作为 CI 流水线中的专用步骤运行。

忽略无法修复的漏洞

扫描使用 --ignore-unfixed 运行，因此没有可用修复的漏洞不会导致构建失败，因为它们无法通过升级 Dockerfile 中的工具来解决——它们不会在构建的扫描输出中报告。随着新漏洞的披露，扫描结果可能会随时间而变化，因此请定期通过运行不带该标志的 trivy image <your-image> 来审查镜像，并在发布修复后针对较新的基础镜像重新构建（或添加容器步骤来应用可用的补丁）。

抑制 Trivy 发现

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

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

.trivyignore

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

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

可观测性

您的代理会自动配置可观测性,使用 AWS Distro for Open Telemetry (ADOT),通过在 Dockerfile 中配置自动检测。

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

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

调用您的 Agent

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

protocol = http

调用本地服务器

您可以使用客户端工厂的 .local 工厂方法调用本地运行的代理。

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

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

快速测试

使用 tsx 运行是测试代理的快速方法。

pnpm

pnpm tsx scripts/test.ts

yarn

yarn tsx scripts/test.ts

npm

npx tsx scripts/test.ts

bun

bunx tsx scripts/test.ts

调用已部署的代理

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

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

CDK

import { CfnOutput } from 'aws-cdk-lib';
import { MyProjectAgent } from '@my-scope/common-constructs';

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

    new CfnOutput(this, 'AgentArn', {
      value: agent.agentCoreRuntime.agentRuntimeArn,
    });
  }
}

Terraform

# Agent
module "my_project_agent" {
  # Relative path to the generated module in the common/terraform project
  source = "../../common/terraform/src/app/agents/my-project-agent"

  appconfig_application_id  = module.runtime_config_appconfig.application_id
  appconfig_application_arn = module.runtime_config_appconfig.application_arn
}

output "agent_arn" {
  value = module.my_project_agent.agent_core_runtime_arn
}

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

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

浏览器控制台

在浏览器控制台或 Node REPL 中使用内置的 encodeURIComponent 方法可以轻松实现:

encodeURIComponent('arn:aws:bedrock-agentcore:<region>:<account>:runtime/<agent-runtime-id>')

用于调用 agent 的 Bedrock AgentCore Runtime 数据平面 URL 如下:

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

调用 URL

您的基础设施还可以直接输出完整的调用 URL,ARN 编码会自动处理:

CDK

new CfnOutput(this, 'AgentUrl', {
  value: agent.invocationUrl,
});

Terraform

output "agent_url" {
  value = module.my_project_agent.invocation_url
}

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

NodeJS

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

HTTP头认证

客户端工厂在 WebSocket 握手中使用 HTTP 头来验证对 Bedrock AgentCore Runtime 的请求。这在浏览器中不可能实现,因此此客户端不适合浏览器环境。有关从浏览器调用的详细信息,请参阅下面的”浏览器”部分。

IAM

IAM 身份验证

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

AWS凭证

这将使用默认的 AWS 凭证提供程序链来验证请求,因此运行上述代码的环境必须配置了 AWS 凭证,并具有调用运行时的访问权限。

Cognito

JWT / Cognito 身份验证

使用 withJwtAuth 工厂方法通过 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,
});

accessTokenProvider 必须返回用于验证请求的令牌。例如,您可以在此方法中获取令牌,以确保在 tRPC 重启 WebSocket 连接时重用新凭证。以下演示了使用 AWS SDK 从 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!;
  },
});

浏览器 / React 网站

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

VSCode

1. 安装 Nx Console VSCode Plugin 如果您尚未安装
2. 在VSCode中打开Nx控制台
3. 点击 Generate (UI) 在"Common Nx Commands"部分
4. 搜索 @aws/nx-plugin - connection
5. 填写必需参数
6. 点击 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

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

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

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

protocol = a2a

将 A2A 代理作为工具调用

要将工作从此代理委托给远程 A2A 代理(无论是 TypeScript 还是 Python),请使用 connection 生成器。它会为目标代理提供 SigV4 认证的客户端,并对此代理的 agent.ts 进行 AST 转换,将远程 A2A 代理注册为 Strands tool。

VSCode

1. 安装 Nx Console VSCode Plugin 如果您尚未安装
2. 在VSCode中打开Nx控制台
3. 点击 Generate (UI) 在"Common Nx Commands"部分
4. 搜索 @aws/nx-plugin - connection
5. 填写必需参数
6. 点击 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

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

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

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

protocol = ag-ui

调用 AG-UI 代理

要从 React 网站调用您的 AG-UI 代理,请使用 connection 生成器,它会为您部署的代理配置 CopilotKit 客户端,并使用正确的身份验证(IAM 或 Cognito)。

VSCode

1. 安装 Nx Console VSCode Plugin 如果您尚未安装
2. 在VSCode中打开Nx控制台
3. 点击 Generate (UI) 在"Common Nx Commands"部分
4. 搜索 @aws/nx-plugin - connection
5. 填写必需参数
6. 点击 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

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

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

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

保护您的 Agent

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

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

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

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

Strands 的提示工程和负责任的 AI指南介绍了如何编写健壮且注重安全的系统提示。

严格限制工具权限范围

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

提供紧急开关

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

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

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

保护敏感数据

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

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 指南。

连接

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

React to TypeScript Agent从 React 网站调用 TypeScript Agent

React to AG-UI Agent通过 CopilotKit 从 React 网站调用公开 AG-UI 协议的 Agent

TypeScript Agent to MCP将 TypeScript Agent 连接到 MCP 服务器

TypeScript Agent to A2A Agent将 TypeScript Agent 连接到远程 A2A agent

Python Agent to A2A Agent将 Python Agent 连接到远程 A2A agent

TypeScript Agent to Relational Database将 TypeScript Agent 连接到 Aurora 关系数据库

TypeScript Agent to TypeScript DynamoDB将 TypeScript Agent 连接到 DynamoDB 表

TypeScript Agent to AgentCore Gateway将 TypeScript Agent 连接到 AgentCore Gateway