Python Agent tới MCP

Trình tạo connection có thể kết nối Python Agent của bạn với một MCP server (có thể là TypeScript hoặc Python).

Trình tạo thiết lập tất cả các kết nối cần thiết để agent của bạn có thể khám phá và gọi các công cụ của MCP server, cả khi triển khai lên AWS (thông qua Bedrock AgentCore) và 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 component Python Agent (Strands hoặc LangChain)
2. Một dự án với component MCP server (có thể là ts#mcp-server hoặc py#mcp-server)
3. Cả hai component được tạo với infra: agentcore

Cách sử dụng

Chạy trình tạo

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

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

Chọn dự án agent của bạn làm nguồn và dự án MCP server của bạn làm đích. Nếu dự án của bạn chứa nhiều component, hãy chỉ định các tùy chọn sourceComponent và targetComponent để phân biệt.

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 một dự án Python agent_connection được chia sẻ tại packages/common/agent_connection/ (nếu chưa tồn tại). Các module client theo từng kết nối được tạo vào dự án được chia sẻ này:

• Thư mụcpackages/common/agent_connection

  • Thư mục<scope>_agent_connection

    • __init__.py Xuất lại các client theo từng kết nối
    • Thư mụccore

      • agentcore_endpoints.py Giải quyết ARN/URL không phụ thuộc framework
      • agentcore_mcp_transport.py Truyền tải MCP không phụ thuộc framework
      • agentcore_mcp_client_<framework>.py Client MCP bao bọc truyền tải cho framework của agent
      • Thư mụcauth/ httpx.Auth SigV4 / chuyển tiếp session không phụ thuộc framework

        • …
    • Thư mụcapp

      • <mcp_server_name>_client_<framework>.py Client theo từng kết nối cho mỗi MCP server

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

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

• Chuyển đổi agent.py của agent để import và sử dụng các công cụ của MCP server thông qua một client dựa trên class
• Thêm dự án agent_connection làm dependency workspace của dự án agent
• Cập nhật target dev của agent để phụ thuộc vào target serve của MCP server

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

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

Strands

packages/my-project/my_module/agent/agent.py

from contextlib import contextmanager
from strands import Agent

from my_scope_agent_connection import MyMcpServerClientStrands

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

Client Strands là một context manager, được nhập vào trong một khối with xung quanh agent.

LangChain

packages/my-project/my_module/agent/agent.py

from langchain.agents import create_agent
from langchain_aws import ChatBedrockConverse

from my_scope_agent_connection import MyMcpServerClientLangChain

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

Client LangChain 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 MCP mới cho mỗi lần gọi, vì vậy các công cụ vẫn có thể sử dụng được trong suốt vòng đời của agent — không cần khối with.

Session ID của AgentCore được tự động truyền đến MCP server thông qua header X-Amzn-Bedrock-AgentCore-Runtime-Session-Id cho cả hai framework, đảm bảo tính nhất quán cho Bedrock AgentCore Observability.

Hạ tầng

CDK

Sau khi chạy trình tạo kết nối, bạn cần cấp quyền cho agent để gọi MCP server:

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

const mcpServer = new MyMcpServer(this, 'MyMcpServer');
const myAgent = new MyAgent(this, 'MyAgent');

// Grant the agent permissions to invoke the MCP server
mcpServer.grantInvokeAccess(myAgent);

ARN runtime AgentCore của MCP server được tự động đăng ký trong namespace agentcore của Runtime Configuration bởi CDK construct được tạo, để agent có thể khám phá nó tại runtime.

Terraform

Sau khi chạy trình tạo kết nối, bạn cần cấp quyền cho agent để gọi MCP server trong cấu hình Terraform của bạn:

packages/infra/src/main.tf

module "inventory_mcp_server" {
  source = "../../common/terraform/src/app/mcp-servers/inventory-mcp"
}

module "story_agent" {
  source = "../../common/terraform/src/app/agents/story-agent"
}

# Grant the agent permissions to invoke the MCP server
resource "aws_iam_policy" "agent_invoke_mcp" {
  name = "AgentInvokeMcpPolicy"
  policy = jsonencode({
    Version = "2012-10-17"
    Statement = [{
      Effect   = "Allow"
      Action   = "bedrock-agentcore:InvokeAgent"
      Resource = module.inventory_mcp_server.agent_core_runtime_arn
    }]
  })
}

resource "aws_iam_role_policy_attachment" "agent_invoke_mcp" {
  role       = module.story_agent.agent_core_runtime_role_arn
  policy_arn = aws_iam_policy.agent_invoke_mcp.arn
}

ARN runtime AgentCore của MCP server được tự động đăng ký trong namespace agentcore 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 để:

1. Tự động khởi động (các) MCP server đã kết nối
2. Đặt LOCAL_DEV=true để client được tạo sử dụng truyền tải HTTP trực tiếp thay vì AgentCore

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>

Điều này sẽ khởi động cả agent và tất cả các MCP server đã kết nối, với agent kết nối trực tiếp đến các MCP server thông qua HTTP trên các cổng cục bộ được chỉ định của chúng.