TypeScript Agent

Tạo một TypeScript Agent để xây dựng các AI agent với công cụ, và tùy chọn triển khai nó lên Amazon Bedrock AgentCore Runtime. Mặc định, generator sử dụng tRPC qua WebSocket để tận dụng hỗ trợ streaming hai chiều của AgentCore cho giao tiếp thời gian thực, type-safe. Ngoài ra, bạn có thể chọn giao thức Agent-to-Agent (A2A) để tương tác với các agent tương thích A2A khác, hoặc giao thức AG-UI để tích hợp trực tiếp với frontend thông qua CopilotKit.

Strands là gì?

Strands là một framework nhẹ để xây dựng các AI agent. Các tính năng chính bao gồm:

Nhẹ và có thể tùy chỉnh: Vòng lặp agent đơn giản không cản trở bạn
Sẵn sàng cho production: Khả năng quan sát đầy đủ, tracing, và các tùy chọn triển khai cho quy mô lớn
Không phụ thuộc vào model và provider: Hỗ trợ nhiều model khác nhau từ nhiều provider
Công cụ do cộng đồng đóng góp: Bộ công cụ mạnh mẽ do cộng đồng đóng góp
Hỗ trợ đa agent: Các kỹ thuật nâng cao như nhóm agent và agent tự động
Chế độ tương tác linh hoạt: Hỗ trợ hội thoại, streaming, và non-streaming

Sử dụng

Tạo một Agent

Bạn có thể tạo một TypeScript Agent theo hai cách:

VSCode
CLI

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 - ts#agent
Điền các tham số bắt buộc
Nhấp Generate

pnpm nx g @aws/nx-plugin:ts#agent

yarn nx g @aws/nx-plugin:ts#agent

npx nx g @aws/nx-plugin:ts#agent

bunx nx g @aws/nx-plugin:ts#agent

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:ts#agent --dry-run

yarn nx g @aws/nx-plugin:ts#agent --dry-run

npx nx g @aws/nx-plugin:ts#agent --dry-run

bunx nx g @aws/nx-plugin:ts#agent --dry-run

Tùy chọn

Tham số	Kiểu	Mặc định	Mô tả
project Bắt buộc	string	-	Dự án để thêm Agent vào
framework	strands	strands	SDK agent cần sử dụng.
name	string	-	Tên của Agent của bạn (mặc định: agent)
auth	iam \| cognito	iam	Phương thức được sử dụng để xác thực với Agent của bạn. Chỉ áp dụng khi infra được thiết lập (bị bỏ qua khi infra là none).
protocol	http \| a2a \| ag-ui	http	Giao thức máy chủ cho Agent của bạn. HTTP cung cấp máy chủ tRPC/WebSocket. A2A cung cấp máy chủ giao thức Agent-to-Agent. AG-UI cung cấp máy chủ giao thức AG-UI để tích hợp trực tiếp frontend với CopilotKit.
iac	inherit \| cdk \| terraform	inherit	Nhà cung cấp IaC ưu tiên. Mặc định giá trị này được kế thừa từ lựa chọn ban đầu của bạn.
infra	agentcore \| none	agentcore	Loại hạ tầng để lưu trữ Agent của bạn.
preferInstallDependencies	boolean	true	Có nên cài đặt dependencies sau khi generator chạy hay không. Đặt thành false để 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.

Đầu ra của Generator

Generator sẽ thêm các file sau vào dự án TypeScript hiện có của bạn. Các file được tạo ra phụ thuộc vào protocol được chọn:

HTTP Protocol (mặc định)

Thư mụcyour-project/
- Thư mụcsrc/
  - Thư mụcagent/ (hoặc tên tùy chỉnh nếu được chỉ định)
    index.ts Điểm vào cho Bedrock AgentCore Runtime (tRPC/WebSocket server)
    init.ts Khởi tạo tRPC
    router.ts tRPC router với các agent procedure
    agent.ts Định nghĩa agent chính với các công cụ mẫu
    client.ts Client được cung cấp để gọi agent của bạn
    agent-core-trpc-client.ts Client factory để kết nối với các agent trên AgentCore Runtime
    Dockerfile Điểm vào để host agent của bạn (loại trừ khi infra được đặt thành None)
- package.json Được cập nhật với các dependency của Strands
- project.json Được cập nhật với các target serve agent

A2A Protocol

Điểm vào sử dụng Strands A2A Express Server thay vì tRPC:

Thư mụcyour-project/
- Thư mụcsrc/
  - Thư mụcagent/ (hoặc tên tùy chỉnh nếu được chỉ định)
    index.ts Điểm vào A2A Express server
    agent.ts Định nghĩa agent chính với các công cụ mẫu
    Dockerfile Điểm vào để host agent của bạn (loại trừ khi infra được đặt thành None)
- package.json Được cập nhật với các dependency của Strands và Express
- project.json Được cập nhật với các target serve agent

AG-UI Protocol

Điểm vào sử dụng @ag-ui/aws-strands để expose agent thông qua giao thức AG-UI (SSE qua POST), tương thích với CopilotKit:

Thư mụcyour-project/
- Thư mụcsrc/
  - Thư mụcagent/ (hoặc tên tùy chỉnh nếu được chỉ định)
    index.ts Điểm vào AG-UI server (Express + SSE)
    agent.ts Định nghĩa agent chính với các công cụ mẫu
    Dockerfile Điểm vào để host agent của bạn (loại trừ khi infra được đặt thành None)
- package.json Được cập nhật với các dependency của Strands và AG-UI
- project.json Được cập nhật với các target serve agent

Hạ tầng

Vì generator này cung cấp infrastructure as code dựa trên iacProvider bạn đã chọn, nó sẽ tạo một dự án trong packages/common bao gồm các CDK constructs hoặc Terraform modules liên quan.

Dự án infrastructure as code chung được cấu trúc như sau:

CDK
Terraform

Thư mụcpackages/common/constructs
- Thư mụcsrc
  - Thư mụcapp/ Constructs cho infrastructure cụ thể của một dự án/generator
    …
  - Thư mụccore/ Constructs chung được tái sử dụng bởi các constructs trong app
    …
  - index.ts Entry point xuất các constructs từ app
- project.json Các build targets và cấu hình của dự án

Thư mụcpackages/common/terraform
- Thư mụcsrc
  - Thư mụcapp/ Terraform modules cho infrastructure cụ thể của một dự án/generator
    …
  - Thư mụccore/ Modules chung được tái sử dụng bởi các modules trong app
    …
- project.json Các build targets và cấu hình của dự án

Để triển khai Agent của bạn, các file sau được tạo ra:

CDK
Terraform

Thư mụcpackages/common/constructs/src
- Thư mụcapp
  - Thư mụcagents
    Thư mục<project-name>
    <project-name>.ts CDK construct để triển khai agent của bạn

Nếu bạn chọn None cho infra, không có CDK construct hoặc Terraform module nào được tạo ra — Agent chỉ có thể chạy locally. Tùy chọn auth sẽ bị bỏ qua trong chế độ này vì không có endpoint được host để xác thực.

Khi triển khai lên Bedrock AgentCore Runtime, agent được xây dựng thành container image, đẩy lên Amazon ECR và chạy trong AgentCore Runtime. Các client gọi đến AgentCore Runtime data plane endpoint, endpoint này chuyển tiếp các yêu cầu đến agent của bạn. Agent gọi Amazon Bedrock để suy luận mô hình và có thể gọi các công cụ, MCP server, hoặc các API downstream.

Với infra: None, không có cơ sở hạ tầng AWS nào được tạo ra. Agent chạy như một tiến trình cục bộ và gọi Amazon Bedrock để suy luận mô hình.

Làm việc với Agent của bạn

Protocol

Giao thức server của agent xác định cách nó giao tiếp. Bạn có thể chọn giữa:

HTTP (mặc định): Sử dụng tRPC qua WebSocket cho giao tiếp thời gian thực, type-safe. Tốt nhất cho các tích hợp client tùy chỉnh và kiểm soát chi tiết API của agent.
A2A: Sử dụng giao thức Agent-to-Agent (A2A) cho giao tiếp chuẩn hóa giữa các agent. Tốt nhất khi agent của bạn cần có khả năng khám phá và gọi được bởi các agent tương thích A2A khác.
AG-UI: Sử dụng giao thức AG-UI (SSE qua POST) thông qua @ag-ui/aws-strands để tích hợp trực tiếp với frontend thông qua CopilotKit. Tốt nhất khi bạn muốn có giao diện chat phong phú với streaming, hiển thị tool-call, và quản lý trạng thái.

Giao thức được đặt trong hạ tầng CDK/Terraform, và code ứng dụng được tạo ra tương ứng.

tRPC qua WebSocket (HTTP protocol)

TypeScript Agent sử dụng tRPC qua WebSocket, tận dụng hỗ trợ streaming hai chiều của AgentCore để cho phép giao tiếp thời gian thực, type-safe giữa client và agent của bạn.

Vì tRPC hỗ trợ các procedure Query, Mutation và Subscription qua WebSocket, bạn có thể định nghĩa bất kỳ số lượng procedure nào. Mặc định, một subscription procedure duy nhất có tên invoke được định nghĩa cho bạn trong router.ts.

Thêm công cụ

Công cụ là các hàm mà AI agent có thể gọi để thực hiện các hành động. Bạn có thể thêm công cụ mới trong file agent.ts:

import { Agent, tool } from '@agents/sdk';
import { z } from 'zod';

const letterCounter = tool({
  name: 'letter_counter',
  description: 'Count occurrences of a specific letter in a word',
  inputSchema: z.object({
    word: z.string().describe('The input word to search in'),
    letter: z.string().length(1).describe('The specific letter to count'),
  }),
  callback: (input) => {
    const { word, letter } = input;
    const count = word.toLowerCase().split(letter.toLowerCase()).length - 1;
    return `The letter '${letter}' appears ${count} time(s) in '${word}'`;
  },
});

// Add tools to your agent
export const getAgent = async (sessionId: string) => {
  return new Agent({
    systemPrompt: 'You are a helpful assistant with access to various tools.',
    tools: [letterCounter],
  });
};

Framework Strands tự động xử lý:

Xác thực đầu vào sử dụng Zod schema
Tạo JSON schema cho việc gọi công cụ
Xử lý lỗi và định dạng response

Cấu hình Model

Mặc định, các Strands agent sử dụng Claude 4 Sonnet, nhưng bạn có thể dễ dàng chuyển đổi giữa các model provider:

import { Agent } from '@agents/sdk';
import { BedrockModel } from '@agents/sdk/models/bedrock';
import { OpenAIModel } from '@agents/sdk/models/openai';

// Use Bedrock
const bedrockModel = new BedrockModel({
  modelId: 'anthropic.claude-sonnet-4-20250514-v1:0',
});
let agent = new Agent({ model: bedrockModel });
let response = await agent.invoke('What can you help me with?');

// Alternatively, use OpenAI by just switching model provider
const openaiModel = new OpenAIModel({
  apiKey: process.env.OPENAI_API_KEY,
  modelId: 'gpt-4o',
});
agent = new Agent({ model: openaiModel });
response = await agent.invoke('What can you help me with?');

Xem tài liệu Strands về các model provider để biết thêm các tùy chọn cấu hình.

Sử dụng MCP Server

Bạn có thể thêm công cụ từ các MCP server vào Strands agent của bạn.

Để sử dụng các MCP Server mà bạn đã tạo bằng generator py#mcp-server hoặc ts#mcp-server bạn có thể sử dụng connection generator.

VSCode
CLI

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

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

Tham khảo hướng dẫn connection generator để biết chi tiết về cách thiết lập kết nối.

Đối với các MCP server khác, vui lòng tham khảo Tài liệu Strands.

Thêm

Để có hướng dẫn chi tiết hơn về viết Strands agent, tham khảo tài liệu Strands.

A2A Server (A2A protocol)

File index.ts được tạo ra gắn Strands A2A Express Server vào một Express app để agent được tạo ra expose các endpoint giao thức A2A cùng với health check /ping. Khi được triển khai lên AgentCore, điểm vào sẽ resolve ARN công khai của runtime từ AppConfig và quảng cáo nó trong agent card.

Hầu hết người dùng sẽ không cần sửa đổi file này — chỉnh sửa agent.ts để thay đổi công cụ hoặc system prompt. Các A2A agent lắng nghe trên cổng 9000 (so với 8080 cho HTTP), mà Dockerfile và hạ tầng được tạo ra đã được cấu hình sẵn.

AG-UI Server (AG-UI protocol)

File index.ts được tạo ra bao bọc Strands Agent của bạn trong một @ag-ui/aws-strands StrandsAgent và tạo một Express app thông qua createStrandsApp(). App kết quả expose một POST endpoint duy nhất stream các sự kiện AG-UI qua Server-Sent Events (SSE), cũng như /ping cho health check của AgentCore runtime.

Các AG-UI agent được thiết kế để được sử dụng trực tiếp bởi frontend. Sử dụng connection generator để kết nối React website của bạn với agent thông qua CopilotKit provider và AG-UI HttpAgent client.

Hầu hết người dùng sẽ không cần sửa đổi index.ts — chỉnh sửa agent.ts để thay đổi công cụ hoặc system prompt. Các AG-UI agent lắng nghe trên cổng 8080 (giống như HTTP), mà Dockerfile và hạ tầng được tạo ra đã được cấu hình sẵn.

Chạy Agent của bạn

Phát triển Local

Để chạy Agent của bạn (và mọi thứ được kết nối với nó) locally, sử dụng target dev của dự án:

pnpm nx dev your-project

yarn nx dev your-project

npx nx dev your-project

bunx nx dev your-project

Nếu bạn đã thêm nhiều component vào dự án của mình (agent, MCP server, v.v.), điều này sẽ khởi động tất cả chúng. Để chỉ chạy agent này, hãy target target <your-agent-name>-dev của nó:

pnpm nx agent-dev your-project

yarn nx agent-dev your-project

npx nx agent-dev your-project

bunx nx agent-dev your-project

Điều này sử dụng tsx --watch để tự động khởi động lại server khi các file thay đổi. Agent sẽ có sẵn tại http://localhost:8081 (hoặc cổng được gán nếu bạn có nhiều agent).

Chat với Agent của bạn

Generator cấu hình một target Nx <your-agent-name>-chat đưa bạn vào một terminal chat tương tác với agent của bạn.

Target chat chạy độc lập. Mặc định nó kết nối với agent đang chạy locally của bạn, vì vậy hãy khởi động target <your-agent-name>-dev của agent trước (trong một terminal riêng):

pnpm nx agent-dev your-project

yarn nx agent-dev your-project

npx nx agent-dev your-project

bunx nx agent-dev your-project

Sau đó, trong một terminal khác, khởi động chat:

pnpm nx run your-project:agent-chat

yarn nx run your-project:agent-chat

npx nx run your-project:agent-chat

bunx nx run your-project:agent-chat

Generator tạo ra một scripts/<your-agent-name>/chat.ts cho mọi protocol. Bạn có thể tùy chỉnh nó khi phát triển hình dạng đầu vào của agent. Nó kết nối với agent local theo mặc định, hoặc với agent đã triển khai của bạn khi RUNTIME_CONFIG_APP_ID được thiết lập (xem Chat với agent đã triển khai của bạn bên dưới).

Chat với agent đã triển khai của bạn

Để chat với agent của bạn đã triển khai lên Bedrock AgentCore, thiết lập biến môi trường RUNTIME_CONFIG_APP_ID thành AppConfig application id của deployment (được xuất ra dưới dạng RuntimeConfigApplicationId bởi stack đã triển khai). Script chat sẽ phân giải runtime ARN của agent từ runtime configuration và kết nối với endpoint đã triển khai:

IAM
Cognito

Đối với các agent được xác thực bằng IAM, các request được ký bằng SigV4 sử dụng AWS credentials mặc định của bạn. Đảm bảo môi trường có AWS credentials với quyền invoke runtime:

RUNTIME_CONFIG_APP_ID=<app-id> pnpm nx run your-project:agent-chat

RUNTIME_CONFIG_APP_ID=<app-id> yarn nx run your-project:agent-chat

RUNTIME_CONFIG_APP_ID=<app-id> npx nx run your-project:agent-chat

RUNTIME_CONFIG_APP_ID=<app-id> bunx nx run your-project:agent-chat

Đối với các agent được xác thực bằng Cognito, cung cấp Cognito access token thông qua biến môi trường AGENT_ACCESS_TOKEN, được gửi dưới dạng bearer token:

RUNTIME_CONFIG_APP_ID=<app-id> AGENT_ACCESS_TOKEN=<access-token> pnpm nx run your-project:agent-chat

RUNTIME_CONFIG_APP_ID=<app-id> AGENT_ACCESS_TOKEN=<access-token> yarn nx run your-project:agent-chat

RUNTIME_CONFIG_APP_ID=<app-id> AGENT_ACCESS_TOKEN=<access-token> npx nx run your-project:agent-chat

RUNTIME_CONFIG_APP_ID=<app-id> AGENT_ACCESS_TOKEN=<access-token> bunx nx run your-project:agent-chat

Bạn có thể lấy access token bằng cách sử dụng lệnh cognito-idp admin-initiate-auth của AWS CLI, ví dụ:

aws cognito-idp admin-initiate-auth \
  --user-pool-id <user-pool-id> \
  --client-id <user-pool-client-id> \
  --auth-flow ADMIN_NO_SRP_AUTH \
  --auth-parameters USERNAME=<username>,PASSWORD=<password> \
  --query 'AuthenticationResult.AccessToken' \
  --output text

Triển khai Agent của bạn lên Bedrock AgentCore Runtime

Infrastructure as Code

Nếu bạn đã chọn agentcore cho infra, cơ sở hạ tầng CDK hoặc Terraform liên quan sẽ được tạo ra mà bạn có thể sử dụng để triển khai Agent của mình lên Amazon Bedrock AgentCore Runtime.

CDK
Terraform

Một CDK construct được tạo ra cho agent của bạn, được đặt tên dựa trên name bạn đã chọn khi chạy trình tạo, hoặc mặc định là <ProjectName>Agent.

Bạn có thể sử dụng CDK construct này trong một ứng dụng CDK:

import { MyProjectAgent } from ':my-scope/common-constructs';

export class ExampleStack extends Stack {
  constructor(scope: Construct, id: string) {
    new MyProjectAgent(this, 'MyProjectAgent');
  }
}

Một module Terraform được tạo ra cho bạn, được đặt tên dựa trên name bạn đã chọn khi chạy trình tạo, hoặc mặc định là <ProjectName>-agent.

Truyền các output của module runtime_config_appconfig được chia sẻ vào module agent:

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

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

Docker là bắt buộc để xây dựng và triển khai Agent của bạn. Hãy đảm bảo bạn đã cài đặt và khởi chạy Docker để tránh các lỗi như:

ERROR: Cannot connect to the Docker daemon at unix://path/to/docker.sock.

Xác thực

Trình tạo cung cấp tùy chọn auth để cấu hình xác thực cho Agent của bạn. Bạn có thể chọn giữa xác thực IAM (mặc định) hoặc Cognito khi tạo agent của mình.

IAM

Theo mặc định, Agent của bạn sẽ được bảo mật bằng xác thực IAM, chỉ cần triển khai nó mà không cần bất kỳ tham số nào:

CDK
Terraform

import { MyProjectAgent } from ':my-scope/common-constructs';

export class ExampleStack extends Stack {
  constructor(scope: Construct, id: string) {
    new MyProjectAgent(this, 'MyProjectAgent');
  }
}

Bạn có thể cấp quyền truy cập để gọi agent của mình trên Bedrock AgentCore Runtime bằng phương thức grantInvokeAccess, ví dụ:

import { MyProjectAgent } from ':my-scope/common-constructs';

export class ExampleStack extends Stack {
  constructor(scope: Construct, id: string) {
    const agent = new MyProjectAgent(this, 'MyProjectAgent');
    const lambdaFunction = new Function(this, ...);

    agent.grantInvokeAccess(lambdaFunction);
  }
}

# Agent
module "my_project_agent" {
  # Relative path to the generated module in the common/terraform project
  source = "../../common/terraform/src/app/agents/my-project-agent"

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

Để cấp quyền truy cập gọi agent của bạn, bạn sẽ cần thêm một policy như sau, tham chiếu đến output module.my_project_agent.agent_core_runtime_arn:

{
  Effect = "Allow"
  Action = [
    "bedrock-agentcore:InvokeAgentRuntime"
  ]
  Resource = [
    module.my_project_agent.agent_core_runtime_arn,
    "${module.my_project_agent.agent_core_runtime_arn}/*"
  ]
}

Xác thực Cognito

Khi bạn chọn xác thực Cognito, trình tạo sẽ cấu hình agent để sử dụng Cognito cho xác thực.

CDK
Terraform

Construct được tạo ra chấp nhận một prop identity để cấu hình xác thực Cognito:

import { MyProjectAgent, UserIdentity } from ':my-scope/common-constructs';

export class ExampleStack extends Stack {
  constructor(scope: Construct, id: string) {
    const identity = new UserIdentity(this, 'Identity');

    new MyProjectAgent(this, 'MyProjectAgent', {
      identity,
    });
  }
}

Construct UserIdentity có thể được tạo bằng trình tạo ts#website#auth, hoặc bạn có thể tạo UserPool và UserPoolClient CDK của riêng mình.

Module được tạo ra chấp nhận các biến user_pool_id và user_pool_client_ids cho xác thực Cognito:

module "user_identity" {
  source = "../../common/terraform/src/core/user-identity"
}

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

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

  user_pool_id         = module.user_identity.user_pool_id
  user_pool_client_ids = [module.user_identity.user_pool_client_id]
}

Bundle Target

Generator tự động cấu hình một target bundle sử dụng Rolldown để tạo gói triển khai:

pnpm nx bundle <project-name>

yarn nx bundle <project-name>

npx nx bundle <project-name>

bunx nx bundle <project-name>

Cấu hình Rolldown có thể được tìm thấy trong rolldown.config.ts, với một entry cho mỗi bundle cần tạo. Rolldown quản lý việc tạo nhiều bundle song song nếu được định nghĩa.

Bundle target sử dụng index.ts làm entrypoint cho WebSocket server để host trên Bedrock AgentCore Runtime.

Docker Target

Generator cấu hình một target <your-agent-name>-docker sao chép Dockerfile từ thư mục source agent của bạn vào thư mục output bundle. Điều này đặt Dockerfile cùng với các artifact đã được bundle, cho phép CDK build Docker image trực tiếp sử dụng AgentRuntimeArtifact.fromAsset.

Một target docker cũng được tạo ra để chuẩn bị docker context cho tất cả các agent nếu bạn có nhiều agent được định nghĩa.

Khả năng quan sát

Agent của bạn được tự động cấu hình với khả năng quan sát sử dụng AWS Distro for Open Telemetry (ADOT), bằng cách cấu hình auto-instrumentation trong Dockerfile của bạn.

Bạn có thể tìm thấy các trace trong CloudWatch AWS Console, bằng cách chọn “GenAI Observability” trong menu. Lưu ý rằng để các trace được điền, bạn sẽ cần bật Transaction Search.

Để biết thêm chi tiết, tham khảo tài liệu AgentCore về khả năng quan sát.

Gọi Agent của bạn

Giao tiếp với agent được truyền qua tRPC qua WebSocket. Do đó, nên sử dụng client factory type-safe được tạo ra trong client.ts.

Gọi Local Server

Bạn có thể gọi một agent đang chạy locally sử dụng phương thức factory .local từ client factory.

Bạn có thể, ví dụ, tạo một file có tên scripts/test.ts trong workspace của bạn để import client:

import { AgentClient } from '../packages/<project>/src/agent/client.js';

const client = AgentClient.local({ url: 'http://localhost:8081/ws' });

client.invoke.subscribe({ message: 'what is 1 plus 1?' }, { onData: console.log });

Chạy với tsx như một cách nhanh chóng để kiểm tra agent của bạn.

pnpm tsx scripts/test.ts

yarn tsx scripts/test.ts

npx tsx scripts/test.ts

bunx tsx scripts/test.ts

Gọi Agent đã triển khai

Để gọi Agent của bạn đã triển khai lên Bedrock AgentCore Runtime, bạn có thể gửi một yêu cầu POST đến điểm cuối dataplane của Bedrock AgentCore Runtime với ARN runtime đã được mã hóa URL.

Bạn có thể lấy ARN runtime từ cơ sở hạ tầng của mình như sau:

CDK
Terraform

import { CfnOutput } from 'aws-cdk-lib';
import { MyProjectAgent } from ':my-scope/common-constructs';

export class ExampleStack extends Stack {
  constructor(scope: Construct, id: string) {
    const agent = new MyProjectAgent(this, 'MyProjectAgent');

    new CfnOutput(this, 'AgentArn', {
      value: agent.agentCoreRuntime.agentRuntimeArn,
    });
  }
}

# Agent
module "my_project_agent" {
  # Relative path to the generated module in the common/terraform project
  source = "../../common/terraform/src/app/agents/my-project-agent"

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

output "agent_arn" {
  value = module.my_project_agent.agent_core_runtime_arn
}

ARN sẽ có định dạng như sau: arn:aws:bedrock-agentcore:<region>:<account>:runtime/<agent-runtime-id>.

Sau đó, bạn có thể mã hóa URL cho ARN bằng cách thay thế : bằng %3A và / bằng %2F.

Điều này rất đơn giản trong console trình duyệt hoặc Node REPL bằng cách sử dụng phương thức encodeURIComponent có sẵn:

encodeURIComponent('arn:aws:bedrock-agentcore:<region>:<account>:runtime/<agent-runtime-id>')

URL dataplane của Bedrock AgentCore Runtime để gọi agent như sau:

https://bedrock-agentcore.<region>.amazonaws.com/runtimes/<url-encoded-arn>/invocations

Cách chính xác để gọi URL này phụ thuộc vào phương thức xác thực được sử dụng.

NodeJS

File client.ts được tạo ra bao gồm một client factory type-safe có thể được sử dụng để gọi agent đã triển khai của bạn.

IAM
Cognito

Xác thực IAM

Bạn có thể gọi agent đã triển khai của bạn bằng cách truyền ARN của nó vào phương thức factory withIamAuth:

import { AgentClient } from './agent/client.js';

const client = AgentClient.withIamAuth({
  agentRuntimeArn: 'arn:aws:bedrock-agentcore:us-west-2:123456789012:runtime/my-agent',
});

client.invoke.subscribe({ message: 'what is 1 plus 1?' }, {
  onData: (message) => console.log(message),
  onError: (error) => console.error(error),
  onComplete: () => console.log('Done'),
});

Xác thực JWT / Cognito

Sử dụng phương thức factory withJwtAuth để xác thực với JWT / Cognito access token.

const client = AgentClient.withJwtAuth({
  agentRuntimeArn: 'arn:aws:bedrock-agentcore:us-west-2:123456789012:runtime/my-agent',
  accessTokenProvider: async () => `<access-token>`,
});

client.invoke.subscribe({ message: 'what is 1 plus 1?' }, {
  onData: console.log,
});

accessTokenProvider phải trả về token được sử dụng để xác thực request. Bạn có thể, ví dụ, lấy token trong phương thức này để đảm bảo rằng credential mới được tái sử dụng khi tRPC khởi động lại kết nối WebSocket. Ví dụ dưới đây cho thấy việc sử dụng AWS SDK để lấy token từ Cognito:

import { CognitoIdentityProvider } from "@aws-sdk/client-cognito-identity-provider";

const cognito = new CognitoIdentityProvider();

const jwtClient = AgentClient.withJwtAuth({
  agentRuntimeArn: 'arn:aws:bedrock-agentcore:us-west-2:123456789012:runtime/my-agent',
  accessTokenProvider: async () => {
    const response = await cognito.adminInitiateAuth({
      UserPoolId: '<user-pool-id>',
      ClientId: '<user-pool-client-id>',
      AuthFlow: 'ADMIN_NO_SRP_AUTH',
      AuthParameters: {
        USERNAME: '<username>',
        PASSWORD: '<password>',
      },
    });
    return response.AuthenticationResult!.AccessToken!;
  },
});

Browser / React Website

Để gọi Agent của bạn từ một React website, bạn có thể sử dụng connection generator, generator này tự động thiết lập tRPC WebSocket client với xác thực đúng (IAM hoặc Cognito).

VSCode
CLI

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

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

Tham khảo hướng dẫn connection generator để biết chi tiết về cách thiết lập kết nối.

Gọi một A2A Agent như một Công cụ

Để ủy quyền công việc từ agent này cho một remote A2A agent (có thể là TypeScript hoặc Python), sử dụng connection generator. Nó cung cấp một client được xác thực SigV4 cho target agent và AST-transform file agent.ts của agent này để đăng ký remote A2A agent như một tool của Strands.

VSCode
CLI

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

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

Tham khảo hướng dẫn connection generator để biết chi tiết về cách thiết lập kết nối.

Gọi một AG-UI Agent

Để gọi AG-UI agent của bạn từ một React website, sử dụng connection generator, generator này kết nối một CopilotKit client được cấu hình cho agent đã triển khai của bạn với xác thực đúng (IAM hoặc Cognito).

VSCode
CLI

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

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

Tham khảo hướng dẫn connection generator để biết chi tiết về cách thiết lập kết nối.

Kết nối

Sử dụng generator connection để tích hợp dự án này với các dự án khác trong workspace của bạn. Các kết nối sau liên quan đến dự án này:

React to TypeScript Agent Gọi TypeScript Agent từ một trang web React

React to AG-UI Agent Gọi Agent hỗ trợ giao thức AG-UI từ một trang web React thông qua CopilotKit

TypeScript Agent to MCP Kết nối TypeScript Agent với MCP server

TypeScript Agent to A2A Agent Kết nối TypeScript Agent với A2A agent từ xa

Python Agent to A2A Agent Kết nối Python Agent với A2A agent từ xa

TypeScript Agent to Relational Database Kết nối TypeScript Agent với cơ sở dữ liệu quan hệ Aurora

TypeScript Agent to TypeScript DynamoDB Kết nối TypeScript Agent với bảng DynamoDB

TypeScript Agent to AgentCore Gateway Kết nối TypeScript Agent với AgentCore Gateway