---
title: "会话 API：发起任务、读取和管理会话"
description: "Halo HTTP API 会话接口：发起一轮任务、停止运行、查看进行中的会话，列出、读取、重命名、星标和删除会话。"
type: "reference"
audience: ["developer"]
lang: "zh-CN"
canonical: "https://hello-halo.cc/docs/developers/api/conversation.html"
last_updated: "2026-10-19T00:11:17+08:00"
source: "Halo 3.0.4 docs"
---
# API：会话

Halo HTTP API 会话接口：发起一轮任务、停止运行、查看进行中的会话，列出、读取、重命名、星标和删除会话。

会话是工作区里你和 Halo 助手之间的对话线程。API 按工作区组织会话，路径里的工作区写作 `spaces`。用这些接口在会话中发起任务、跟进和停止运行，并管理会话列表。与数字人的聊天在 [API：数字人](https://hello-halo.cc/docs/developers/api/digital-human.html) 页。

所有路径都相对于你的 Halo 地址，每个请求都要带上访问密码。示例中的 `$HALO_URL` 和 `$HALO_TOKEN` 按[快速上手](https://hello-halo.cc/docs/developers/quickstart.html)设置；地址、鉴权和错误约定见 [HTTP API 概览](https://hello-halo.cc/docs/developers/api/)。

| 操作 | 端点 |
| --- | --- |
| [查询 Halo 是否仍在某个会话中生成回复](#get-api-agent-generating-conversationid) | `GET /api/agent/generating/:conversationId` |
| [在会话中发起一轮新任务](#post-api-agent-message) | `POST /api/agent/message` |
| [列出 Halo 正在处理的会话](#get-api-agent-sessions) | `GET /api/agent/sessions` |
| [停止 Halo 在会话中正在做的事](#post-api-agent-stop) | `POST /api/agent/stop` |
| [列出会话可用的按需能力](#post-api-agent-toolsets-list) | `POST /api/agent/toolsets/list` |
| [列出工作区中的会话](#get-api-spaces-spaceid-conversations) | `GET /api/spaces/:spaceId/conversations` |
| [新建空会话](#post-api-spaces-spaceid-conversations) | `POST /api/spaces/:spaceId/conversations` |
| [读取会话及其消息](#get-api-spaces-spaceid-conversations-conversationid) | `GET /api/spaces/:spaceId/conversations/:conversationId` |
| [修改会话标题或元数据](#put-api-spaces-spaceid-conversations-conversationid) | `PUT /api/spaces/:spaceId/conversations/:conversationId` |
| [删除会话](#delete-api-spaces-spaceid-conversations-conversationid) （不可撤销） | `DELETE /api/spaces/:spaceId/conversations/:conversationId` |
| [读取一条消息背后的思考过程和工具调用](#get-api-spaces-spaceid-conversations-conversationid-messages-messageid-thoughts) | `GET /api/spaces/:spaceId/conversations/:conversationId/messages/:messageId/thoughts` |
| [星标或取消星标会话](#post-api-spaces-spaceid-conversations-conversationid-star) | `POST /api/spaces/:spaceId/conversations/:conversationId/star` |

## 查询 Halo 是否仍在某个会话中生成回复 {#get-api-agent-generating-conversationid}

`GET /api/agent/generating/:conversationId` （助手可调用）

- Pairs with [`POST /api/agent/stop`](#post-api-agent-stop) — check this before deciding whether there is anything to stop

**路径参数**

| 名称 | 说明 |
| --- | --- |
| `conversationId` | 会话 ID，来自 [`GET /api/spaces/:spaceId/conversations`](#get-api-spaces-spaceid-conversations)。 |

**响应**

```ts
{success:true,data:boolean}
```

**示例**

```bash
curl -s "$HALO_URL/api/agent/generating/<conversationId>" \
  -H "Authorization: Bearer $HALO_TOKEN"
```

## 在会话中发起一轮新任务 {#post-api-agent-message}

`POST /api/agent/message` （助手可调用）

- Starts Halo working in the conversation and returns as soon as the turn is accepted: `success: true` means accepted, not answered. The reply is written afterwards.
- Follow the reply over the WebSocket after subscribing to the conversation, or poll [`GET /api/agent/generating/:conversationId`](#get-api-agent-generating-conversationid) with a growing interval (2 s, then double) and read the conversation when it is done.
- Optional body fields: `resumeSessionId`, `thinkingEnabled` (boolean), `reasoningEffort` (`off`, `minimal`, `low`, `medium`, `high`, `xhigh` or `max`; overrides `thinkingEnabled`, but a level the user chose for this conversation wins), `knowledgeBaseId`, `images` (base64 attachments; the whole JSON body must stay under 100 KB).
- Start work in a conversation you created with [`POST /api/spaces/:spaceId/conversations`](#post-api-spaces-spaceid-conversations), so your turn never interrupts one the user is having.
- A turn can stop to ask the user a question. The user answers it in the Halo app, and the turn waits until then.

**请求体**

```json
{
  "spaceId": "<spaceId>",
  "conversationId": "<conversationId>",
  "message": "Summarize the activity log"
}
```

**响应**

```ts
{success:true}  // no data — the turn runs after the call returns
```

**示例**

```bash
curl -sX POST "$HALO_URL/api/agent/message" \
  -H "Authorization: Bearer $HALO_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"spaceId":"<spaceId>","conversationId":"<conversationId>","message":"Summarize the activity log"}'
```

## 列出 Halo 正在处理的会话 {#get-api-agent-sessions}

`GET /api/agent/sessions` （助手可调用）

**响应**

```ts
{success:true,data:string[]}  // array of conversationId, each one currently generating a reply
```

**示例**

```bash
curl -s "$HALO_URL/api/agent/sessions" \
  -H "Authorization: Bearer $HALO_TOKEN"
```

## 停止 Halo 在会话中正在做的事 {#post-api-agent-stop}

`POST /api/agent/stop` （助手可调用）

- `conversationId` is optional. Leave it out (or send `{}`) to stop everything Halo is doing.

**请求体**

```json
{
  "conversationId": "<conversationId>"
}
```

**响应**

```ts
{success:true}
```

**示例**

```bash
curl -sX POST "$HALO_URL/api/agent/stop" \
  -H "Authorization: Bearer $HALO_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"conversationId":"<conversationId>"}'
```

## 列出会话可用的按需能力 {#post-api-agent-toolsets-list}

`POST /api/agent/toolsets/list` （助手可调用）

- Read-only: lists the on-demand capabilities (toolsets in the API) a conversation can use and whether each is open. The user opens and closes them in the composer under **＋ › Capabilities**.

**请求体**

```json
{
  "spaceId": "<spaceId>",
  "conversationId": "<conversationId>"
}
```

**响应**

```ts
{success:true,data:[{id:string,displayName:string,summary:string,open:boolean}]}
```

**示例**

```bash
curl -sX POST "$HALO_URL/api/agent/toolsets/list" \
  -H "Authorization: Bearer $HALO_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"spaceId":"<spaceId>","conversationId":"<conversationId>"}'
```

## 列出工作区中的会话 {#get-api-spaces-spaceid-conversations}

`GET /api/spaces/:spaceId/conversations` （助手可调用）

**路径参数**

| 名称 | 说明 |
| --- | --- |
| `spaceId` | 工作区 ID，来自 [`GET /api/spaces`](https://hello-halo.cc/docs/developers/api/workspace.html#get-api-spaces)。Halo 工作区的 ID 固定为 `halo-temp`。 |

**响应**

```json
{
  "success": true,
  "data": [
    {
      "id": "<uuid>",
      "title": "…",
      "starred": false
    }
  ]
}
```

**示例**

```bash
curl -s "$HALO_URL/api/spaces/<spaceId>/conversations" \
  -H "Authorization: Bearer $HALO_TOKEN"
```

## 新建空会话 {#post-api-spaces-spaceid-conversations}

`POST /api/spaces/:spaceId/conversations` （助手可调用）

- Creates an empty conversation. To make Halo work in it, call [`POST /api/agent/message`](#post-api-agent-message) with its id.
- Optional body field `reasoningEffort`: `off`, `minimal`, `low`, `medium`, `high`, `xhigh` or `max` — how hard the model thinks. Leave it out to follow the model's configured effort.
- Optional body field `ephemeral` (boolean): for a view that shows the transcript itself. The conversation is left out of every list and search, and deleted at the next start of Halo unless deleted before. Leave it out for a conversation the user should see.

**路径参数**

| 名称 | 说明 |
| --- | --- |
| `spaceId` | 工作区 ID，来自 [`GET /api/spaces`](https://hello-halo.cc/docs/developers/api/workspace.html#get-api-spaces)。Halo 工作区的 ID 固定为 `halo-temp`。 |

**请求体**

```json
{
  "title": "Weekly report"
}
```

**响应**

```json
{
  "success": true,
  "data": {
    "id": "<uuid>",
    "title": "Weekly report"
  }
}
```

**示例**

```bash
curl -sX POST "$HALO_URL/api/spaces/<spaceId>/conversations" \
  -H "Authorization: Bearer $HALO_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"title":"Weekly report"}'
```

## 读取会话及其消息 {#get-api-spaces-spaceid-conversations-conversationid}

`GET /api/spaces/:spaceId/conversations/:conversationId` （助手可调用）

- Long conversations return a lot of text. To read only what is new, pass `?from=&lt;messageId&gt;`: messages start at that message (inclusive) and the response carries `messagesFrom`. An unknown id returns the whole conversation.
- Each message has its own `id`; it is the `messageId` that [`GET /api/spaces/:spaceId/conversations/:conversationId/messages/:messageId/thoughts`](#get-api-spaces-spaceid-conversations-conversationid-messages-messageid-thoughts) takes.

**路径参数**

| 名称 | 说明 |
| --- | --- |
| `spaceId` | 工作区 ID，来自 [`GET /api/spaces`](https://hello-halo.cc/docs/developers/api/workspace.html#get-api-spaces)。Halo 工作区的 ID 固定为 `halo-temp`。 |
| `conversationId` | 会话 ID，来自 [`GET /api/spaces/:spaceId/conversations`](#get-api-spaces-spaceid-conversations)。 |

**查询参数**：`from`

**响应**

```json
{
  "success": true,
  "data": {
    "id": "<uuid>",
    "messages": [
      {
        "id": "<uuid>",
        "role": "user",
        "content": "…"
      }
    ]
  }
}
```

**示例**

```bash
curl -s "$HALO_URL/api/spaces/<spaceId>/conversations/<conversationId>" \
  -H "Authorization: Bearer $HALO_TOKEN"
```

## 修改会话标题或元数据 {#put-api-spaces-spaceid-conversations-conversationid}

`PUT /api/spaces/:spaceId/conversations/:conversationId` （可撤销） （助手可调用）

- modelSourceId + modelId (always both; sourceId is a uuid from [`GET /api/config`](https://hello-halo.cc/docs/developers/api/settings.html#get-api-config)) pin the account and model the conversation runs on. A pin naming an account that no longer exists is not rejected: the conversation runs on the current global account until it is pinned again.

**路径参数**

| 名称 | 说明 |
| --- | --- |
| `spaceId` | 工作区 ID，来自 [`GET /api/spaces`](https://hello-halo.cc/docs/developers/api/workspace.html#get-api-spaces)。Halo 工作区的 ID 固定为 `halo-temp`。 |
| `conversationId` | 会话 ID，来自 [`GET /api/spaces/:spaceId/conversations`](#get-api-spaces-spaceid-conversations)。 |

**请求体**

```json
{
  "title": "Renamed conversation"
}
```

**响应**

```ts
{"success":true,"data":{...updated conversation}}
```

**示例**

```bash
curl -sX PUT "$HALO_URL/api/spaces/<spaceId>/conversations/<conversationId>" \
  -H "Authorization: Bearer $HALO_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"title":"Renamed conversation"}'
```

## 删除会话 {#delete-api-spaces-spaceid-conversations-conversationid}

`DELETE /api/spaces/:spaceId/conversations/:conversationId` （不可撤销） （助手可调用）

::: danger 不可撤销
执行后无法撤销，数据也不会进入回收站。调用前请确认这是用户想要的结果。
:::

- Removes the conversation file and its reasoning history from disk. There is no backup.

**路径参数**

| 名称 | 说明 |
| --- | --- |
| `spaceId` | 工作区 ID，来自 [`GET /api/spaces`](https://hello-halo.cc/docs/developers/api/workspace.html#get-api-spaces)。Halo 工作区的 ID 固定为 `halo-temp`。 |
| `conversationId` | 会话 ID，来自 [`GET /api/spaces/:spaceId/conversations`](#get-api-spaces-spaceid-conversations)。 |

**响应**

```json
{
  "success": true
}
```

**示例**

```bash
curl -sX DELETE "$HALO_URL/api/spaces/<spaceId>/conversations/<conversationId>" \
  -H "Authorization: Bearer $HALO_TOKEN"
```

## 读取一条消息背后的思考过程和工具调用 {#get-api-spaces-spaceid-conversations-conversationid-messages-messageid-thoughts}

`GET /api/spaces/:spaceId/conversations/:conversationId/messages/:messageId/thoughts` （助手可调用）

- Wrong ids return an empty array, not a 404 — an empty result does not prove the message had no thoughts.
- toolInput and toolOutput are the raw arguments and results of that turn, so this gets long fast. Read it to diagnose what Halo actually did, not as a way to read a conversation.

**路径参数**

| 名称 | 说明 |
| --- | --- |
| `spaceId` | 工作区 ID，来自 [`GET /api/spaces`](https://hello-halo.cc/docs/developers/api/workspace.html#get-api-spaces)。Halo 工作区的 ID 固定为 `halo-temp`。 |
| `conversationId` | 会话 ID，来自 [`GET /api/spaces/:spaceId/conversations`](#get-api-spaces-spaceid-conversations)。 |
| `messageId` | 消息 ID，来自 [`GET /api/spaces/:spaceId/conversations/:conversationId`](#get-api-spaces-spaceid-conversations-conversationid) 返回的消息列表。 |

**响应**

```json
{
  "success": true,
  "data": [
    {
      "id": "…",
      "type": "…",
      "content": "…",
      "timestamp": "…",
      "toolName": "…",
      "toolInput": {},
      "toolOutput": "…"
    }
  ]
}
```

**示例**

```bash
curl -s "$HALO_URL/api/spaces/<spaceId>/conversations/<conversationId>/messages/<messageId>/thoughts" \
  -H "Authorization: Bearer $HALO_TOKEN"
```

## 星标或取消星标会话 {#post-api-spaces-spaceid-conversations-conversationid-star}

`POST /api/spaces/:spaceId/conversations/:conversationId/star` （可撤销） （助手可调用）

**路径参数**

| 名称 | 说明 |
| --- | --- |
| `spaceId` | 工作区 ID，来自 [`GET /api/spaces`](https://hello-halo.cc/docs/developers/api/workspace.html#get-api-spaces)。Halo 工作区的 ID 固定为 `halo-temp`。 |
| `conversationId` | 会话 ID，来自 [`GET /api/spaces/:spaceId/conversations`](#get-api-spaces-spaceid-conversations)。 |

**请求体**

```json
{
  "starred": true
}
```

**响应**

```json
{
  "success": true
}
```

**示例**

```bash
curl -sX POST "$HALO_URL/api/spaces/<spaceId>/conversations/<conversationId>/star" \
  -H "Authorization: Bearer $HALO_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"starred":true}'
```