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

# 会话

> /v1/sessions — 创建长期会话、追加事件、回放历史、中断运行

会话（Session）是一段可以反复追加事件的对话。相比 `POST /v1/agents/run` 每次自己带 `session_id`，会话接口让你显式地创建、查询、回放和中断它。

<Note>
  创建会话不会开沙盒，也不产生任何费用。沙盒在第一次发事件时才开，计费也按事件发生，不按会话存在。
</Note>

## 创建会话

```
POST https://api.profy.cn/v1/sessions
```

<ParamField body="agent" type="string" required>
  专家（Agent）标识符。
</ParamField>

<ParamField body="title" type="string">
  会话标题，不传则为 "New Chat"。
</ParamField>

<ParamField body="environment_id" type="string">
  [运行环境](/zh/developers/api/environments) ID。每次运行时实时解析——你改了环境，下一个事件就生效。
</ParamField>

```bash curl theme={null}
curl -X POST https://api.profy.cn/v1/sessions \
  -H "Authorization: Bearer sk-pro-your-key" \
  -H "Content-Type: application/json" \
  -d '{"agent": "my-expert", "environment_id": "env_abc"}'
```

```json theme={null}
{
  "code": 0,
  "message": "ok",
  "data": { "id": "ses_abc123", "agent": "my-expert", "environment_id": "env_abc", "status": "idle" }
}
```

## 发送事件（SSE）

```
POST https://api.profy.cn/v1/sessions/{session_id}/events
```

<ParamField body="type" type="string" default="user.message">
  目前只支持 `user.message`，其它值会返回 400。
</ParamField>

<ParamField body="content" type="string" required>
  消息内容。
</ParamField>

<ParamField body="model" type="string">
  指定模型，不传用平台默认。
</ParamField>

<ParamField body="attachment_file_ids" type="string[]">
  附件文件 ID，最多 20 个，由[上传文件](/zh/developers/api/files)接口返回。
</ParamField>

响应是 SSE 流，事件类型与[调用专家](/zh/developers/api/agents-run)完全一致——两个接口走的是同一套执行逻辑。

```bash curl theme={null}
curl -N -X POST https://api.profy.cn/v1/sessions/ses_abc123/events \
  -H "Authorization: Bearer sk-pro-your-key" \
  -H "Content-Type: application/json" \
  -H "Accept: text/event-stream" \
  -d '{"content": "帮我看看这份报关单"}'
```

## 回放历史

```
GET https://api.profy.cn/v1/sessions/{session_id}/events?after={event_id}&limit=100
```

返回已落库的用户与助手消息：

```json theme={null}
{
  "code": 0,
  "data": {
    "events": [
      { "id": "msg_1", "type": "user.message", "role": "user", "content": "你好", "metadata": {}, "created_at": "..." },
      { "id": "msg_2", "type": "assistant.message", "role": "assistant", "content": "你好，我是…", "metadata": {}, "created_at": "..." }
    ]
  }
}
```

`after` 传一个不存在的 ID 时会从头回放，而不是返回空——空结果和"已追上"无法区分。`limit` 最大 200。

## 中断运行

```
POST https://api.profy.cn/v1/sessions/{session_id}/interrupt
```

请求运行时停止当前生成。这个接口是幂等的：会话上没有正在跑的任务时也返回成功，因为"停止"这个意图已经满足了。

## 其它操作

| 方法       | 路径                           | 说明                            |
| -------- | ---------------------------- | ----------------------------- |
| `GET`    | `/v1/sessions?agent=&limit=` | 列出你的会话，最多 100 条               |
| `GET`    | `/v1/sessions/{id}`          | 会话详情，含绑定的 agent 与 environment |
| `DELETE` | `/v1/sessions/{id}`          | 删除会话及其消息                      |

## 错误码

| HTTP 状态码 | 说明                                   |
| -------- | ------------------------------------ |
| `400`    | 缺少 `agent` / `content`，或 `type` 不受支持 |
| `401`    | 认证失败                                 |
| `404`    | 会话不存在、不属于你，或 `environment_id` 无效     |

## 下一步

<CardGroup cols={2}>
  <Card title="运行环境" icon="box" href="/zh/developers/api/environments">
    定义沙盒运行时与依赖
  </Card>

  <Card title="管理专家" icon="robot" href="/zh/developers/api/agents">
    用 API 创建和发布专家
  </Card>
</CardGroup>