Python 代理

生成一个用于构建带工具的AI代理的Python代理，并可选部署到Amazon Bedrock AgentCore Runtime。使用framework选项选择代理框架：Strands（默认）或LangChain（基于LangGraph构建）。

生成器通过服务器protocol暴露您的代理。两个框架都支持HTTP（默认）、用于与其他A2A兼容代理互操作的Agent-to-Agent (A2A)协议，以及通过CopilotKit直接集成前端的AG-UI协议。

使用方式

生成代理

可通过两种方式生成Python代理：

VSCode

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

CLI

pnpm

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

yarn

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

npm

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

bun

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

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

pnpm

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

yarn

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

npm

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

bun

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

项目前提条件

建议先使用py#project生成器创建项目，再添加代理。

选项配置

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

生成器输出

生成器将在现有Python项目中添加以下文件。生成的文件取决于所选的protocol：

protocol = http

HTTP协议（默认）

• 文件夹your-project/

  • 文件夹your_module/

    • 文件夹agent/ (可自定义名称)

      • __init__.py Python包初始化文件
      • init.py 配置CORS和错误处理中间件的FastAPI应用设置
      • agent.py 主智能体定义（含示例工具）
      • main.py Bedrock AgentCore Runtime的FastAPI入口点
      • Dockerfile 智能体托管入口文件（当infra设为None时不生成）
  • pyproject.toml 更新Strands依赖
  • project.json 更新服务目标配置

protocol = a2a

A2A协议

入口点通过A2A协议暴露您的代理（Strands使用Strands A2A Server；LangChain将图包装在a2a-sdk执行器中），挂载到FastAPI应用上：

• 文件夹your-project/

  • 文件夹your_module/

    • 文件夹agent/ (可自定义名称)

      • __init__.py Python包初始化文件
      • agent.py 主智能体定义（含示例工具）
      • main.py A2A服务器入口点
      • Dockerfile 智能体托管入口文件（当infra设为None时不生成）
  • pyproject.toml 更新框架和A2A依赖
  • project.json 更新服务目标配置

protocol = ag-ui

AG-UI协议

入口点通过AG-UI协议暴露您的代理，以便直接与CopilotKit进行前端集成。Strands代理使用ag-ui-strands集成；LangChain代理使用ag-ui-langgraph：

• 文件夹your-project/

  • 文件夹your_module/

    • 文件夹agent/ (可自定义名称)

      • __init__.py Python包初始化文件
      • agent.py 主智能体定义（含示例工具）
      • main.py AG-UI服务器入口点
      • Dockerfile 智能体托管入口文件（当infra设为None时不生成）
  • pyproject.toml 更新框架和AG-UI依赖
  • project.json 更新服务目标配置

连接到React网站

AG-UI智能体可以使用connection生成器连接到React前端，该生成器将设置CopilotKit组件以提供丰富的聊天体验。

基础设施

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 生成器创建，因此配置了相同的构建目标。

部署代理时生成以下文件：

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 部署智能体的Terraform模块
  • 文件夹core

    • 文件夹agent-core

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

infra = none

如果您选择了none作为infra，则不会生成CDK构造或Terraform模块——代理只能在本地运行。在此模式下，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.py来添加工具、配置模型和自定义系统提示。API取决于您选择的框架。

添加工具

工具是AI智能体可调用的功能函数。两个框架都使用基于装饰器的方式定义工具，从函数名和文档字符串派生工具名称和描述，并从类型提示生成输入模式。

Strands

from strands import Agent, tool

@tool
def calculate_sum(numbers: list[int]) -> int:
    """计算数字列表的总和"""
    return sum(numbers)

@tool
def get_weather(city: str) -> str:
    """获取城市天气信息"""
    # 此处集成天气API
    return f"{city}天气：晴，25°C"

# 将工具添加到智能体
agent = Agent(
    system_prompt="您是一个拥有多种工具的智能助手。",
    tools=[calculate_sum, get_weather],
)

LangChain

from langchain.agents import create_agent
from langchain_aws import ChatBedrockConverse
from langchain_core.tools import tool

@tool
def calculate_sum(numbers: list[int]) -> int:
    """计算数字列表的总和"""
    return sum(numbers)

@tool
def get_weather(city: str) -> str:
    """获取城市天气信息"""
    # 此处集成天气API
    return f"{city}天气：晴，25°C"

# 将工具添加到智能体
agent = create_agent(
    model=ChatBedrockConverse(model=MODEL_ID, region_name=REGION),
    tools=[calculate_sum, get_weather],
    system_prompt="您是一个拥有多种工具的智能助手。",
)

使用预置工具

Strands

Strands通过strands-tools包提供一系列预置工具：

from strands_tools import current_time, http_request, file_read

agent = Agent(
    system_prompt="您是一个智能助手。",
    tools=[current_time, http_request, file_read],
)

LangChain

LangChain提供了大量的工具和集成生态系统。安装相关的集成包，然后将工具传递给create_agent：

from langchain_community.tools import DuckDuckGoSearchRun

agent = create_agent(
    model=ChatBedrockConverse(model=MODEL_ID, region_name=REGION),
    tools=[DuckDuckGoSearchRun()],
    system_prompt="您是一个智能助手。",
)

模型配置

Strands

默认情况下，Strands代理使用Claude 4 Sonnet，但您可以自定义模型提供商。有关配置选项，请参阅Strands模型提供商文档：

from strands import Agent
from strands.models import BedrockModel

# 创建Bedrock模型实例
bedrock_model = BedrockModel(
    model_id="anthropic.claude-sonnet-4-20250514-v1:0",
    region_name="us-west-2",
    temperature=0.3,
)

agent = Agent(model=bedrock_model)

LangChain

LangChain代理使用ChatBedrockConverse模型。生成的代理从MODEL_ID和AWS_REGION环境变量读取模型ID和区域，但您可以直接在agent.py中配置模型：

from langchain_aws import ChatBedrockConverse

model = ChatBedrockConverse(
    model="anthropic.claude-sonnet-4-20250514-v1:0",
    region_name="us-west-2",
    temperature=0.3,
)

使用MCP服务

对于使用py#mcp-server或ts#mcp-server生成器创建的MCP服务，可以使用connection生成器，它会将MCP服务器的工具连接到您的代理（支持两个框架）。

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或LangChain MCP文档。

更多信息

有关编写代理的深入指南，请参考Strands或LangChain文档。

协议

智能体的服务器协议决定其通信方式。所有选项都由FastAPI提供服务——区别在于入口点：

• HTTP（默认）：标准FastAPI服务器，带有自定义/invocations端点、CORS和流式传输。最适合自定义客户端集成。
• A2A：将Agent-to-Agent服务器挂载到FastAPI应用上（Strands使用Strands A2A Server；LangChain使用框架无关的a2a-sdk）。最适合需要被其他A2A兼容智能体发现和调用的场景。
• AG-UI：通过SSE暴露AG-UI协议（Strands使用ag-ui-strands；LangChain使用ag-ui-langgraph）。最适合在React网站中通过CopilotKit直接集成前端。

服务器入口点因框架而异（Strands生成上下文管理的Agent，而LangChain驱动编译的create_agent图），但每个协议的外部契约是相同的。

所有协议都暴露/ping端点以满足AgentCore运行时健康检查契约。A2A智能体监听端口9000；HTTP和AG-UI智能体监听端口8080。生成的Dockerfile和基础设施已为您配置。

protocol = http

FastAPI服务器（HTTP协议）

生成的HTTP服务器包含：

• 配置CORS中间件的FastAPI应用
• 错误处理中间件
• OpenAPI模式生成
• 健康检查端点（/ping）
• 智能体调用端点（/invocations）

使用Pydantic自定义调用输入和输出

智能体的调用端点使用Pydantic模型来定义和验证请求及响应模式。您可以在main.py中自定义这些模型以满足智能体需求。

定义输入模型

默认的InvokeInput模型接受提示。

from pydantic import BaseModel

class InvokeInput(BaseModel):
    prompt: str

您可以扩展此模型以包含智能体所需的任何额外字段。

会话ID从x-amzn-bedrock-agentcore-runtime-session-id HTTP标头中提取，符合Bedrock AgentCore Runtime会话契约。如果未提供该标头，将生成随机UUID作为后备。

代码组织

如果用户直接调用您的智能体，您可能需要对调用者抽象部分或全部会话ID。例如，您可以使用已认证用户ID作为会话ID的一部分。

还需要注意的是，根据您的使用场景，可能需要为会话实现授权机制，例如确保用户只能访问自己的会话而不能访问其他用户的会话。

定义输出模型

对于流式响应，生成器提供JsonStreamingResponse，它会自动将Pydantic模型序列化为JSON Lines格式（application/jsonl）。该格式兼容OpenAPI 3.2的流式规范，并与生成的TypeScript客户端无缝协作。

默认情况下，智能体yield包含智能体响应文本的StreamChunk对象：

class StreamChunk(BaseModel):
    content: str

您可以自定义StreamChunk模型以满足需求：

from pydantic import BaseModel

class StreamChunk(BaseModel):
    content: str
    timestamp: str
    token_count: int

FastAPI流式限制

注意，由于FastAPI目前不支持为流式响应生成OpenAPI规范，我们必须为每个流式操作显式设置响应模型，例如：

@app.post(
    "/invocations",
    response_class=JsonStreamingResponse,
    responses={200: JsonStreamingResponse.openapi_response(StreamChunk)},
)
async def invoke(input: InvokeInput) -> JsonStreamingResponse:
    return JsonStreamingResponse(handle_invoke(input))

FastAPI有一个关于原生支持的开放功能请求。

Bedrock AgentCore Python SDK

生成器包含对Bedrock AgentCore Python SDK的依赖，用于PingStatus常量。如果需要，可以直接使用BedrockAgentCoreApp替代FastAPI，但请注意会失去类型安全性。

SDK功能详情请参阅文档。

基础设施即代码

由于生成器提供CDK或Terraform基础设施来管理部署，无需使用文档中提到的bedrock-agentcore-starter-toolkit进行部署。

protocol = a2a

A2A服务器（A2A协议）

生成的main.py将A2A服务器挂载到同时暴露/ping端点的父FastAPI应用上。Strands代理使用Strands A2AServer；LangChain代理将编译的图包装在a2a-sdk AgentExecutor中。部署到AgentCore时，入口点从AppConfig解析运行时的公共ARN并在智能体卡片中发布。

大多数用户无需修改此文件；编辑agent.py即可更改工具或系统提示。A2A服务器从智能体的name和description填充智能体卡片（/.well-known/agent-card.json）。

protocol = ag-ui

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

生成的main.py暴露一个POST端点，通过Server-Sent Events (SSE)流式传输AG-UI事件，以及用于AgentCore运行时健康检查的/ping端点。连接方式取决于框架：

• Strands：将您的Agent包装在ag_ui_strands.StrandsAgent中，并通过create_strands_app()创建FastAPI应用。
• LangChain：将编译的图包装在ag_ui_langgraph.LangGraphAgent中，并从手工编写的FastAPI /invocations循环中提供服务。

大多数用户无需修改此文件——编辑agent.py即可更改工具或系统提示。

连接到React网站

AG-UI智能体设计为可直接被前端使用。使用connection生成器，通过CopilotKit提供器和AG-UI HttpAgent客户端将您的React网站连接到智能体。

运行代理

本地开发

要在本地运行您的智能体（及其所有连接的组件），请使用项目的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

这将使用uv run通过Bedrock AgentCore Python SDK执行您的智能体。

与智能体聊天

生成器配置了一个<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时连接到已部署的智能体（参见下面的与已部署的智能体聊天）。

对于HTTP智能体，聊天脚本使用从智能体的OpenAPI规范生成的类型安全TypeScript客户端。生成器还会生成：

• scripts/<your-agent-name>_openapi.py — 一个导出智能体OpenAPI规范的小脚本
• 一个运行该脚本的<your-agent-name>-openapi Nx目标
• 一个<your-agent-name>-generate-client Nx目标，在scripts/<your-agent-name>/generated/下生成类型安全的TypeScript客户端

当您自定义智能体的输入形状（例如向InvokeInput添加新字段）时，更新chat.ts以在调用智能体时传递新字段，其余部分将自动工作。

infra = agentcore

与已部署的智能体聊天

要与部署到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

部署代理到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 安全最佳实践。

打包与Docker目标

为构建Bedrock AgentCore Runtime部署包，项目中添加了bundle目标：

• 使用uv export导出Python依赖到requirements.txt
• 使用uv pip install为目标平台（aarch64-manylinux_2_28）安装依赖

同时添加智能体专用的docker目标，将Dockerfile和打包构建产物复制到docker上下文目录。这使Dockerfile与构建输出位于同一位置，允许CDK使用AgentRuntimeArtifact.fromAsset直接构建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 过滤文档。

可观测性

通过Dockerfile中的自动配置，使用AWS分布式OpenTelemetry（ADOT）实现可观测性。

在CloudWatch控制台选择”GenAI Observability”查看追踪数据，需启用事务搜索。

详细配置参考AgentCore可观测性文档。

调用代理

protocol = http

调用本地服务器

要调用通过<your-agent-name>-serve目标本地运行的智能体，可以向本地智能体运行端口的/invocations发送简单的POST请求。例如，使用curl：

curl -N -X POST http://localhost:8081/invocations \
  -d '{"message": "what is 3 + 5?"}' \
  -H "Content-Type: application/json"

Curl流式标志

传递给curl的-N参数禁用输出流缓冲，以便实时查看流式响应。

调用已部署的智能体

要调用部署到 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 的具体方式取决于所使用的身份验证方法。

IAM

IAM认证

对于IAM认证，请求必须使用AWS Signature Version 4（SigV4）签名。

acurl <region> bedrock-agentcore -N -X POST \
'https://bedrock-agentcore.<region>.amazonaws.com/runtimes/<url-encoded-arn>/invocations' \
-d '{"message": "what is 3 + 5?"}' \
-H 'Content-Type: application/json'

点击此处了解配置上述acurl命令的更多详情

Cognito

JWT / Cognito认证

对于Cognito认证，在Authorization标头中传递Cognito访问令牌：

curl -N -X POST 'https://bedrock-agentcore.<region>.amazonaws.com/runtimes/<url-encoded-arn>/invocations' \
  -d '{"message": "what is 3 + 5?"}' \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <access-token>"

可使用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> \
  --region <region> \
  --query 'AuthenticationResult.AccessToken' \
  --output text

浏览器 / React网站

要从React网站调用代理，可以使用connection生成器，它会自动设置具有正确认证方式（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生成器指南。

protocol = a2a

将A2A智能体作为工具调用

要将工作从此智能体委托给远程A2A智能体（TypeScript或Python），请使用connection生成器。它为目标智能体提供SigV4认证的客户端，并对此智能体的agent.py进行AST转换，将远程A2A智能体注册为@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。

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

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

• 为您的工具定义严格的输入模式，就像生成的示例工具一样。将值约束为工具实际需要的内容（枚举、长度限制、数值范围），而不是接受自由格式的字符串。
• 永远不要在没有验证或编码的情况下将模型输出直接传递到 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 使用的模型：

Strands

agent.py

import os

from strands import Agent
from strands.models import BedrockModel

model = BedrockModel(
    model_id=os.environ.get("MODEL_ID"),
    guardrail_id=os.environ["GUARDRAIL_ID"],
    guardrail_version=os.environ.get("GUARDRAIL_VERSION", "DRAFT"),
)

agent = Agent(model=model)

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

LangChain

agent.py

import os

from langchain_aws import ChatBedrockConverse

model = ChatBedrockConverse(
    model=os.environ.get("MODEL_ID"),
    guardrail_config={
        "guardrailIdentifier": os.environ["GUARDRAIL_ID"],
        "guardrailVersion": os.environ.get("GUARDRAIL_VERSION", "DRAFT"),
    },
)

有关 guardrail_config 字段的详细信息，请参阅 ChatBedrockConverse 文档。

连接

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

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

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

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

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

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

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

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