Python Agent tới 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 sẽ cấu hình agent để 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ó:

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

Cách sử dụng

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

pnpm nx g @aws/nx-plugin:connection

yarn nx g @aws/nx-plugin:connection

npx nx g @aws/nx-plugin:connection

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 nx g @aws/nx-plugin:connection --dry-run

yarn nx g @aws/nx-plugin:connection --dry-run

npx nx g @aws/nx-plugin:connection --dry-run

bunx nx g @aws/nx-plugin:connection --dry-run

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ả đầu ra của trình tạo

Trình tạo tạo ra các module 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 Phân giải ARN/URL không phụ thuộc framework
    agentcore_gateway_mcp_transport.py Gateway MCP transport không phụ thuộc framework
    agentcore_gateway_mcp_client_<framework>.py Gateway MCP client cho framework của agent
    Thư mụcauth/ SigV4 / chuyển tiếp session httpx.Auth không phụ thuộc framework
    …
  - Thư mụcapp/
    <gateway_snake>_client_<framework>.py Wrapper client cho mỗi Gateway
  - __init__.py Xuất lại Gateway client

Hậu tố client khớp với framework của agent (_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
LangChain

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 có thể quản lý ngữ cảnh duy nhất mà list_tools_sync() của nó cung cấp mọi công cụ có sẵn thông qua Gateway.

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 session mới cho mỗi lần gọi, do đó 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ý SigV4.
Chế độ cục bộ (LOCAL_DEV=true): các công cụ HTTP thuần trỏ đến gateway cục bộ được khởi động bởi target dev của dự án Gateway.

Session ID đượ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
Terraform

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.

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
}

URL Gateway được tự động đăng ký trong namespace agentcore.gateways.<ClassName> của Runtime Configuration bởi module 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 để:

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
Đặ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 nx <agent-name>-dev <project-name>

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

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

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

Để chạy agent cục bộ 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. Khi không đặt LOCAL_DEV, client sẽ phân giải URL Gateway đã triển khai từ cấu hình runtime và ký SigV4 các yêu cầu với thông tin xác thực AWS cục bộ của bạn:

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

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

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

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

Độ trung thực cục bộ

Gateway cục bộ thay thế cho Gateway đã triển khai, do đó:

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 chính sách với Gateway đã triển khai.
Tiền tố tên công cụ được giữ nguyê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.