> ## Documentation Index
> Fetch the complete documentation index at: https://octop.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Octop 对话 API：WebSocket 流式传输与线程管理

> 通过 WebSocket 与 Octop 专家对话并流式接收回复，并使用线程管理端点组织对话历史。

通过 WebSocket 与专家对话，实时流式接收回复，并管理对话线程。

## WebSocket 端点

```text theme={null}
WS /api/agents/{id}/chat/ws?token=<jwt>
```

由于浏览器 WebSocket API 不支持自定义头，令牌需作为查询参数传递，而不是 `Authorization` 头。

## 消息帧

向专家发送一轮对话：

```json theme={null}
{"type": "user_turn", "content": "你好！", "thread_id": "abc123"}
```

服务器以流式块回应：

```json theme={null}
{"type": "chunk", "content": "你好！我能"}
```

回复完成时发送：

```json theme={null}
{"type": "done"}
```

若发生错误：

```json theme={null}
{"type": "error", "message": "模型请求超时"}
```

为保持连接存活，可发送 ping/pong 帧：

```json theme={null}
{"type": "ping"}
```

```json theme={null}
{"type": "pong"}
```

断线本身**不会**取消正在进行的回合。重连后发送 `subscribe` 可挂接到仍在流式输出的线程；服务器以 `turn_status` 回应：

```json theme={null}
{"type": "subscribe", "thread_id": "abc123"}
```

```json theme={null}
{"type": "turn_status", "thread_id": "abc123", "active": true}
```

显式停止当前回合：

```json theme={null}
{"type": "cancel", "thread_id": "abc123"}
```

> [!NOTE]
>
> `thread_id` 在整个对话中保持不变。若需在断开后恢复会话，请使用创建线程时返回的 `session_key`。页面刷新后先拉 history，根据 `turn_active` 再决定是否 `subscribe`。

## 线程管理

| 方法 | 路径 | 描述 |
| - | - | - |
| GET | `/agents/{id}/chat/sessions` | 列出对话线程 |
| POST | `/agents/{id}/chat/sessions` | 创建新线程 |
| PATCH | `/agents/{id}/chat/sessions/{thread_id}` | 重命名或固定线程 |
| DELETE | `/agents/{id}/chat/sessions/{thread_id}` | 删除线程 |
| GET | `/agents/{id}/chat/sessions/{thread_id}/history` | 获取线程历史记录（含 `turn_active`） |
| GET | `/agents/{id}/threads/{thread_id}/trajectory` | 分页运行轨迹摘要，用 `before_seq` 取更早记录 |
| GET | `/agents/{id}/threads/{thread_id}/trajectory/events/{event_id}` | 单条事件完整载荷 |
| GET | `/agents/{id}/threads/{thread_id}/trajectory/metrics` | 回合、耗时与 token 汇总 |
| GET | `/agents/{id}/threads/{thread_id}/trajectory/stream` | 实时 SSE，用 `after_seq` 或 `Last-Event-ID` 续传 |
| GET | `/agents/{id}/threads/{thread_id}/trajectory/export` | 导出账本，默认 JSONL，也可 JSON |

## 创建线程

```bash theme={null}
curl -X POST http://127.0.0.1:8088/api/agents/1/chat/sessions \
  -H 'Authorization: Bearer <token>'
```

响应：

```json theme={null}
{"thread_id": "abc123", "session_key": "sk_..."}
```

## 获取历史记录

```bash theme={null}
curl "http://127.0.0.1:8088/api/agents/1/chat/sessions/abc123/history?limit=50&offset=0" \
  -H 'Authorization: Bearer <token>'
```

支持 `limit` 和 `offset` 分页参数。响应还包含布尔字段 `turn_active`：为 `true` 时，请重新打开聊天 WebSocket 并发送 `{"type":"subscribe","thread_id":"..."}` 以恢复流式输出。

## 重命名或固定线程

```bash theme={null}
curl -X PATCH http://127.0.0.1:8088/api/agents/1/chat/sessions/abc123 \
  -H 'Authorization: Bearer <token>' \
  -H 'Content-Type: application/json' \
  -d '{"title": "项目规划讨论", "pinned": true}'
```

## 润饰端点

在实际发送之前优化用户输入的提示词文本：

```bash theme={null}
curl -X POST http://127.0.0.1:8088/api/agents/1/chat/polish \
  -H 'Authorization: Bearer <token>' \
  -H 'Content-Type: application/json' \
  -d '{"text": "帮我写个邮件"}'
```

响应：

```json theme={null}
{"text": "请帮我草拟一封专业的邮件，受信人是..."}
```

可选参数 `default_model` 可用于覆盖润饰时使用的模型。

## 分叉会话

`POST /api/agents/{id}/threads/{thread_id}/fork` 把一段对话复制成新线程，截止到指定的专家回复。原对话不变。传 `assistant_turns_from_end: 1` 可从最新一条回复分叉，或传入 `message_id`。专家需要处于运行中。

## 文件与知识库引用

线程列表和历史会带上专家生成的文件（例如写文件、桌面截图），以及回复用到知识库时的来源文档。页面里点击引用可在聊天中预览文档。

## 运行轨迹

`GET /agents/{id}/threads/{thread_id}/trajectory*` 对应聊天里的**运行轨迹**抽屉：分页事件摘要、单条完整事件、汇总指标、实时 SSE 和导出。需要审计回合与工具调用时用这些接口，不必刮页面。

> [!TIP]
>
> 润饰端点很适合用于 UI 中的“润饰提示词”按钮——在实际发射前帮用户把输入润色为更清晰、更具体的提示词。


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.