TypeScript Agent đến A2A Agent

Generator connection có thể kết nối TypeScript Agent của bạn với một A2A agent từ xa — có thể là TypeScript hoặc Python — để agent của bạn có thể ủy quyền cho một agent khác như một công cụ.

Generator 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 A2A agent từ xa, 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 generator này, hãy đảm bảo bạn có:

1. Một dự án TypeScript với component Strands Agent (bất kỳ giao thức nào)
2. Một dự án với component Agent được tạo bằng --protocol=a2a và --auth=iam (có thể là ts#agent hoặc py#agent)
3. Cả hai component được tạo với infra: agentcore

Cách sử dụng

Chạy Generator

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 host agent của bạn làm nguồn và dự án A2A agent của bạn làm đích. Nếu các 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ả của Generator

Generator tạo một package agent-connection được chia sẻ và sửa đổi mã agent của bạn:

• Thư mụcpackages/common/agent-connection

  • Thư mụcsrc

    • Thư mụcapp

      • <target-agent-name>-client-strands.ts High-level Strands client for the connected A2A agent
    • Thư mụccore

      • agentcore-endpoints.ts Framework-agnostic ARN/URL resolution
      • agentcore-fetch.ts Framework-agnostic SigV4 / JWT / session-forwarding fetch
      • agentcore-a2a-client-config.ts Framework-agnostic A2A client config (signed clientFactory)
      • agentcore-a2a-client-strands.ts Strands A2A client wrapping the config
    • index.ts Exports all clients
  • project.json
  • tsconfig.json

Ngoài ra, nó:

• Chuyển đổi agent.ts của agent để đăng ký A2A agent từ xa như một Strands tool
• Cập nhật target dev của agent để phụ thuộc vào target dev của target agent
• Cài đặt các dependency cần thiết

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

Generator chuyển đổi agent.ts của agent để bao bọc A2A agent từ xa như một công cụ:

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

import { Agent, tool } from '@strands-agents/sdk';
import { RemoteAgentClientStrands } from '@my-scope/agent-connection';
import { z } from 'zod';

export const getAgent = async (sessionId: string) => {
  const remoteAgent = await RemoteAgentClientStrands.create(sessionId);
  const remoteAgentTool = tool({
    name: 'askRemoteAgent',
    description: 'Delegate a question to the remote RemoteAgent A2A agent and return its reply.',
    inputSchema: z.object({ prompt: z.string() }),
    callback: async ({ prompt }) => (await remoteAgent.invoke(prompt)).toString(),
  });
  return new Agent({
    systemPrompt: '...',
    tools: [remoteAgentTool],
  });
};

Tham số sessionId được truyền từ người gọi, đảm bảo tính nhất quán cho Bedrock AgentCore Observability.

Bên trong, RemoteAgentClientStrands.create(sessionId) trả về một Strands A2AAgent được cấu hình với clientFactory ký SigV4 khi triển khai lên AWS, và một endpoint http://localhost:<port>/ đơn giản khi LOCAL_DEV=true. Việc ký và phân giải endpoint nằm trong agentcore-a2a-client-config.ts không phụ thuộc framework; chỉ có agentcore-a2a-client-strands.ts mỏng phụ thuộc vào Strands.

Cơ sở hạ tầng

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

CDK

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

const remoteAgent = new RemoteAgent(this, 'RemoteAgent');
const myAgent = new MyAgent(this, 'MyAgent');

// Grant the host agent permission to invoke the remote A2A agent
remoteAgent.grantInvokeAccess(myAgent);

grantInvokeAccess trên một A2A agent sẽ thiết lập cả bedrock-agentcore:InvokeAgentRuntime và bedrock-agentcore:GetAgentCard — A2A client cần cả hai để lấy agent card và gửi tin nhắn.

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

Terraform

packages/infra/src/main.tf

module "remote_agent" {
  source = "../../common/terraform/src/app/agents/remote-agent"

  appconfig_application_id  = module.runtime_config_appconfig.application_id
  appconfig_application_arn = module.runtime_config_appconfig.application_arn
}

module "my_agent" {
  source = "../../common/terraform/src/app/agents/my-agent"

  appconfig_application_id  = module.runtime_config_appconfig.application_id
  appconfig_application_arn = module.runtime_config_appconfig.application_arn
}

# Grant the host agent permission to invoke the remote A2A agent
resource "aws_iam_policy" "agent_invoke_a2a" {
  name = "AgentInvokeA2aPolicy"
  policy = jsonencode({
    Version = "2012-10-17"
    Statement = [{
      Effect = "Allow"
      Action = [
        "bedrock-agentcore:InvokeAgentRuntime",
        "bedrock-agentcore:GetAgentCard",
      ]
      Resource = module.remote_agent.agent_core_runtime_arn
    }]
  })
}

resource "aws_iam_role_policy_attachment" "agent_invoke_a2a" {
  role       = module.my_agent.agent_core_runtime_role_arn
  policy_arn = aws_iam_policy.agent_invoke_a2a.arn
}

ARN của AgentCore runtime của remote agent được tự động đăng ký trong namespace agentcore của Runtime Configuration bởi Terraform module được tạo, để host 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 host agent để:

1. Tự động khởi động (các) A2A agent đã kết nối
2. Đặt LOCAL_DEV=true để client được tạo kết nối trực tiếp với http://localhost:<port>/ 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ả host agent và tất cả các A2A agent đã kết nối, với host agent gọi các remote agent qua HTTP đơn giản trên các cổng cục bộ được chỉ định của chúng.