Python Agent 到 Gateway

connection 生成器可以将您的 Python Agent 连接到 AgentCore Gateway。

该生成器会配置 agent，使其在部署时使用 IAM SigV4（通过 httpx 请求签名）向 Gateway 进行身份验证，并在本地运行时连接到 Gateway 项目启动的本地网关。

前置条件

在使用此生成器之前，请确保您具备：

1. 一个包含 Agent 组件的 Python 项目（infra: agentcore）
2. 一个 agentcore-gateway 项目

使用方法

运行生成器

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

选择 agent 项目作为源，Gateway 项目作为目标。

选项

参数	类型	默认值	描述
sourceProject 必需	string	-	源项目
targetProject 必需	string	-	要连接到的目标项目
sourceComponent	string	-	要从其连接的源组件（组件名称、相对于源项目根目录的路径或生成器 ID）。使用 '.' 显式选择项目作为源。
targetComponent	string	-	要连接到的目标组件（组件名称、相对于目标项目根目录的路径或生成器 ID）。使用 '.' 显式选择项目作为目标。
preferInstallDependencies	boolean	true	是否在生成器运行后优先安装依赖项。设置为 false 可在批量运行多个生成器时延迟安装（如果后续生成器需要计算 Nx 项目图，仍会运行安装）；在最后统一安装一次。

生成器输出

生成器会将共享的 core-gateway 模块发送到您的 agent_connection Python 项目中，加上一个针对每个 Gateway 的包装器，并修改您的 agent：

• 文件夹packages/common/agent_connection

  • 文件夹<scope>_agent_connection

    • 文件夹core/

      • agentcore_endpoints.py 框架无关的 ARN/URL 解析
      • agentcore_gateway_mcp_transport.py 框架无关的 Gateway MCP 传输
      • agentcore_gateway_mcp_client_<framework>.py 用于您的 agent 框架的 Gateway MCP 客户端
      • 文件夹auth/ 框架无关的 SigV4 / 会话转发 httpx.Auth

        • …
    • 文件夹app/

      • <gateway_snake>_client_<framework>.py 针对每个 Gateway 的客户端包装器
    • __init__.py 重新导出 Gateway 客户端

客户端后缀与您的 agent 框架匹配（_strands 或 _langchain）。

此外，生成器还会：

• 修改您的 agent 的 agent.py 以导入 Gateway 客户端并在 tools 中注册其工具
• 将 agent_connection 添加为 agent 的工作区依赖项
• 将 agent 的 <agent>-dev 目标配置为依赖于 Gateway 的 dev 目标

使用连接的 Gateway

生成器会转换您的 agent 的 agent.py 以使用 Gateway 客户端：

Strands

packages/example/example/my_agent/agent.py

from contextlib import contextmanager
from strands import Agent

from my_scope_agent_connection import MyGatewayClientStrands

@contextmanager
def get_agent():
    my_gateway = MyGatewayClientStrands.create()
    with (
        my_gateway,
    ):
        yield Agent(
            system_prompt="...",
            tools=[*my_gateway.list_tools_sync()],
        )

MyGatewayClientStrands.create() 返回一个可以作为上下文管理器的单个 MCPClient，其 list_tools_sync() 会产生通过 Gateway 可用的每个工具。

LangChain

packages/example/example/my_agent/agent.py

from langchain.agents import create_agent
from langchain_aws import ChatBedrockConverse

from my_scope_agent_connection import MyGatewayClientLangChain

def get_agent():
    my_gateway = MyGatewayClientLangChain.create()
    return create_agent(
        model=ChatBedrockConverse(model=MODEL_ID, region_name=REGION),
        system_prompt="...",
        tools=[*my_gateway],
    )

MyGatewayClientLangChain.create() 返回通过 langchain-mcp-adapters 加载的工具列表。每个工具在每次调用时都会打开一个新会话，因此不需要 with 块。

在两种情况下，客户端在每种模式下的行为方式相同：

• 部署模式（未设置 LOCAL_DEV）：指向 Gateway 的 MCP 端点的工具，使用 SigV4 签名。
• 本地模式（LOCAL_DEV=true）：指向 Gateway 项目的 dev 目标启动的本地网关的纯 HTTP 工具。

会话 ID 会通过 X-Amzn-Bedrock-AgentCore-Runtime-Session-Id 标头自动传播到下游 MCP 服务器。

基础设施

运行生成器后，您必须授予 agent 调用 Gateway 的权限。

CDK

packages/infra/src/stacks/application-stack.ts

const gateway = new MyGateway(this, 'MyGateway');
const myAgent = new MyAgent(this, 'MyAgent');

// Grant the agent permissions to invoke the Gateway
gateway.grantInvokeAccess(myAgent);

Gateway URL 会由生成的 CDK 构造自动注册到 运行时配置 的 agentcore.gateways.<ClassName> 命名空间中，以便 agent 可以在运行时发现它。

Terraform

packages/infra/src/main.tf

module "my_gateway" {
  source = "../../common/terraform/src/app/gateways/my-gateway"
}

module "my_agent" {
  source = "../../common/terraform/src/app/agents/my-agent"
}

# Grant the agent permission to invoke the Gateway
resource "aws_iam_policy" "agent_invoke_gateway" {
  name = "AgentInvokeGatewayPolicy"
  policy = jsonencode({
    Version = "2012-10-17"
    Statement = [{
      Effect   = "Allow"
      Action   = "bedrock-agentcore:InvokeGateway"
      Resource = module.my_gateway.gateway_arn
    }]
  })
}

resource "aws_iam_role_policy_attachment" "agent_invoke_gateway" {
  role       = module.my_agent.agent_core_runtime_role_arn
  policy_arn = aws_iam_policy.agent_invoke_gateway.arn
}

Gateway URL 会由生成的 Terraform 模块自动注册到 运行时配置 的 agentcore.gateways.<ClassName> 命名空间中，以便 agent 可以在运行时发现它。

本地开发

生成器会配置 agent 的 dev 目标以：

1. 启动连接的 Gateway 的本地网关和每个附加的 MCP 服务器
2. 设置 LOCAL_DEV=true，以便生成的客户端指向本地网关，而不是已部署的 Gateway

使用以下命令在本地运行 agent：

pnpm

pnpm nx <agent-name>-dev <project-name>

yarn

yarn nx <agent-name>-dev <project-name>

npm

npx nx <agent-name>-dev <project-name>

bun

bunx nx <agent-name>-dev <project-name>

要在本地运行 agent 针对已部署的 Gateway（例如，为了执行 Cedar 策略），请使用 agent 的 serve 目标。在未设置 LOCAL_DEV 的情况下，客户端会从运行时配置中解析已部署的 Gateway URL，并使用您的本地 AWS 凭证对请求进行 SigV4 签名：

pnpm

pnpm nx <agent-name>-serve <project-name>

yarn

yarn nx <agent-name>-serve <project-name>

npm

npx nx <agent-name>-serve <project-name>

bun

bunx nx <agent-name>-serve <project-name>

本地保真度

本地网关代替已部署的 Gateway，因此：

• 没有 Cedar 策略评估。 无论策略如何，agent 都可以看到每个工具。使用 serve target 针对已部署的 Gateway 执行策略。
• 工具名称前缀被保留。 每个本地 MCP 服务器的工具都以 <target-name>___<tool-name> 的形式公开，与已部署的 Gateway 发出的内容相匹配。这使得 agent 的系统提示和您引用的 Cedar 操作名称在本地和部署运行中保持一致。