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

由于该生成器会根据您选择的 iacProvider 以基础设施即代码的形式输出，它将在 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):
    message: 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镜像。

可观测性

通过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 的具体方式取决于所使用的身份验证方法。

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生成器指南。

连接

使用 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