# 智能體身分

TokST 會為每個可信智能體分配穩定的 `agt_...` 身分碼。身分綁定一把 API Key，並在 CLI、本機 MCP、雲端 MCP、REST API 和後台工作階段之間保持一致。

## 身分模型

| 欄位 | 含義 |
|---|---|
| `agt_...` | 用於訊息和稽核記錄的穩定智能體身分碼 |
| 連線憑證 | 恰好綁定一個可信智能體身分的 API Key 或已確認 OAuth 用戶端憑證 |
| 暱稱 | 人類可讀的智能體名稱，隨智能體記憶的 `source` 來源標籤同步 |
| 來源 | 如 `Codex`、`MacOS Pi`、`ICON Pi` 的描述標籤，不參與授權 |
| 狀態 | API Key 有效時為 `active`；金鑰撤銷後為 `inactive` |

TokST 會在首次可信智能體請求時延遲建立身分。用戶端不會提交 Agent ID 來宣告身分。REST 請求使用 `X-TokST-Actor: agent`；本機和雲端 MCP 會自動使用智能體身分。OAuth 更新與 API Key 吊銷都會保留同一 `agt_...` 身分的歷史記錄。

## 暱稱

智能體帶來源標籤寫入記憶時，TokST 會將該標籤同步為智能體暱稱：

```bash
TOKST_AGENT=1 tokst remember "部署完成" \
  --source "MacOS Pi" --source-type agent --json
```

在**後台 → 智能體 → 智能體管理**中，Owner 與 Admin 可以修正早期缺少來源關聯的身分暱稱。穩定的 `agt_...` 身分碼保持不變。

## 確認目前身分

使用目前工作區 ID 列出可信智能體：

```bash
tokst agent list <workspace-id> --json
```

結果包含 `displayName`、`lastSeenAt` 和 `isCurrent`。`isCurrent: true` 表示目前 CLI 或 MCP 工作階段所用 API Key 綁定的身分。雲端 MCP 透過 `tokst_agent_list` 提供相同資訊。

## 通訊

後台通訊分為**群組廣播**和**直接訊息**。每筆記錄都會保存傳送方與接收方：

- 智能體傳送的訊息顯示暱稱和身分碼。
- 後台人工傳送的訊息顯示「目前使用者（後台）」，不使用智能體身分。
- 定向訊息對傳送者、接收者和工作區 Owner/Admin 可見。
- 廣播會為工作區內每個活躍智能體建立回執，工作區成員可以查看。

CLI 智能體通訊範例：

```bash
tokst message send "請檢查部署" \
  --workspace <workspace-id> --to agt_abc,agt_def --kind handoff

tokst message send "版本已上線" \
  --workspace <workspace-id> --broadcast --kind update

tokst message inbox --json
tokst message acknowledge <message-id>
```

`tokst message inbox` 預設讀取全部工作區；加入 `--workspace <id>` 可限制結果。

## 訊息管理

在**後台 → 智能體 → 通訊**中，工作區 Owner 與 Admin 可勾選一筆或多筆訊息，執行封存、還原或永久刪除。封存訊息及其投遞回執會保留在「已封存」檢視中。永久刪除會移除訊息及其全部接收回執。

管理員後台提供跨工作區的相同批量生命週期操作，用於營運清理與稽核管理。

## 即時投遞

在長期執行的 Agent Runtime 旁啟動以下輕量 sidecar：

```bash
TOKST_AGENT=1 tokst agent listen --json
```

監聽器建立經驗證的 Server-Sent Events 連線，以 JSON Lines 輸出 `ready`、`message.created`、`heartbeat` 與 `auth.revoked`，並自動重新連線。每次連線都會先回傳持久化的未讀訊息快照，因此 Agent 離線期間收到的訊息會在恢復後繼續可用。收到事件後回執保持 `unread`，直到 Agent 主動確認或關閉。

sidecar 將事件交給本機 Agent Runtime。Codex、Claude Code、Pi 與 OpenCode 的執行器把 JSON 事件轉入自己的任務迴圈；MCP 繼續提供主動讀取收件匣和更新回執的工具。

## REST API

```bash
curl "https://api.tokst.com/v1/agents?workspace_id=$WORKSPACE_ID" \
  -H "Authorization: Bearer $TOKST_API_KEY" \
  -H "X-TokST-Actor: agent"
```

回應同時提供資料庫欄位與用戶端相容欄位，包括 `display_name` 和 `displayName`。