跳到主要内容

Session API

Xiaohe Agent 提供 REST Session API，用于以程序方式驱动 Agent 工作流。它驱动的是真实 CLI 后端 —— Claude、Kimi、Codex、Cursor —— 不是另一套独立 Agent SDK。

用 OS 服务生命周期命令启动本机控制面：

xiaohe server ensure    # 安装 + 启动；还没有桌面密钥时写一把
xiaohe server install   # 只装服务单元
xiaohe server start

本机默认地址是 http://127.0.0.1:8110。托管 Session 使用运维方给你的地址和密钥，它可能位于私有网络而非公网。各类窗口各自需要什么，见快速开始。

鉴权​

开启鉴权后，每个 /v1/* 请求（健康检查与公开 UI 路径除外）都需要 Bearer token：

Authorization: Bearer <api-key|access-jwt>

在控制面主机上签发与管理密钥：

xiaohe server pair        # 签发密钥并打印；--write-client（默认）写入桌面应用
xiaohe keys issue --tenant local --label mac
xiaohe keys list
xiaohe keys revoke <id|prefix>

EventSource 与 SSE 无法携带请求头，这两处要把密钥作为查询参数：

GET /v1/sessions/{id}/events?access_token=<key>&after=0&follow=true

核心接口​

方法路径作用
POST/v1/sessions创建托管会话
GET/v1/sessions/{id}会话状态
POST/v1/sessions/{id}/messages发送用户消息
GET/v1/sessions/{id}/eventsSSE 事件流
POST/v1/sessions/{id}/approvals批准或拒绝待确认动作
POST/v1/sessions/{id}/cancel取消生成中的回复
DELETE/v1/sessions/{id}结束会话
GET/v1/me调用方身份与工作区提示
GET/PUT/v1/provider列出或切换 Claude LLM provider
GET/PUT/v1/voice/provider列出或切换 TTS/STT provider

创建会话​

POST /v1/sessions

{
  "tenant_id": "demo",
  "backend": "claude",
  "skill_ids": ["demo.echo"],
  "message": "optional first turn",
  "workspace_path": "/absolute/path/to/project",
  "persistent": false
}
  • backend —— claude（默认）、kimi、codex、cursor，或用于本地测试的 fake。会话代理真实 CLI；claude 使用 Agent SDK 做 token 流式与跨回合 --resume。
  • workspace_path —— 调用方项目的绝对路径，作为工作目录。省略则使用沙箱工作区。
  • persistent —— 为会话保持长生命周期主机进程，而不是每回合起停。
  • skill_ids —— 限制会话可加载的产品技能。

消息与事件​

用 POST /v1/sessions/{id}/messages 发送回合：

{"content": "Hello"}

进度经 SSE 到达。用 after=<last_event_seq> 重连以续传：

GET /v1/sessions/{id}/events?after=0&follow=true

附件​

上传文件上限 50 MiB：

  • POST /v1/sessions/{id}/attachments —— multipart 字段 file，返回 {id, name, mime, size, kind}
  • GET /v1/sessions/{id}/attachments —— 列出元数据
  • GET /v1/sessions/{id}/attachments/{att_id} —— 下载字节

入站附件会以本机路径追加到提示里，agent 的 Read 与图片工具随即可以读取。

转写​

GET /v1/sessions/{id}/messages 返回稳定聊天气泡，是界面重开时的真相源。分页可选且最新优先：limit（1–500）配合 before_created_at 加 before_msg_id 的 keyset 游标；省略 limit 则返回全文。

批准​

POST /v1/sessions/{id}/approvals

{"approval_id": "...", "approved": true, "note": ""}

当 Agent 需要决策时，会话进入 waiting_approval，并在 SSE 流上发出 approval_required 事件。

工作区​

  • GET /v1/me —— 调用方建议的 workspace_path
  • GET /v1/workspaces —— 该密钥租户下已注册的工作区
  • POST /v1/workspaces —— 确保或注册工作区

语音​

语音合成与识别使用同一个地址、同一把密钥。

  • POST /v1/tts —— 文本转音频（audio/mpeg）。Body {"text", "voice", "tenant_id"}。音色：zh_male_m191_uranus_bigtts（经典男声）、zh_female_xiaohe_uranus_bigtts（经典女声）、ICL_uranus_zh_female_yuanqitianmei_tob（阳光甜妹）。最多 2000 字。
  • POST /v1/stt —— multipart file 转 {"text": "..."}（豆包 flash ASR）。

相关​