RAAGENT 文档中心

Appearance

会话、异步消息与 SSE ​

会话接口均需要 Bearer Key，并严格隔离当前账号的会话。模型由 Agent 引擎运行后自动发现，所有会话和消息请求都不接受 model 参数。

接口 ​

方法与路径说明
GET /api/v1/sessions分页查询会话。
POST /api/v1/sessions创建空会话，或携带首消息创建并运行。
GET /api/v1/sessions/{id}查询会话，可选包含最近消息。
PATCH /api/v1/sessions/{id}更新标题、工作模式或 effort。
DELETE /api/v1/sessions/{id}删除会话。
GET /api/v1/sessions/{id}/messages游标分页查询持久化消息。
POST /api/v1/sessions/{id}/messages向已有会话发送消息。
POST /api/v1/sessions/{id}/abort停止会话当前运行，并清除该会话待处理消息。
GET /api/v1/sessions/{id}/cost查询会话成本和引擎实际上报的模型。

会话对象包含以下字段：

字段类型说明
idstring会话 ID
titlestring标题
agentIdstring智能体 ID
agentNamestring智能体展示名称
statusstringactive（空闲）、processing（运行中）、queued（排队中）
modestring?工作模式
effortstring?运行强度
modelstring?引擎运行后上报的实际模型
lastMessagestring?最近一条消息文本
updatedAtstring更新时间（ISO 8601）
messageCountnumber?消息数
groupstring?今天、本周、更早
unreadnumber?未读数
processingboolean?是否运行中（有 turn 正在执行）
pendingRunsnumber?排队中的消息数；>0 时会话 status 为 queued，当前未执行
lastMsgAtnumber?最近消息时间（Unix 毫秒）
lastActiveAtnumber?最近活跃时间（Unix 毫秒）

查询会话列表 ​

参数位置类型必填可选值默认值限制
agentIdQuerystring否智能体 ID——
keywordQuerystring否任意文本——
qQuerystring否keyword 的别名——
sortQuerystring否lastMsgAt、-createdAt、createdAt最近消息优先—
pageQueryinteger否—1最小 1
pageSizeQueryinteger否—201～50
http
GET /api/v1/sessions?page=1&pageSize=20 HTTP/1.1
Host: raagent.me
Authorization: Bearer raa-REPLACE_WITH_YOUR_KEY

HTTP 200，data 为 { items, total, page, pageSize, hasMore }：

json
{
  "code": "0",
  "message": "ok",
  "data": {
    "items": [
      {
        "id": "s-01JQ2R8X1A3B4C5D6E7F8G9",
        "title": "仓库分析",
        "agentId": "raagent/code-review-3f8a1b2c",
        "agentName": "代码审查助手",
        "status": "active",
        "mode": "default",
        "effort": "default",
        "model": "claude-opus-4-8",
        "lastMessage": "继续给出最小修复方案",
        "updatedAt": "2026-08-04T09:30:00.000Z",
        "messageCount": 12,
        "group": "今天",
        "unread": 0,
        "processing": false,
        "lastMsgAt": 1722730200000,
        "lastActiveAt": 1722730200000
      }
    ],
    "total": 1,
    "page": 1,
    "pageSize": 20,
    "hasMore": false
  }
}

错误：400 参数不合法；401 凭据缺失或无效。

创建空会话 ​

不提供 content 时创建空会话并返回 HTTP 201 和统一 envelope。

字段位置类型必填可选值默认值限制
agentIdBodystring是可用智能体 ID—最短 1
titleBodystring否任意标题服务端生成最短 1
modeBodystring否default、accept-edits、auto、plandefault工作模式，不是权限模式
effortBodystring否low、default、medium、highdefault—
http
POST /api/v1/sessions HTTP/1.1
Host: raagent.me
Authorization: Bearer raa-REPLACE_WITH_YOUR_KEY
Content-Type: application/json

{
  "agentId": "raagent/code-review-3f8a1b2c",
  "title": "仓库分析"
}

HTTP 201，data 为会话对象：

json
{
  "code": "0",
  "message": "ok",
  "data": {
    "id": "s-01JQ2R8X1A3B4C5D6E7F8G9",
    "title": "仓库分析",
    "agentId": "raagent/code-review-3f8a1b2c",
    "agentName": "代码审查助手",
    "status": "active",
    "mode": "default",
    "effort": "default",
    "updatedAt": "2026-08-04T09:30:00.000Z",
    "messageCount": 0,
    "group": "今天",
    "unread": 0,
    "processing": false,
    "lastMsgAt": 1722730200000,
    "lastActiveAt": 1722730200000
  }
}

错误：400 校验失败（如智能体无法使用）；401 凭据缺失或无效。

创建并发送首条消息 ​

提供 content 时成功返回 HTTP 202。

字段位置类型必填可选值默认值限制
agentIdBodystring是可用智能体 ID—最短 1
titleBodystring否任意标题服务端生成最短 1
modeBodystring否default、accept-edits、auto、plandefault工作模式
effortBodystring否low、default、medium、highdefault—
contentBodystring是首条消息—1～100000
options.effortBodystring否引擎支持的 effort——
options.permissionModeBodystring否default、accept-edits、auto、plan会话当前 mode仅覆盖本次运行；不传则沿用会话模式
http
POST /api/v1/sessions HTTP/1.1
Host: raagent.me
Authorization: Bearer raa-REPLACE_WITH_YOUR_KEY
Content-Type: application/json
Accept: application/json

{
  "agentId": "raagent/code-review-3f8a1b2c",
  "content": "分析这个仓库的测试失败原因",
  "options": {
    "effort": "medium",
    "permissionMode": "default"
  }
}

HTTP 202，响应不使用统一 envelope，仅含 sessionId、status（queued 时额外返回 taskId 与 queueReason；会话忙或主机并发满均可能排队，见下文「会话忙时排队」）：

json
{
  "sessionId": "s-01JQ2R8X1A3B4C5D6E7F8G9",
  "status": "processing"
}

202 只表示请求已接受。随后用 GET /api/v1/sessions/{id} 和 GET /api/v1/sessions/{id}/messages 查询状态与结果。错误：400 校验失败；503 运行所需服务暂不可用。

会话忙时排队（status: "queued"） ​

若会话正在处理上一条消息，新的消息会进入等待状态：

json
{
  "sessionId": "s-01JQ2R8X1A3B4C5D6E7F8G9",
  "status": "queued",
  "taskId": "80d817a9-55f7-4130-96b4-ff06e6d3ee9d",
  "queueReason": "session_busy"
}

queueReason 为 session_busy 时表示当前会话正在处理上一条消息；为 host_capacity 时表示主机并发已满。当前消息或其他任务完成后，等待消息会自动执行，无需调用方干预。每个会话最多等待 10 条消息，超出返回 409。取消会话或调用「停止会话当前运行」接口会清除尚未处理的消息。

排队时即使请求头带 Accept: text/event-stream，也返回上述 JSON 202（不建立 SSE 流），请通过 taskId 或会话消息接口查询结果。

向已有会话发送消息 ​

参数位置类型必填可选值默认值限制
idPathstring是当前账号的会话 ID—最短 1
AcceptHeaderstring否application/json、text/event-streamapplication/json最长 128
contentBodystring是消息内容—1～100000
options.effortBodystring否引擎支持的 effort——
options.permissionModeBodystring否default、accept-edits、auto、plan会话当前 mode仅覆盖本次运行；不传则沿用会话模式
http
POST /api/v1/sessions/s-01JQ2R8X1A3B4C5D6E7F8G9/messages HTTP/1.1
Host: raagent.me
Authorization: Bearer raa-REPLACE_WITH_YOUR_KEY
Content-Type: application/json
Accept: application/json

{
  "content": "继续给出最小修复方案",
  "options": {
    "effort": "medium",
    "permissionMode": "default"
  }
}

HTTP 202，响应不使用统一 envelope：

json
{
  "sessionId": "s-01JQ2R8X1A3B4C5D6E7F8G9",
  "status": "processing"
}

202 只表示请求已接受。模型由引擎运行后上报，不需要也不能在请求中指定。若会话已有 turn 在运行，返回 status: "queued"（额外带 taskId），消息入队等当前 turn 结束后自动执行，详见上文「会话忙时排队」。错误：400 校验失败（如 Content-Type 非 application/json）；404 会话不存在；409 排队队列已满（最多 10 条）；503 运行所需服务暂不可用。

停止会话当前运行 ​

参数位置类型必填可选值默认值限制
idPathstring是当前账号的会话 ID—最短 1
http
POST /api/v1/sessions/s-01JQ2R8X1A3B4C5D6E7F8G9/abort HTTP/1.1
Host: raagent.me
Authorization: Bearer raa-REPLACE_WITH_YOUR_KEY

HTTP 200，data 为 { sessionId, status }：

json
{
  "code": "0",
  "message": "ok",
  "data": {
    "sessionId": "s-01JQ2R8X1A3B4C5D6E7F8G9",
    "status": "aborted"
  }
}

停止当前正在运行的任务：通知主机终止引擎进程，并清除该会话所有等待中的消息（排队中的消息不再执行）。会话本身保留，之后可继续发送新消息。已生成但未完成的内容会以中断形式保留在消息记录中。幂等：重复调用仍返回 200，无任务在运行时仅将会话状态复位为可用。错误：404 会话不存在。

同路径 SSE ​

将同一消息 POST 请求的 Accept 改为 text/event-stream。创建并发送首消息的路径也支持相同内容协商。SSE 成功建立时返回 HTTP 200。

http
POST /api/v1/sessions/s-01JQ2R8X1A3B4C5D6E7F8G9/messages HTTP/1.1
Host: raagent.me
Authorization: Bearer raa-REPLACE_WITH_YOUR_KEY
Content-Type: application/json
Accept: text/event-stream

{
  "content": "逐步分析测试失败"
}

HTTP 200，后续为 text/event-stream 帧流。每帧由 event: 与 data: 组成，事件包括：

事件说明
accepted请求已接受，开始运行
snapshot当前快照
message.delta增量文本，data.delta
tool.started工具开始，data.toolName
tool.completed工具结束，data.toolName、data.isError
run.completed运行成功结束
run.error运行失败结束
text
event: accepted
data: {"sessionId":"s-01JQ2R8X1A3B4C5D6E7F8G9","status":"processing"}

event: snapshot
data: {"sessionId":"s-01JQ2R8X1A3B4C5D6E7F8G9","status":"processing"}

event: message.delta
data: {"sessionId":"s-01JQ2R8X1A3B4C5D6E7F8G9","status":"processing","delta":"好的，"}

event: tool.started
data: {"sessionId":"s-01JQ2R8X1A3B4C5D6E7F8G9","status":"processing","toolName":"Bash"}

event: tool.completed
data: {"sessionId":"s-01JQ2R8X1A3B4C5D6E7F8G9","status":"processing","toolName":"Bash","isError":false}

event: run.completed
data: {"sessionId":"s-01JQ2R8X1A3B4C5D6E7F8G9","status":"completed"}

连接每 15 秒发送一条注释心跳。断线后仍可通过消息列表查询已持久化结果。

查询会话详情 ​

参数位置类型必填可选值默认值限制
idPathstring是会话 ID—最短 1
includeMessagesQuerystring否true、falsefalse—
messageLimitQueryinteger否—201～50
http
GET /api/v1/sessions/s-01JQ2R8X1A3B4C5D6E7F8G9?includeMessages=true&messageLimit=5 HTTP/1.1
Host: raagent.me
Authorization: Bearer raa-REPLACE_WITH_YOUR_KEY

HTTP 200，data 为会话对象；includeMessages=true 时额外包含 messages 数组：

json
{
  "code": "0",
  "message": "ok",
  "data": {
    "id": "s-01JQ2R8X1A3B4C5D6E7F8G9",
    "title": "仓库分析",
    "agentId": "raagent/code-review-3f8a1b2c",
    "agentName": "代码审查助手",
    "status": "active",
    "mode": "default",
    "effort": "default",
    "model": "claude-opus-4-8",
    "lastMessage": "继续给出最小修复方案",
    "updatedAt": "2026-08-04T09:30:00.000Z",
    "messageCount": 12,
    "group": "今天",
    "unread": 0,
    "processing": false,
    "lastMsgAt": 1722730200000,
    "lastActiveAt": 1722730200000,
    "messages": [
      {
        "id": "msg-01JQ2R8X1A3B4C5D6E7F8GA",
        "sessionId": "s-01JQ2R8X1A3B4C5D6E7F8G9",
        "role": "assistant",
        "timestamp": "2026-08-04T09:29:00.000Z",
        "provider": "claude",
        "kind": "text",
        "content": "已定位到测试失败原因",
        "seq": 2
      },
      {
        "id": "msg-01JQ2R8X1A3B4C5D6E7F8GA",
        "sessionId": "s-01JQ2R8X1A3B4C5D6E7F8G9",
        "role": "user",
        "timestamp": "2026-08-04T09:30:00.000Z",
        "provider": "claude",
        "kind": "text",
        "content": "继续给出最小修复方案",
        "seq": 3
      }
    ]
  }
}

错误：400 参数不合法；404 会话不存在。

查询消息 ​

参数位置类型必填可选值默认值限制
idPathstring是会话 ID—最短 1
beforeQuerystring否消息 ID 游标—不能与 after 同时使用
afterQuerystring否消息 ID 游标—不能与 before 同时使用
limitQueryinteger否—201～50
http
GET /api/v1/sessions/s-01JQ2R8X1A3B4C5D6E7F8G9/messages?limit=20 HTTP/1.1
Host: raagent.me
Authorization: Bearer raa-REPLACE_WITH_YOUR_KEY

HTTP 200，data 为 { items, total, hasMore, firstId, lastId }。items 为规范化消息数组，kind 取值 text、thinking、tool_use、tool_result；tool_use 含 toolName/toolInput，tool_result 含 toolResult：

json
{
  "code": "0",
  "message": "ok",
  "data": {
    "items": [
      {
        "id": "msg-01JQ2R8X1A3B4C5D6E7F8GA",
        "sessionId": "s-01JQ2R8X1A3B4C5D6E7F8G9",
        "role": "user",
        "timestamp": "2026-08-04T09:30:00.000Z",
        "provider": "claude",
        "kind": "text",
        "content": "继续给出最小修复方案",
        "seq": 3
      },
      {
        "id": "msg-01JQ2R8X1A3B4C5D6E7F8GB",
        "sessionId": "s-01JQ2R8X1A3B4C5D6E7F8G9",
        "role": "assistant",
        "timestamp": "2026-08-04T09:30:05.000Z",
        "provider": "claude",
        "kind": "tool_use",
        "toolName": "Bash",
        "toolId": "msg-01JQ2R8X1A3B4C5D6E7F8GB_t",
        "toolInput": { "command": "npm test" },
        "seq": 4
      },
      {
        "id": "msg-01JQ2R8X1A3B4C5D6E7F8GB_r",
        "sessionId": "s-01JQ2R8X1A3B4C5D6E7F8G9",
        "role": "assistant",
        "timestamp": "2026-08-04T09:30:10.000Z",
        "provider": "claude",
        "kind": "tool_result",
        "toolId": "msg-01JQ2R8X1A3B4C5D6E7F8GB_t",
        "toolResult": { "content": "7 failed", "isError": true },
        "seq": 4
      }
    ],
    "total": 12,
    "hasMore": false,
    "firstId": "msg-01JQ2R8X1A3B4C5D6E7F8GA",
    "lastId": "msg-01JQ2R8X1A3B4C5D6E7F8GB_r"
  }
}

错误：400 参数不合法（如 before 与 after 同时使用）；404 会话不存在。

更新或删除会话 ​

参数位置类型必填可选值默认值限制
idPathstring是会话 ID—最短 1

PATCH 只接受以下字段：

字段位置类型必填可选值默认值限制
titleBodystring否任意标题—最短 1
modeBodystring否default、accept-edits、auto、plan—工作模式
effortBodystring否low、default、medium、high——
http
PATCH /api/v1/sessions/s-01JQ2R8X1A3B4C5D6E7F8G9 HTTP/1.1
Host: raagent.me
Authorization: Bearer raa-REPLACE_WITH_YOUR_KEY
Content-Type: application/json

{
  "title": "仓库测试失败分析"
}

HTTP 200，data 为更新后的会话对象：

json
{
  "code": "0",
  "message": "ok",
  "data": {
    "id": "s-01JQ2R8X1A3B4C5D6E7F8G9",
    "title": "仓库测试失败分析",
    "agentId": "raagent/code-review-3f8a1b2c",
    "agentName": "代码审查助手",
    "status": "active",
    "mode": "default",
    "effort": "default",
    "updatedAt": "2026-08-04T09:31:00.000Z",
    "messageCount": 12,
    "group": "今天",
    "unread": 0,
    "processing": false,
    "lastMsgAt": 1722730200000,
    "lastActiveAt": 1722730200000
  }
}

删除会话：

http
DELETE /api/v1/sessions/s-01JQ2R8X1A3B4C5D6E7F8G9 HTTP/1.1
Host: raagent.me
Authorization: Bearer raa-REPLACE_WITH_YOUR_KEY

HTTP 200：

json
{
  "code": "0",
  "message": "ok",
  "data": {
    "deleted": true
  }
}

删除成功后该会话不能继续使用。错误：404 会话不存在或不属于当前账号。

查询会话用量 ​

参数位置类型必填可选值默认值限制
idPathstring是会话 ID—最短 1
http
GET /api/v1/sessions/s-01JQ2R8X1A3B4C5D6E7F8G9/cost HTTP/1.1
Host: raagent.me
Authorization: Bearer raa-REPLACE_WITH_YOUR_KEY

HTTP 200，data 包含模型与 Token 统计。cost = inputTokens + outputTokens × 2：

json
{
  "code": "0",
  "message": "ok",
  "data": {
    "model": "claude-opus-4-8",
    "messageCount": 12,
    "inputTokens": 152300,
    "outputTokens": 48200,
    "totalTokens": 200500,
    "cost": 248700
  }
}

错误：404 会话不存在。