TypeScript Agent tới Gateway

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

Trình tạo sẽ kết nối agent để xác thực với Gateway bằng IAM SigV4 khi triển khai, và kết nối với local gateway đượ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 TypeScript với thành phần Agent (infra: agentcore)
2. Một dự án agentcore-gateway

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 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 tệp client cốt lõi được chia sẻ vào gói 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ụcsrc

    • Thư mụccore/

      • agentcore-endpoints.ts Framework-agnostic ARN/URL resolution
      • agentcore-gateway-mcp-transport.ts Framework-agnostic Gateway MCP transport
      • agentcore-gateway-mcp-client-strands.ts Strands MCP client cho Gateway đã triển khai
    • Thư mụcapp/

      • <gateway-kebab>-client-strands.ts Wrapper client Strands cho mỗi Gateway
    • index.ts Xuất lại Gateway client

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

• Sửa đổi agent.ts của agent để import lớp Gateway client, gọi <Gateway>ClientStrands.create(), và đăng ký client được trả về trong mảng tools
• Kết nối target <agent>-dev của agent để phụ thuộc vào target dev của Gateway
• Cài đặt các phụ thuộc SigV4 / MCP cần thiết

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

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

packages/example/src/my-agent/agent.ts

import { Agent } from '@strands-agents/sdk';
import { MyGatewayClientStrands } from ':my-scope/agent-connection';

export const getAgent = async () => {
  const myGateway = await MyGatewayClientStrands.create();
  return new Agent({
    systemPrompt: '...',
    tools: [myGateway],
  });
};

Khi triển khai (SERVE_LOCAL không được đặt), client trỏ tới MCP endpoint của Gateway và xác thực bằng SigV4. Khi SERVE_LOCAL=true, nó trỏ tới local gateway được khởi động bởi target serve-local của dự án Gateway, vì vậy cùng một agent.ts hoạt động đồng nhất trong cả hai chế độ.

Session ID được truyền tới các MCP server downstream tự động 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);

Gateway URL được tự động đăng ký trong namespace agentcore.gateways.<ClassName> của Runtime Configuration bởi CDK construct được tạo, vì vậy 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
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 được tự động đăng ký trong namespace agentcore.gateways.<ClassName> của Runtime Configuration bởi Terraform module được tạo, vì vậy 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 local gateway của Gateway đã kết nối và mọi MCP server được đính kèm
2. Đặt LOCAL_DEV=true để client được tạo trỏ tới local gateway 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ộ 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 SERVE_LOCAL, client sẽ phân giải Gateway URL đã triển khai từ cấu hình runtime và ký các 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ộ

Local gateway đóng vai trò 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 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 MCP server cục bộ được bọc để hiển thị tên có 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 action 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. n khai.