AgentCore Gateway đến Agent

Generator connection có thể đăng ký một agent (có thể là TypeScript hoặc Python) làm AgentCore Runtime target của một AgentCore Gateway được tạo với protocol: http.

Sau khi kết nối, Gateway sẽ proxy các yêu cầu cho agent dưới <gatewayUrl>/<targetName>/invocations, ký lưu lượng truy cập đi ra đến runtime bằng IAM SigV4. Điều này cung cấp cho các agent của bạn một điểm vào duy nhất được quản lý — và vì người gọi chỉ cần tiếp cận Gateway, bản thân các agent runtime có thể được triển khai bên trong VPC phía sau nó.

Đ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 agentcore-gateway được tạo với protocol: http
2. Một component agent (ts#agent hoặc py#agent) được tạo với infra: agentcore. Cả auth: iam (Gateway gọi nó bằng role của chính nó) hoặc auth: cognito (Gateway chuyển tiếp JWT của người gọi — xem Chuyển tiếp danh tính người gọi) đều hoạt động.

TypeScript HTTP agents

Một TypeScript http agent phục vụ tRPC qua WebSocket, và AgentCore Gateway không hỗ trợ WebSocket hoặc bidirectional streaming — generator từ chối kết hợp này. Hãy tạo agent với giao thức ag-ui thay thế.

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 Gateway làm nguồn và dự án agent làm đích. Nếu dự án agent chứa nhiều component, hãy chỉ định 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ả từ Generator

Generator kết nối các dự án hiện có với nhau thay vì tạo ra các file nguồn mới. Các file sau được sửa đổi:

• Thư mụcpackages/<gateway>

  • project.json target dev của Gateway có thêm dependency vào <agent>-dev của agent
  • local-dev.ts ATTACHED_AGENTS được cập nhật để gateway cục bộ proxy đến agent

Thêm agent target vào stack của bạn

Generator không thể tự động kết nối agent target vào cơ sở hạ tầng của bạn vì nó không biết stack hoặc module nào khởi tạo Gateway. Hãy tự thêm một lệnh gọi duy nhất gateway.addAgent(agent).

CDK

Trong stack nơi bạn khởi tạo Gateway, hãy đăng ký agent làm target:

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

const myAgent = new MyAgent(this, 'MyAgent');
const myGateway = new MyGateway(this, 'MyGateway');

// Register the agent as a runtime target of the Gateway. The target name
// defaults to the agent's `agentName` (its class name in kebab-case,
// e.g. `MyAgent` -> `my-agent`), and forms the target's invocation path:
// <gatewayUrl>/my-agent/invocations
myGateway.addAgent(myAgent);

Để ghi đè tên target mặc định, hãy truyền gatewayTargetName:

myGateway.addAgent(myAgent, { gatewayTargetName: 'my-target' });

Construct cấp quyền invoke access cho execution role của Gateway đến agent runtime và cấu hình target với credential provider GATEWAY_IAM_ROLE, để Gateway ký các lệnh gọi đi ra bằng role của chính nó.

Triển khai agents vào VPC

Đặt một agent phía sau Gateway là điều giúp agent được triển khai trong VPC có thể tiếp cận được: người gọi giao tiếp với endpoint công khai của Gateway, và Gateway tiếp cận runtime bên trong. Truyền cấu hình mạng VPC cho agent construct:

import { RuntimeNetworkConfiguration } from 'aws-cdk-lib/aws-bedrockagentcore';

const myAgent = new MyAgent(this, 'MyAgent', {
  // Give each agent its own scope for the network configuration — usingVpc
  // creates a security group named `SecurityGroup` under the scope you pass,
  // so passing `this` for more than one agent collides on the construct id.
  networkConfiguration: RuntimeNetworkConfiguration.usingVpc(
    new Construct(this, 'MyAgentNetwork'),
    {
      vpc,
      vpcSubnets: { subnetType: ec2.SubnetType.PRIVATE_WITH_EGRESS },
    },
  ),
});

Sử dụng private subnet với egress, không phải private isolated subnet: runtime cần truy cập internet đi ra để tiếp cận Bedrock và đọc cấu hình của nó từ AWS AppConfig.

Triển khai AgentCore Runtime VPC chỉ được hỗ trợ trong một số availability zone nhất định. Nếu triển khai thất bại với subnets are in unsupported availability zones, hãy giới hạn VPC (hoặc lựa chọn subnet) vào các zone được hỗ trợ cho region của bạn.

Terraform

Trong file Terraform nơi bạn khởi tạo Gateway, hãy kết nối agent target vào:

packages/infra/src/main.tf

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

module "my_gateway" {
  source = "../../common/terraform/src/app/gateways/my-gateway"

  # The Gateway signs outbound calls to the runtime with its own role and
  # validates access at target creation, so it needs invoke access first.
  additional_iam_policy_statements = [
    {
      Effect = "Allow"
      Action = [
        "bedrock-agentcore:InvokeAgentRuntime",
        "bedrock-agentcore:InvokeAgentRuntimeWithWebSocketStream",
        # A2A targets additionally serve their agent card via the gateway
        "bedrock-agentcore:GetAgentCard",
      ]
      Resource = [
        module.my_agent.agent_core_runtime_arn,
        "${module.my_agent.agent_core_runtime_arn}/*",
      ]
    }
  ]
}

# Register the agent as a runtime target of the Gateway. The target name
# forms the invocation path: <gatewayUrl>/my-agent/invocations
resource "aws_bedrockagentcore_gateway_target" "my_agent" {
  gateway_identifier = module.my_gateway.gateway_id
  name               = "my-agent"
  # AgentCore fills in a description when none is set, which the provider
  # reports as an inconsistent result after apply — so always set one.
  description = "Agent runtime target my-agent"

  target_configuration {
    http {
      agentcore_runtime {
        arn = module.my_agent.agent_core_runtime_arn
      }
    }
  }

  credential_provider_configuration {
    gateway_iam_role {}
  }
}

Triển khai agents vào VPC

Đặt một agent phía sau Gateway là điều giúp agent được triển khai trong VPC có thể tiếp cận được: người gọi giao tiếp với endpoint công khai của Gateway, và Gateway tiếp cận runtime bên trong. Đặt các biến VPC của agent module:

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

  enable_vpc = true
  vpc_id     = aws_vpc.my_vpc.id
  subnet_ids = [aws_subnet.private_a.id, aws_subnet.private_b.id]
}

Sử dụng private subnet với egress (một route đến NAT gateway), không phải private isolated subnet: runtime cần truy cập internet đi ra để tiếp cận Bedrock và đọc cấu hình của nó từ AWS AppConfig.

Gọi agent thông qua Gateway

Các yêu cầu đến <gatewayUrl origin>/<targetName>/invocations được chuyển tiếp đến agent runtime mà không có chuyển đổi giao thức, vì vậy người gọi sử dụng cùng hình dạng yêu cầu mà họ sẽ sử dụng trực tiếp với runtime — SSE streams (AG-UI), JSON streaming (Python HTTP) và A2A JSON-RPC đều proxy qua. Người gọi xác thực với Gateway (IAM SigV4 hoặc Cognito JWT tùy thuộc vào auth của Gateway) thay vì với agent.

Để kết nối một website với các agent của Gateway, hãy sử dụng connection generator.

Chuyển tiếp danh tính người gọi đến runtime

Theo mặc định, Gateway ký các lệnh gọi đi ra bằng IAM role của chính nó (credential provider GATEWAY_IAM_ROLE), vì vậy runtime thấy danh tính của Gateway, không phải của người gọi. Nếu thay vào đó bạn muốn agent ủy quyền dựa trên người gọi — ví dụ để đọc các claim sub hoặc scope của người dùng — hãy đặt một agent Cognito phía sau một Gateway Cognito. Gateway sau đó chuyển tiếp JWT của người gọi đến runtime không thay đổi (credential provider JWT_PASSTHROUGH), và runtime xác thực lại nó.

Tạo cả hai đầu với auth: cognito và kết nối chúng như trên:

• một agent (ts#agent hoặc py#agent) được tạo với auth: cognito, và
• một Gateway được tạo với auth: cognito đặt phía trước cùng Cognito user pool.

Mọi thứ khác đều tự động — gateway.addAgent(agent) (CDK) và Terraform runtime module được tạo xử lý việc kết nối cho bạn dựa trên auth của agent:

• target được tạo với credential provider JWT_PASSTHROUGH (thay vì GATEWAY_IAM_ROLE), và
• runtime cho phép header Authorization vào danh sách cho phép để token được chuyển tiếp đến code agent của bạn. Không có danh sách cho phép này, AgentCore xác thực token nhưng loại bỏ header trước container của bạn.

Người gọi gọi Gateway với Authorization: Bearer <jwt> (không có SigV4), và agent đọc các claim từ header Authorization — bỏ qua xác thực chữ ký, vì inbound authorizer của runtime đã xác minh token:

packages/py_project/.../my_agent/main.py

import jwt  # PyJWT

@app.post('/invocations')
async def invoke(input: InvokeInput, request: Request):
    token = request.headers['authorization'].removeprefix('Bearer ')
    claims = jwt.decode(token, options={'verify_signature': False})
    # authorize on claims['sub'], claims['scope'], ...

Ghi chú

JWT passthrough phù hợp với một nhà cung cấp danh tính duy nhất có token audience đã bao phủ runtime. Nếu một Gateway đặt phía trước các agent trên nhiều tenant hoặc audience, hãy sử dụng OAuth on-behalf-of token exchange thay thế.

Phát triển cục bộ

Chạy Gateway cục bộ với:

pnpm

pnpm nx dev <gateway-name>

yarn

yarn nx dev <gateway-name>

npm

npx nx dev <gateway-name>

bun

bunx nx dev <gateway-name>

khởi động một gateway cục bộ cộng với mọi agent được đính kèm trên cổng cục bộ được chỉ định của nó. Gateway cục bộ proxy các đường dẫn /<targetName>/... đến máy chủ cục bộ của mỗi agent, khớp với định tuyến dựa trên đường dẫn của Gateway đã triển khai.