React đến AG-UI Agent

Nx Plugin for AWS cung cấp một generator để kết nối trang web React với Agent mà expose giao thức AG-UI. Nó kết nối CopilotKit với một @ag-ui/client HttpAgent trên trang web của bạn, với hỗ trợ xác thực AWS IAM và Cognito.

Đ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 trang web React (được tạo bằng generator ts#website)
2. Một TypeScript hoặc Python Agent với protocol=ag-ui (được tạo bằng generator ts#agent hoặc py#agent)
3. Đối với các agent đã triển khai, Cognito Auth được thêm qua generator ts#website#auth

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

Bạn sẽ được nhắc chọn trang web React của mình làm source project và project chứa AG-UI Agent của bạn làm target project. Nếu target project của bạn chứa nhiều component (chẳng hạn như nhiều agent hoặc các loại component khác), bạn sẽ được nhắc chỉ định một 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.

Đầu ra của Generator

Generator tạo ra một component AguiProvider được chia sẻ duy nhất, một hook cho mỗi agent được kết nối, và một wrapper có theme cho các component chat của CopilotKit:

• Thư mụcsrc

  • Thư mụccomponents

    • AguiProvider.tsx CopilotKitProvider duy nhất cho mọi AG-UI agent. Được tạo trong lần chạy connection đầu tiên và được cập nhật trong các lần chạy tiếp theo để đăng ký từng agent mới.
    • Thư mụccopilot

      • index.tsx Re-export CopilotChat, CopilotSidebar và CopilotPopup với các slot mặc định khớp với ux của trang web của bạn (Cloudscape, Shadcn, hoặc không có theme).
      • ThemeComponents .tsx Các component theme theo từng slot (ví dụ: CloudscapeAssistantMessage.tsx, ShadcnChatInput.tsx). Chỉ được cung cấp khi ux là cloudscape hoặc shadcn.
  • Thư mụchooks

    • useAgui<AgentName>.tsx Đăng ký một AG-UI agent. Một file cho mỗi lần chạy connection.
    • useSigV4.tsx Ký SigV4 (chỉ IAM)

Chạy connection lần thứ hai cho một agent khác thêm một hook useAgui<AgentName>.tsx mới và cập nhật AguiProvider.tsx để đăng ký cả hai hook — mọi chỉnh sửa tùy chỉnh mà bạn đã thực hiện đối với provider đều được giữ nguyên. main.tsx giữ wrapper <AguiProvider> duy nhất của nó — bạn sẽ không bao giờ có các provider lồng nhau.

Các dependency sau được thêm vào package.json gốc:

• @copilotkit/react-core — cung cấp CopilotKitProvider và các component chat (CopilotChat, CopilotSidebar, CopilotPopup)
• @ag-ui/client — HttpAgent được sử dụng bởi các hook được tạo
• aws4fetch, oidc-client-ts, react-oidc-context, @aws-sdk/credential-providers — chỉ xác thực IAM
• react-oidc-context — xác thực Cognito

Cách hoạt động

Kết nối AG-UI

Mỗi hook useAgui<AgentName> đọc giá trị runtime của agent từ Runtime Configuration và khởi tạo một @ag-ui/client HttpAgent:

• Đã triển khai: giá trị runtime là một Bedrock AgentCore Runtime ARN, được chuyển đổi thành endpoint HTTPS của AgentCore: https://bedrock-agentcore.<region>.amazonaws.com/runtimes/<encoded-arn>/invocations?qualifier=DEFAULT
• Phát triển cục bộ: dev ghi đè giá trị thành URL cục bộ của agent (ví dụ: http://localhost:8081)

AguiProvider được chia sẻ gọi mọi hook được tạo và spread từng hook vào selfManagedAgents trên một CopilotKitProvider duy nhất, expose tất cả chúng cho các component CopilotKit.

Tích hợp CopilotKit

CopilotKit là React client tham chiếu chính thức cho giao thức AG-UI và đi kèm với các component chat sẵn có:

• <CopilotChat /> — giao diện chat đầy đủ
• <CopilotSidebar /> — chat panel bên cố định
• <CopilotPopup /> — popup chat nổi

Đặt bất kỳ component nào trong số này ở bất kỳ đâu bên trong wrapper <AguiProvider> (đã được kết nối vào main.tsx cho bạn).

Xác thực

Code được tạo xử lý xác thực tùy thuộc vào cấu hình của agent:

• IAM (mặc định): sử dụng các HTTP request được ký AWS SigV4. Thông tin xác thực được lấy từ Cognito Identity Pool được cấu hình với auth của trang web của bạn.
• Cognito: nhúng JWT access token vào header Authorization dưới dạng Bearer token.

Sessions và Threads

AG-UI và AgentCore Runtime mỗi cái xác định một cuộc hội thoại theo cách khác nhau, và hook được tạo liên kết chúng lại với nhau:

• threadId — định danh cuộc hội thoại AG-UI, được gửi trong request body. CopilotKit tạo một UUID ngẫu nhiên cho mỗi cuộc trò chuyện trừ khi bạn truyền một threadId rõ ràng.
• Session ID — session AgentCore Runtime, được gửi trong header X-Amzn-Bedrock-AgentCore-Runtime-Session-Id. Nó chọn microVM phục vụ request, và là thứ mà session.ts / session.py của agent của bạn dùng làm khóa cho trạng thái cuộc hội thoại.

Hook suy ra session ID từ thread ID, đệm phải nó đến 33 ký tự mà AgentCore Runtime yêu cầu:

function agentCoreSessionId(input: RunAgentInput): string {
  return (input.threadId ?? '').padEnd(33, '0');
}

Để threadId không được đặt là đơn giản nhất — UUID được tạo bởi CopilotKit đã có 36 ký tự. Nếu bạn truyền một cách rõ ràng, hãy đảm bảo nó có ít nhất 33 ký tự, vì việc đệm ánh xạ các thread ID chỉ khác nhau ở các ký tự cuối vào cùng một session.

Cả Session ID và Thread ID đều được cung cấp bởi trình duyệt. Để hạn chế mỗi người dùng chỉ truy cập các cuộc hội thoại của riêng họ, hãy tham khảo hướng dẫn py#agent hoặc ts#agent.

Hạ tầng

Nếu agent của bạn sử dụng xác thực IAM, vai trò được xác thực của Cognito Identity Pool phải được cấp quyền để gọi agent.

CDK

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

const identity = new UserIdentity(this, 'Identity');
const myAgent = new MyAgent(this, 'MyAgent');

// Grant the authenticated Cognito role permission to invoke the agent
myAgent.grantInvokeAccess(identity.identityPool.authenticatedRole);

grantInvokeAccess kết nối tất cả các hành động gọi AgentCore (InvokeAgentRuntime, InvokeAgentRuntimeWithWebSocketStream) trên ARN runtime của agent.

Terraform

packages/infra/src/main.tf

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

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 authenticated Cognito role permission to invoke the agent
resource "aws_iam_policy" "invoke_my_agent" {
  name = "InvokeMyAgentPolicy"
  policy = jsonencode({
    Version = "2012-10-17"
    Statement = [{
      Effect = "Allow"
      Action = [
        "bedrock-agentcore:InvokeAgentRuntime",
        "bedrock-agentcore:InvokeAgentRuntimeWithWebSocketStream",
      ]
      Resource = [
        module.my_agent.agent_core_runtime_arn,
        "${module.my_agent.agent_core_runtime_arn}/*",
      ]
    }]
  })
}

resource "aws_iam_role_policy_attachment" "invoke_my_agent" {
  role       = module.identity.authenticated_role_name
  policy_arn = aws_iam_policy.invoke_my_agent.arn
}

Nếu agent của bạn sử dụng xác thực Cognito, bạn không cần định nghĩa thêm bất kỳ cơ sở hạ tầng nào để kết nối website của bạn với agent.

Sử dụng Code được tạo

Thêm giao diện Chat

Khởi tạo các component CopilotKit với agentId để chọn agent nào sẽ sử dụng. Id là tên của agent — cùng tên mà bạn đã chọn khi chạy generator ts#agent hoặc py#agent — và bạn cũng có thể tìm thấy nó trong file hook được tạo (ví dụ: key được trả về từ packages/web/src/hooks/useAgui<AgentName>.tsx).

Import các component chat từ module ./components/copilot được tạo để theme khớp với ux của trang web của bạn được áp dụng tự động:

import { CopilotChat } from './components/copilot';

function ChatPage() {
  return (
    <CopilotChat
      agentId="agent"
      labels={{
        welcomeMessageText: 'How can I help you today?',
        chatInputPlaceholder: 'Ask me anything...',
      }}
    />
  );
}

Kết nối nhiều AG-UI Agent

Chạy generator connection một lần cho mỗi agent. Mọi agent được đăng ký qua AguiProvider được chia sẻ đều hiển thị từ bất kỳ đâu trong ứng dụng — khởi tạo một component CopilotKit với agentId khác nhau để định tuyến mỗi cuộc trò chuyện đến agent bạn muốn:

import { CopilotChat } from './components/copilot';

<CopilotChat agentId="story" />    {/* talks to StoryAgent */}
<CopilotChat agentId="research" /> {/* talks to ResearchAgent */}

Tùy chỉnh giao diện

<CopilotChat /> (và <CopilotSidebar />, <CopilotPopup />) sử dụng hệ thống slot đệ quy — bạn có thể ghi đè bất kỳ sub-component nào bằng chuỗi class Tailwind, object prop, hoặc component React tùy chỉnh. Xem hướng dẫn slots của CopilotKit để biết cây slot đầy đủ.

Theme tích hợp sẵn

Generator đọc metadata.ux từ project trang web React của bạn và cung cấp một module wrapper có theme tại src/components/copilot/index.tsx để các component chat khớp với phần còn lại của UI của bạn mà không cần cấu hình thêm:

ux	Styling được áp dụng cho CopilotChat / CopilotSidebar / CopilotPopup
cloudscape	Các tin nhắn được render bên trong Cloudscape ChatBubble với gen-AI Avatar (khớp với mẫu chat generative AI của Cloudscape); chỉ báo đang gõ trở thành LoadingBar và input là PromptInput. Được xây dựng từ @cloudscape-design/components và @cloudscape-design/chat-components.
shadcn	Tin nhắn của assistant được render trong bubble bg-muted với avatar Sparkles; tin nhắn của người dùng được render căn phải trong bubble bg-primary với avatar User. Input là Textarea bo tròn + Button gửi/dừng hình viên thuốc (Enter để gửi, Shift+Enter để xuống dòng). Sử dụng các primitive shadcn từ package common-shadcn được chia sẻ.
none (hoặc bất kỳ giá trị nào khác)	Không có theme — module chỉ re-export các component CopilotKit mặc định.

Import các component có theme từ module theme cục bộ (không phải trực tiếp từ @copilotkit/react-core/v2) để theme được áp dụng tự động:

import { CopilotChat } from './components/copilot';

<CopilotChat agentId="agent" />

Theme được áp dụng dưới dạng các slot mặc định, vì vậy bất kỳ slot nào bạn truyền một cách rõ ràng vẫn được ưu tiên — bạn vẫn giữ toàn quyền kiểm soát bất cứ khi nào bạn cần ghi đè một lần.

Tùy chỉnh Theme

Theme được tạo nằm hoàn toàn bên trong project của bạn:

• src/components/copilot/index.tsx — export CopilotChat / CopilotSidebar / CopilotPopup có theme và các object cloudscapeCopilotTheme / shadcnCopilotTheme. Chỉnh sửa file này để thay đổi kết nối slot mặc định cho mọi chat trong ứng dụng của bạn.
• src/components/copilot/<ThemeComponent>.tsx — các component theme theo từng slot (ví dụ: CloudscapeAssistantMessage, ShadcnChatInput). Chỉnh sửa những file này để điều chỉnh giao diện của một slot duy nhất mà không cần kết nối lại theme.

Ví dụ: để thay thế renderer tin nhắn người dùng của riêng bạn trong khi vẫn giữ phần còn lại của theme, hãy chỉnh sửa file liên quan trong src/components/copilot/ và re-export nó từ index.tsx.

Styling Tailwind qua slots

Các ghi đè theo từng chat vẫn hoạt động cùng với theme — bất kỳ thứ gì bạn truyền dưới dạng slot prop đều ghi đè mặc định có theme:

<CopilotChat
  agentId="agent"
  // style the input and its children
  input={{
    textArea: 'text-blue-600',
    sendButton: 'bg-blue-600 hover:bg-blue-700',
  }}
  // style nested message slots
  messageView={{
    assistantMessage: 'bg-blue-50 rounded-xl p-2',
    userMessage: 'bg-blue-100 rounded-xl',
  }}
/>

Thay thế slot bằng component tùy chỉnh

Bất kỳ slot nào cũng có thể nhận một component React thay vì className, vì vậy bạn có thể thay thế hoàn toàn mặc định:

import { CopilotChat } from './components/copilot';

const MySendButton: React.FC<{ onClick: () => void }> = ({ onClick }) => (
  <button onClick={onClick} className="my-send-btn">
    Send
  </button>
);

<CopilotChat
  agentId="agent"
  input={{ sendButton: MySendButton }}
/>;

Các ghi đè sâu hơn tuân theo cùng một hình dạng — ví dụ: chỉ thay thế nút sao chép trên tin nhắn của assistant:

<CopilotChat
  agentId="agent"
  messageView={{
    assistantMessage: {
      copyButton: ({ onClick }) => <button onClick={onClick}>Copy</button>,
    },
  }}
/>

Phát triển cục bộ

Generator connection tự động cấu hình tích hợp dev:

1. Chạy nx dev <website> cũng sẽ khởi động server cục bộ của agent
2. Runtime config được ghi đè để trỏ đến URL AG-UI cục bộ (ví dụ: http://localhost:8081)
3. Cả trang web và agent đều hot-reload cùng nhau

pnpm

pnpm nx dev <WebsiteProject>

yarn

yarn nx dev <WebsiteProject>

npm

npx nx dev <WebsiteProject>

bun

bunx nx dev <WebsiteProject>

Hot Reloading

Trang web và agent được kết nối hot-reload cùng nhau, cho phép bạn nhanh chóng lặp lại trên cả hai phía mà không cần triển khai lên AWS.

Thông tin thêm

• Hướng dẫn TypeScript Agent
• Hướng dẫn Python Agent
• Tài liệu giao thức AG-UI
• Tài liệu CopilotKit + AWS Strands
• CopilotKit Custom Look & Feel
• Bedrock AgentCore Runtime