Python Agent đến Gateway

Trình tạo connection có thể kết nối Python Agent của bạn với AgentCore Gateway.

Trình tạo kết nối agent để nó xác thực với Gateway bằng IAM SigV4 (thông qua ký yêu cầu httpx) khi triển khai, và kết nối với gateway cục bộ được khởi động bởi dự án Gateway khi chạy cục bộ.

Điều kiện tiên quyết

Trước khi sử dụng trình tạo này, hãy đảm bảo bạn có:

1. Một dự án Python với thành phần Agent (infra: agentcore)
2. Một dự án agentcore-gateway với auth: iam

Gateway phải sử dụng xác thực IAM — agent ký các yêu cầu của nó bằng SigV4 sử dụng vai trò thực thi của chính nó. Trình tạo từ chối các gateway được xác thực bằng Cognito.

Cách sử dụng

Chạy Trình tạo

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

Bạn cũng có thể thực hiện chạy thử để xem những tệp nào sẽ bị thay đổi

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

VSCode

1. Cài đặt Nx Console VSCode Plugin nếu bạn chưa cài đặt
2. Mở Nx Console trong VSCode
3. Nhấp Generate (UI) trong phần "Common Nx Commands"
4. Tìm kiếm @aws/nx-plugin - connection
5. Điền các tham số bắt buộc
6. Nhấp Generate

Chọn dự án agent làm nguồn và dự án Gateway làm đích.

Tùy chọn

Tham số	Kiểu	Mặc định	Mô tả
sourceProject Bắt buộc	string	-	Dự án nguồn
targetProject Bắt buộc	string	-	Dự án đích để kết nối tới
sourceComponent	string	-	Component nguồn để kết nối từ đó (tên component, đường dẫn tương đối so với thư mục gốc của dự án nguồn, hoặc generator id). Sử dụng '.' để chọn rõ ràng dự án làm nguồn.
targetComponent	string	-	Component đích để kết nối tới (tên component, đường dẫn tương đối so với thư mục gốc của dự án đích, hoặc generator id). Sử dụng '.' để chọn rõ ràng dự án làm đích.
preferInstallDependencies	boolean	true	Có nên cài đặt các dependencies sau khi generator chạy hay không. Đặt thành false để trì hoãn việc cài đặt khi chạy nhiều generator liên tiếp (việc cài đặt vẫn sẽ chạy nếu cần thiết để các generator tiếp theo có thể tính toán Nx project graph); cài đặt một lần vào cuối.

Kết quả của Trình tạo

Trình tạo phát ra các mô-đun core-gateway được chia sẻ vào dự án Python agent_connection của bạn, cộng với một wrapper cho mỗi Gateway, và sửa đổi agent của bạn:

• Thư mụcpackages/common/agent_connection

  • Thư mục<scope>_agent_connection

    • Thư mụccore/

      • agentcore_endpoints.py Framework-agnostic ARN/URL resolution
      • agentcore_gateway_mcp_transport.py Framework-agnostic Gateway MCP transport
      • agentcore_gateway_mcp_client_<framework>.py Gateway MCP client for your agent’s framework
      • Thư mụcauth/ Framework-agnostic SigV4 / session-forwarding httpx.Auth

        • …
    • Thư mụcapp/

      • <gateway_snake>_client_<framework>.py Per-Gateway client wrapper
    • __init__.py Re-exports the Gateway client

Hậu tố client khớp với framework của agent của bạn (_strands hoặc _langchain).

Ngoài ra, trình tạo:

• Sửa đổi agent.py của agent để import Gateway client và đăng ký các công cụ của nó trong tools
• Thêm agent_connection làm phụ thuộc workspace của agent
• Kết nối target <agent>-dev của agent để phụ thuộc vào target dev của Gateway

Sử dụng Gateway đã kết nối

Trình tạo chuyển đổi agent.py của agent để sử dụng Gateway client:

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() trả về một MCPClient duy nhất có thể quản lý context mà list_tools_sync() của nó cung cấp mọi công cụ có sẵn thông qua 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() trả về một danh sách các công cụ được tải thông qua langchain-mcp-adapters. Mỗi công cụ mở một phiên mới cho mỗi lần gọi, vì vậy không cần khối with.

Trong cả hai trường hợp, client hoạt động theo cùng một cách cho mỗi chế độ:

• Chế độ triển khai (LOCAL_DEV không được đặt): các công cụ trỏ đến điểm cuối MCP của Gateway, được ký bằng SigV4.
• Chế độ cục bộ (LOCAL_DEV=true): các công cụ HTTP thuần túy trỏ đến gateway cục bộ được khởi động bởi target dev của dự án Gateway.

ID phiên được truyền tự động đến các máy chủ MCP downstream thông qua header X-Amzn-Bedrock-AgentCore-Runtime-Session-Id.

Cơ sở hạ tầng

Sau khi chạy trình tạo, bạn phải cấp quyền cho agent để gọi 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);

URL Gateway được tự động đăng ký trong namespace agentcore.gateways.<ClassName> của Runtime Configuration bởi CDK construct được tạo, để agent có thể khám phá nó tại runtime.

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
  additional_iam_policy_statements = [{
    Effect   = "Allow"
    Action   = ["bedrock-agentcore:InvokeGateway"]
    Resource = [module.my_gateway.gateway_arn]
  }]
}

URL Gateway được tự động đăng ký trong namespace agentcore.gateways.<ClassName> của Runtime Configuration bởi mô-đun Terraform được tạo, để agent có thể khám phá nó tại runtime.

Phát triển Cục bộ

Trình tạo cấu hình target dev của agent để:

1. Khởi động gateway cục bộ của Gateway đã kết nối và mọi máy chủ MCP được đính kèm
2. Đặt LOCAL_DEV=true để client được tạo trỏ đến gateway cục bộ thay vì Gateway đã triển khai

Chạy agent cục bộ với:

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>

Để chạy agent cục bộ đối với Gateway đã triển khai thay thế (ví dụ: để thực thi các chính sách Cedar), hãy sử dụng target serve của agent. Không có LOCAL_DEV được đặt, client phân giải URL Gateway đã triển khai từ cấu hình runtime và ký yêu cầu bằng SigV4 với thông tin xác thực AWS cục bộ của bạn:

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>

Độ trung thực cục bộ

Gateway cục bộ thay thế cho Gateway đã triển khai, vì vậy:

• Không đánh giá chính sách Cedar. Mọi công cụ đều hiển thị với agent bất kể chính sách. Sử dụng target serve để thực thi các chính sách đối với Gateway đã triển khai.
• Tiền tố tên công cụ được bảo toàn. Các công cụ của mỗi máy chủ MCP cục bộ được hiển thị dưới dạng <target-name>___<tool-name>, khớp với những gì Gateway đã triển khai phát ra. Điều này giữ cho system prompt của agent và tên hành động Cedar mà bạn tham chiếu nhất quán giữa các lần chạy cục bộ và đã triển khai.