AgentCore Gateway đến Agent

Generator connection có thể đăng ký một agent (có thể là TypeScript hoặc Python) như một 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 đường dẫn <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 truy cập 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 agent component (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 đến runtime) đều hoạt động.

TypeScript HTTP agents

Một agent TypeScript http phục vụ tRPC qua WebSocket, và AgentCore Gateway không hỗ trợ WebSocket hoặc bidirectional streaming — generator sẽ 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

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 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ả của Generator

Generator kết nối các dự án hiện có với nhau thay vì tạo ra các tệp nguồn mới. Các tệp 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 để local gateway 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 gateway.addAgent(agent).

CDK

Trong stack nơi bạn khởi tạo Gateway, hãy đăng ký agent như một 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 cho execution role của Gateway đến agent runtime và cấu hình target với credential provider GATEWAY_IAM_ROLE, do đó 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 một agent được triển khai trong VPC có thể truy cập được: người gọi giao tiếp với endpoint công khai của Gateway, và Gateway truy cập 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 để kết nối với 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 lỗ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 tệp 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 một agent được triển khai trong VPC có thể truy cập được: người gọi giao tiếp với endpoint công khai của Gateway, và Gateway truy cập 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 để kết nối với 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, do đó người gọi sử dụng cùng hình thức yêu cầu như khi họ gọi trực tiếp đến 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), do đó 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 đó sẽ chuyển tiếp JWT của người gọi đến runtime mà 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 đứng trước cùng Cognito user pool.

Mọi thứ khác đều tự động — gateway.addAgent(agent) (CDK) và module runtime Terraform được tạo sẽ 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 để token được chuyển tiếp đến được mã agent của bạn. Không có allowlist này, AgentCore xác thực token nhưng loại bỏ header trước khi đến container của bạn.

Người gọi invoke 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 identity provider duy nhất có token audience đã bao phủ runtime. Nếu một Gateway đứng 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 local gateway cùng với mọi agent được gắn kết trên cổng cục bộ được chỉ định của nó. Local gateway proxy các đường dẫn /<targetName>/... đến server 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.