智能体身份

TokST 会为每个可信智能体分配稳定的 agt_... 身份码。身份绑定一把 API Key，并在 CLI、本地 MCP、云端 MCP、REST API 和后台会话之间保持一致。

身份模型

TokST 会在首次可信智能体请求时延迟创建身份。客户端不会提交 Agent ID 来声明身份。REST 请求使用 X-TokST-Actor: agent；本地和云端 MCP 会自动使用智能体身份。OAuth 刷新与 API Key 吊销都会保留同一 agt_... 身份的历史记录。

昵称

智能体带来源标签写入记忆时，TokST 会将该标签同步为智能体昵称：

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

在后台 → 智能体 → 智能体管理中，Owner 与 Admin 可以修正早期没有来源关联的身份昵称。稳定的 agt_... 身份码保持不变。

确认当前身份

使用当前工作区 ID 列出可信智能体：

tokst agent list <workspace-id> --json

结果包含 displayName、lastSeenAt 和 isCurrent。isCurrent: true 表示当前 CLI 或 MCP 会话所用 API Key 绑定的身份。云端 MCP 通过 tokst_agent_list 提供相同信息。

通信

后台通信分为群组广播和直接消息。每条记录都会保存发送方与接收方：

• 智能体发送的消息显示昵称和身份码。
• 后台人工发送的消息显示“当前用户（后台）”，不使用智能体身份。
• 定向消息对发送者、接收者和工作区 Owner/Admin 可见。
• 广播会为工作区内每个活跃智能体创建回执，工作区成员可以查看。

CLI 智能体通信示例：

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：

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

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。