# 智能体身份

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`。