# AgentRole

> Create and name multiple agents (a role is a system prompt + model + plugin list), then attach one to a workspace or session in AI Chat.

| | |
|---|---|
| Version | 1.0.5 |
| Category | AI & Agents |
| Depends on | ai-chat |

# AgentRole

Tạo và đặt tên nhiều **agent** (vai trò). Mỗi agent gói sẵn: tên + avatar + `systemPrompt` + danh sách
plugin. Agent được gán vào workspace/session của plugin **AI Chat** để tự động cấp bộ plugin + áp
system-prompt cho phiên chat (xem `plugins-library/ai-chat/.claude/features/attach-agent-role.md`).
Agent **không** đặt model — phiên luôn dùng model hiện tại của chính nó.

**Type:** `backend` — see `.claude/skills/kazuo-create-plugin/references/plugin-examples.md`

## Mô hình dữ liệu

`settings.agents: Array<{ id, name, systemPrompt, plugins: string[], avatar }>`

- `id`: **đặt được lúc TẠO** (ô ID trong trình soạn) — slug `^[a-z0-9][a-z0-9-]{0,63}$`, unique; để trống
  thì tự sinh (`genId()`). **Khoá (read-only) khi sửa** để không gãy các tham chiếu `[agent-<id>]`.
- `systemPrompt`: có thể chứa tag tham chiếu `[agent-<id>]` (vd `[agent-kazuo-ui]`). Đây là **text nhắc
  tên thuần** — KHÔNG expand ở runtime; trình soạn có autocomplete (gõ `[agent-` → chọn agent → chèn
  `[agent-<id>]`). Dùng để agent/Manager biết id agent nào tồn tại mà `dispatch_agent(role: '<id>')`.
- `device`: **thiết bị mặc định** để `dispatch_agent` chạy agent này (`''` = máy hiện tại/local). Dropdown
  trong trình soạn lấy từ `plugin:device-manager:fleet-devices`. Khi Manager gọi `dispatch_agent(role)` mà
  KHÔNG truyền `device`, dùng giá trị này.
- `cwd`: **thư mục làm việc mặc định** cho agent (`''` = mặc định của máy đích). Tương tự, tool arg `cwd`
  (nếu có) sẽ được ưu tiên; không có thì dùng `cwd` của role.
- `plugins`: id các plugin (đang bật, có MCP tool) mà agent này gói theo.
- `avatar`: ảnh upload đã thu nhỏ về **32×32** (PNG data URL); rỗng = dùng ô chữ cái đầu tên. Thu nhỏ
  bằng canvas ngay trong renderer nên settings không phình to.

## Files

- `manifest.json` — metadata, `defaultSettings` (`{ agents: [] }`), `defaultWidgetConfig`
- `widget.html` / `js/widget.js` / `css/widget.css` — UI quản lý agent (danh sách + trình soạn:
  tên, model, system prompt, checklist plugin). Đọc/ghi `agents` qua `getSettings`/`setSettings`.
- `settings.html` / `js/settings.js` — trang thông tin ngắn (Plugin Manager); agent quản lý trong widget.
- `locales/en.json5` / `locales/vi.json5` — UI strings, namespace `widget.*` / `settings.*`
- `main/index.ts` (+ compiled `main/index.js`) — chạy ở Electron main process; chỉ 1 IPC read-only
  `plugin:agent-role:list-plugins` trả danh sách plugin đang bật có tool (cho checklist trong trình
  soạn). Việc lưu agent do renderer làm; ai-chat đọc `agents` trực tiếp qua `pluginControl`.

## Default settings

- `agents` — default: `[]`

## Test

Mở Kazuo AI → Plugin Manager — plugin xuất hiện tự động (host tự quét `plugins-library/`) → Install →
Enable. Tạo vài agent trong widget (đặt tên, viết system-prompt, tick plugin), rồi qua plugin
**AI Chat**: chuột phải vào thư mục hoặc phiên → "🎭 Gán agent" → chọn agent → gửi tin để agent kết
nối với bộ plugin + system-prompt đã gán (model vẫn là model đang chọn của phiên).

Sau khi sửa `main/index.ts`, biên dịch lại trước khi test: `npx tsc -p tsconfig.plugins.json`
(chạy từ project root).

## Orchestration tools (Manager Role — chia việc đa thiết bị)

`main/index.ts` export `getMcpTools` với 4 tool cho phép một role điều phối agent Claude Code chạy
local hoặc trên máy khác của cùng tài khoản (qua fleet relay). Chi tiết kiến trúc + bảo mật:
`.claude/features/distributed-agent-orchestration.md`.

- `list_devices` — máy của account + trạng thái online.
- `dispatch_agent({task, cwd?, device?, role?, model?, mode?, timeoutMs?})` — chạy 1 việc; trả `{jobId}`
  ngay (async). `device` rỗng/self = local; khác = remote. `role` = tên/id agent trên MÁY NÀY (resolve
  systemPrompt+plugins rồi truyền sang worker).
- `agent_status({jobId})` — snapshot không chặn.
- `agent_result({jobId, maxWaitMs?})` — poll có giới hạn (mặc định 90s), trả text khi xong; `running` thì gọi lại.

Tool nạp khi agent-role nằm trong bundle của session — **không cần Dev Mode** (đường MCP của ai-chat
không gate theo Dev Mode). Cần `zod` (khai trong `package.json`) + `ai-chat` bật (dùng
`globalThis.__kazuoAiChat.runAgent` cho local). Máy nhận việc cần bật kill-switch `acceptRemoteDispatch`
(mặc định on) + `claude` đã login.

**Preset "Manager" systemPrompt** (dán vào role, bundle `agent-role` + `task-manager`):
> Bạn là Manager điều phối. Chẻ yêu cầu thành các việc con ĐỘC LẬP. Mỗi việc gọi `dispatch_agent`
> (đặt `device` nếu cần máy khác — xem `list_devices`). Gọi nhiều `dispatch_agent` trong một lượt để
> chạy song song, rồi `agent_result(jobId)` từng việc và tổng hợp. Ghi tiến độ qua task-manager.