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

Python Agent

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

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

用法

Section titled “用法”

生成代理

Section titled “生成代理”

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

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

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

必需

infra = agentcore | agentcore-ecr

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

选项

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

要添加 Agent 的项目

frameworkenum默认值: strands

要使用的 Agent SDK。

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

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

iamcognito
protocolenum默认值: http

Agent 的服务器协议。HTTP 暴露一个 FastAPI HTTP 服务器。A2A 暴露一个 Agent-to-Agent 协议服务器。AG-UI 暴露一个 Agent-User Interaction 协议服务器，用于直接前端集成。

httpa2aag-ui
iacenum默认值: inherit

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

inheritcdkterraform
infraenum默认值: agentcore

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

agentcoreagentcore-ecrnone
sessionenum默认值: s3

用于持久化 Agent 会话的存储。LangChain 支持 's3' 或 'dynamodb-s3'；Strands 支持 's3'；'in-memory' 两者均适用。

s3dynamodb-s3in-memory
namestring

Agent 的名称（默认：agent）

preferInstallDependenciesboolean默认值: true

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

生成器输出

Section titled “生成器输出”

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

protocol = http

HTTP 协议（默认）

Section titled “HTTP 协议（默认）”
  • 文件夹your-project/
    • 文件夹your_module/
      • 文件夹agent/ (or custom name if specified)
        • __init__.py Python package initialization
        • init.py FastAPI application setup with CORS and error handling middleware
        • agent.py Main agent definition with sample tools
        • session.py Resolves the framework-specific session persistence implementation
        • 文件夹middleware/
          • __init__.py Python package initialization
          • session_id_middleware.py Binds the inbound AgentCore session ID for the request
        • main.py FastAPI entry point for Bedrock AgentCore Runtime
        • Dockerfile Container image definition (only when infra is agentcore-ecr)
    • pyproject.toml Updated with Strands dependencies
    • project.json Updated with agent serve targets
protocol = a2a

A2A 协议

Section titled “A2A 协议”

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

  • 文件夹your-project/
    • 文件夹your_module/
      • 文件夹agent/ (or custom name if specified)
        • __init__.py Python package initialization
        • agent.py Main agent definition with sample tools
        • session.py Resolves the framework-specific session persistence implementation
        • 文件夹middleware/
          • __init__.py Python package initialization
          • session_id_middleware.py Binds the inbound AgentCore session ID for the request
        • main.py A2A server entry point
        • Dockerfile Container image definition (only when infra is agentcore-ecr)
    • pyproject.toml Updated with framework and A2A dependencies
    • project.json Updated with agent serve targets
protocol = ag-ui

AG-UI 协议

Section titled “AG-UI 协议”

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

  • 文件夹your-project/
    • 文件夹your_module/
      • 文件夹agent/ (or custom name if specified)
        • __init__.py Python package initialization
        • agent.py Main agent definition with sample tools
        • session.py Resolves the framework-specific session persistence implementation
        • 文件夹middleware/
          • __init__.py Python package initialization
          • session_id_middleware.py Binds the inbound AgentCore session ID for the request
        • main.py AG-UI server entry point
        • Dockerfile Container image definition (only when infra is agentcore-ecr)
    • pyproject.toml Updated with framework 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…

使用您的代理

Section titled “使用您的代理”

您可以编辑 agent.py 来添加工具、配置模型和自定义系统提示。API 取决于您选择的框架。

添加工具

Section titled “添加工具”

工具是 AI 代理可以调用以执行操作的函数。两个框架都使用基于装饰器的方法来定义工具，从函数名称和文档字符串派生工具名称和描述，并从您的类型提示生成输入模式。

定义工具，然后将其添加到 get_agent() 内的 tools 列表中：

packages/my-project/my_module/agent/agent.py
from contextlib import contextmanager


from strands import Agent, tool
from strands.hooks import HookCallback, HookProvider
from strands_tools import current_time
from my_scope_agent_connection import log_model_errors, log_tool_errors


from .session import get_session_manager




@tool
def subtract(a: int, b: int) -> int:
    return a - b




@tool
def get_weather(city: str) -> str:
    """Get weather information for a city"""
    # Your weather API integration here
    return f"Weather in {city}: Sunny, 25°C"




AGENT_HOOKS: list[HookProvider | HookCallback] = [log_model_errors, log_tool_errors]




@contextmanager
def get_agent():
    yield Agent(
        name="MyAgent",
        description="MyAgent Strands Agent",
        system_prompt="You are a helpful assistant with access to various tools.",
        tools=[subtract, current_time, get_weather],
        hooks=AGENT_HOOKS,
        session_manager=get_session_manager(),
    )

使用预构建工具

Section titled “使用预构建工具”

Strands 通过 strands-agents-tools 包提供了一系列预构建工具，生成器已将其添加到您项目的 pyproject.toml 中。导入您想要的工具并将它们添加到 get_agent()：

packages/my-project/my_module/agent/agent.py
from strands_tools import current_time, file_read, http_request


# ...


@contextmanager
def get_agent():
    yield Agent(
        name="MyAgent",
        description="MyAgent Strands Agent",
        system_prompt="You are a helpful assistant.",
        tools=[current_time, file_read, http_request],
        hooks=AGENT_HOOKS,
        session_manager=get_session_manager(),
    )

模型配置

Section titled “模型配置”

生成的代理使用 Amazon Bedrock 上的默认 Strands 模型。要配置它，请将 model 传递给 Agent。有关可用提供商及其选项，请参阅 Strands 关于模型提供商的文档：

packages/my-project/my_module/agent/agent.py
from strands.models import BedrockModel


# ...


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


@contextmanager
def get_agent():
    yield Agent(
        model=MODEL,
        name="MyAgent",
        description="MyAgent Strands Agent",
        system_prompt="You are a helpful assistant.",
        tools=[subtract, current_time],
        hooks=AGENT_HOOKS,
        session_manager=get_session_manager(),
    )

使用 MCP 服务器

Section titled “使用 MCP 服务器”

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

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

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

必需

必需

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

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

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

更多

Section titled “更多”

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

协议

Section titled “协议”

您的代理的服务器协议决定了它如何通信。所有选项都由 FastAPI 提供服务 — 入口点不同：

  • HTTP（默认）：具有自定义 /invocations 端点、CORS 和流式传输的标准 FastAPI 服务器。最适合自定义客户端集成。
  • A2A：挂载到 FastAPI 应用程序上的 Agent-to-Agent 服务器（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。生成的基础设施已为您配置。

protocol = http

FastAPI 服务器（HTTP 协议）

Section titled “FastAPI 服务器（HTTP 协议）”

生成的 HTTP 服务器包括：

  • 带有 CORS 中间件的 FastAPI 应用程序设置
  • 错误处理中间件
  • OpenAPI 模式生成
  • 健康检查端点（/ping）
  • 代理调用端点（/invocations）

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

Section titled “使用 Pydantic 自定义调用输入和输出”

代理的调用端点使用 Pydantic 模型来定义和验证请求和响应模式。您可以在 main.py 中自定义这些模型以匹配您的代理的要求。

定义输入模型

Section titled “定义输入模型”

默认的 InvokeInput 模型接受一个提示。

from pydantic import BaseModel, Field


class InvokeInput(BaseModel):
    prompt: str = Field(max_length=100000)

您可以扩展此模型以包含代理需要的任何其他字段。

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

定义输出模型

Section titled “定义输出模型”

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

默认情况下，代理产生包含代理响应文本的 StreamChunk 对象：

class StreamChunk(BaseModel):
    content: str

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

from pydantic import BaseModel


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

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

Bedrock AgentCore Python SDK

Section titled “Bedrock AgentCore Python SDK”

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

您可以在此处的文档中找到有关 SDK 功能的更多详细信息。

protocol = a2a

A2A 服务器（A2A 协议）

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

生成的 main.py 将 A2A 服务器挂载到也公开 /ping 的父 FastAPI 应用程序上。Strands 代理使用 Strands A2AServer；LangChain 代理将编译的图包装在 a2a-sdk AgentExecutor 中。代理卡中公布的 URL 来自 AGENTCORE_RUNTIME_URL 环境变量，对于本地开发则回退到 http://localhost:<port>/。

大多数用户不需要修改此文件；编辑 agent.py 以更改工具或系统提示。A2A 服务器从代理的 name 和 description 填充代理卡（/.well-known/agent-card.json）。

protocol = ag-ui

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

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

生成的 main.py 公开了一个通过服务器发送事件（SSE）流式传输 AG-UI 事件的单个 POST 端点，以及用于 AgentCore 运行时健康检查的 /ping。连接取决于框架：

  • Strands：将您的 Agent 包装在 ag_ui_strands.StrandsAgent 中，在 FastAPI lifespan 处理程序内构建（因此构建发生在容器/会话启动时而不是导入时），并从手工编写的 FastAPI /invocations 循环中提供服务。
  • LangChain：将编译的图包装在 ag_ui_langgraph.LangGraphAgent 中，以相同的方式在 lifespan 内构建，并从手工编写的 FastAPI /invocations 循环中提供服务。

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

运行您的代理

Section titled “运行您的代理”

本地开发

Section titled “本地开发”

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

Terminal window
pnpm nx dev your-project

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

Terminal window
pnpm nx agent-dev your-project

这使用 uv run 使用 Bedrock AgentCore Python SDK 执行您的 Agent。

代理监听在生成时从工作区池分配的端口。从项目的 project.json 中的 metadata.ports 读取它，或从 <your-agent-name>-dev 目标的命令中的 --port 标志读取。下面的示例使用 8081，这是在新工作区中分配给第一个 HTTP 代理的端口。

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

与您的代理聊天

Section titled “与您的代理聊天”

生成器配置了一个 <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 时连接到您部署的代理（请参阅下面的与您部署的代理聊天）。

protocol = http

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

  • scripts/<your_agent_name>_openapi.py — 一个导出代理的 OpenAPI 规范的小脚本（使用您的代理名称的 snake_case 命名）
  • 一个运行它的 <your-agent-name>-openapi Nx 目标
  • 一个在 scripts/<your-agent-name>/generated/ 下生成类型安全 TypeScript 客户端的 <your-agent-name>-generate-client Nx 目标

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

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

将您的代理部署到 Bedrock AgentCore Runtime

Section titled “将您的代理部署到 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。

打包和 Docker 目标

Section titled “打包和 Docker 目标”

为了为 Bedrock AgentCore Runtime 构建您的 Agent，会向您的项目添加一个 bundle 目标，它：

  • 使用 uv export 将您的 Python 依赖项导出到 requirements.txt 文件
  • 使用 uv pip install 为目标平台（aarch64-manylinux_2_28）安装依赖项
infra = agentcore

还会添加一个 <your-agent-name>-package 目标，它组装可部署的代码包：aarch64 依赖项包、您的 Python 模块树和根 main.py 入口点。生成的基础设施将此目录作为 .zip 上传 — 在 CDK 下通过 AgentRuntimeArtifact.fromCodeAsset，或在 Terraform 下归档到共享资产存储桶中。

infra = agentcore-ecr

还会添加一个特定于您的 Agent 的 docker 目标，它将 Dockerfile 和打包的工件复制到 docker 上下文目录中。这将 Dockerfile 与构建输出放在一起，允许 CDK 使用 AgentRuntimeArtifact.fromAsset 直接构建 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”。请注意，要填充跟踪，您需要启用事务搜索。

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

会话管理

Section titled “会话管理”

session 选项根据您选择的框架映射到不同的底层持久性概念：Strands 的会话管理概念用于 strands 框架，或 LangGraph 的检查点概念用于 langchain 框架。

framework = strands

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

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

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

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

将会话限制为其所有者

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

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

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

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

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

framework = langchain

session 选项控制您的代理的 LangGraph 检查点如何持久化对话状态：

  • s3（默认）：部署的代理使用带有提供的会话存储桶的 S3CheckpointSaver，将检查点和待处理写入存储在 checkpoints/ 前缀下。此类位于共享代理连接项目中的 s3_checkpoint_saver_langchain.py 中。
  • dynamodb-s3：CDK/Terraform 基础设施为检查点提供 DynamoDB 表，按照 AWS 关于使用 DynamoDB 作为 LangGraph 代理的检查点存储的文档中的建议进行配置（统一的 PK/SK 模式、PAY_PER_REQUEST 计费、时间点恢复和 ttl 属性），以及用于卸载超过 350KB 的检查点的 S3 存储桶。两者都使用专用的 KMS 密钥加密；存储桶的服务器访问日志通过相同的密钥传送到 CloudWatch Logs 日志组。代理的 IAM 角色被授予对表和存储桶的读/写访问权限，并且表/存储桶名称与代理的 ARN 一起注册在 AppConfig 运行时配置中。
  • in-memory：不提供表或存储桶。对话状态仅在运行进程的生命周期内保留在内存中，不会在重启或缩容后保留。

这在生成的 session.py 中实现，它导出一个从 agent.py 的 create_agent(..., checkpointer=get_checkpointer()) 调用的 get_checkpointer() 函数。

调用您的代理

Section titled “调用您的代理”
protocol = http

调用本地服务器

Section titled “调用本地服务器”

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

Terminal window
pnpm nx agent-dev your-project

然后向您的本地代理运行的端口上的 /invocations 发送 POST 请求。替换分配给您的代理的端口 — 从项目的 project.json 中的 metadata.ports 读取它，或从 <your-agent-name>-dev 目标的命令中的 --port 标志读取。新工作区中的第一个 HTTP 代理被分配 8081：

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

调用部署的代理

Section titled “调用部署的代理”

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

IAM 身份验证

Section titled “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 '{"prompt": "what is 3 + 5?"}' \
-H 'Content-Type: application/json'
Click here for more details on configuring the above acurl command

浏览器 / React 网站

Section titled “浏览器 / React 网站”

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

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

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

必需

必需

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

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

protocol = a2a

将 A2A 代理作为工具调用

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

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

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

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

必需

必需

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

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

protocol = ag-ui

调用 AG-UI 代理

Section titled “调用 AG-UI 代理”

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

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

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

必需

必需

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

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

保护您的代理

Section titled “保护您的代理”

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

连接

Section titled “连接”

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

Strands AgentsPython
React to Python AgentCall a Python Agent from a React website
CopilotKit
React to AG-UI AgentCall an Agent exposing the AG-UI protocol from a React website via CopilotKit
Strands AgentsPythonModel Context Protocol
Python Agent to MCPConnect a Python Agent to an MCP server
Strands AgentsPythonAgent2Agent
Python Agent to A2A AgentConnect a Python Agent to a remote A2A agent
Strands AgentsTypeScriptAgent2Agent
TypeScript Agent to A2A AgentConnect a TypeScript Agent to a remote A2A agent
Strands AgentsPythonAmazon DynamoDBPython
Python Agent to Python DynamoDBConnect a Python Agent to a DynamoDB table
Strands AgentsPythonAmazon Bedrock AgentCore Gateway
Python Agent to AgentCore GatewayConnect a Python Agent to an AgentCore Gateway
Amazon Bedrock AgentCore GatewayStrands Agents
AgentCore Gateway to AgentFront an agent with an AgentCore Gateway as a runtime target