TypeScript Agent đến Gateway

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

Generator này kết nối agent để nó xác thực với Gateway bằng IAM SigV4 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 generator này, hãy đảm bảo bạn có:

Một dự án TypeScript với thành phần Agent (infra: agentcore)
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ó. Generator sẽ từ chối các gateway được xác thực bằng Cognito.

Cách sử dụng

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

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

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 Generator

Generator tạo ra các tệp client core dùng chung vào package 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 for the deployed Gateway
  - Thư mụcapp/
    <gateway-kebab>-client-strands.ts Per-Gateway Strands client wrapper
  - index.ts Re-exports the Gateway client

Ngoài ra, generator:

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 dependency SigV4 / MCP cần thiết

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

Generator chuyển đổi agent.ts của agent để sử dụng Gateway client:

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 được triển khai (LOCAL_DEV không được đặt), client trỏ đến điểm cuối MCP của Gateway và xác thực bằng SigV4. Khi LOCAL_DEV=true, nó trỏ đến gateway cục bộ được khởi động bởi target dev 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ự động đến các MCP server downstream thông qua header X-Amzn-Bedrock-AgentCore-Runtime-Session-Id.

Cơ sở hạ tầng

Sau khi chạy generator, 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 của Gateway đượ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.

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 của Gateway đượ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ộ

Generator 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 MCP server đượ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 vào đó (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 sẽ phân giải URL Gateway đã triển khai từ runtime configuration 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 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>

Độ chính xác cục bộ

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

Không có đá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 giữ nguyê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.