> For AI agents: the complete documentation index is available at /llms.txt, the full documentation bundle is available at /llms-full.txt.

# Octop 专家 API：创建、配置与控制专家

使用专家 API 创建、配置、启动、停止并重新加载 Octop 专家。每个专家都拥有自己的持久化状态、模型配置和人格。

## 路由

```text
/api/agents
```

## 端点

| 方法     | 路径                                | 描述            |
| ------ | --------------------------------- | ------------- |
| GET    | `/agents`                         | 列出所有专家        |
| POST   | `/agents`                         | 创建新专家         |
| GET    | `/agents/{id}`                    | 获取单个专家详情      |
| PATCH  | `/agents/{id}`                    | 更新专家配置        |
| DELETE | `/agents/{id}`                    | 删除专家并永久清理其工作区 |
| POST   | `/agents/{id}/start`              | 启动专家运行时       |
| POST   | `/agents/{id}/stop`               | 停止专家运行时       |
| POST   | `/agents/{id}/reload`             | 重新加载专家配置      |
| POST   | `/agents/{id}/read`               | 将频道标记为已读      |
| GET    | `/agents/{id}/status`             | 获取运行时状态       |
| POST   | `/agents/from-expert/{expert_id}` | 从专家模板创建专家     |

## 列出专家

```bash
curl http://127.0.0.1:8088/api/agents \
  -H 'Authorization: Bearer <token>'
```

## 创建专家

```bash
curl -X POST http://127.0.0.1:8088/api/agents \
  -H 'Authorization: Bearer <token>' \
  -H 'Content-Type: application/json' \
  -d '{
    "name": "客服助手",
    "persona_mbti": "ENFJ",
    "default_model": "gpt-4o",
    "description": "处理客户支持请求的专家"
  }'
```

### 请求字段


- `name` (string, body, 必填)

专家的人类可读名称。


- `persona_mbti` (string, body)

旋定专家行为风格的 MBTI 人格代码（例如 `"ENFP"`）。


- `default_model` (string, body)

默认用于此专家对话的模型名称。


- `system_prompt` (string, body)

自定义系统提示词，覆盖默认行为。


- `description` (string, body)

专家用途的简短描述。


- `template_name` (string, body)

创建专家时应用的可选模板名称。


> **注意**
> 
> `DELETE /agents/{id}` 还会永久删除 `~/.octop/agents/<id>/`。工作区清理失败不会阻断数据库删除。如需保留文件请先备份。
> 


## 启动与停止

启动或停止专家的运行时：

```bash
curl -X POST http://127.0.0.1:8088/api/agents/1/start \
  -H 'Authorization: Bearer <token>'

curl -X POST http://127.0.0.1:8088/api/agents/1/stop \
  -H 'Authorization: Bearer <token>'
```

成功时两个端点都返回 `204 No Content`。通过 `/status` 端点检查实际运行状态：

```bash
curl http://127.0.0.1:8088/api/agents/1/status \
  -H 'Authorization: Bearer <token>'
# {"state": "running", "last_error": null, ...}
```

## 重新加载专家

在修改配置后重建专家运行时，而无需完全重启：

```bash
curl -X POST http://127.0.0.1:8088/api/agents/1/reload \
  -H 'Authorization: Bearer <token>'
```


> **说明**
> 
> 若该专家当前有正在进行的操作（例如正在处理对话轮次），重新加载请求将返回 `409 AGENT_BUSY`。请在重试前等待当前操作完成。
> 


## 从专家模板创建

Octop 提供预制的专家模板，可以快速引导创建新专家：

```bash
curl -X POST http://127.0.0.1:8088/api/agents/from-expert/finance-advisor \
  -H 'Authorization: Bearer <token>' \
  -H 'Content-Type: application/json' \
  -d '{"name": "我的理财助手"}'
```

通过 `GET /api/experts` 获取可用专家模板目录。

## 共享专家

创建或更新专家时把 `is_shared` 设为 `true`，本实例其他人就可以打开它。只有所有者能改设置。`GET /agents` 会返回你自己的专家以及别人共享给你的专家。管理员可以传 `scope=all` 列出全部专家。

## 发布为专家模板

`POST /agents/{id}/publish-expert` 把该专家的工作区复制成模板，其他人可以在专家市场安装。不会带上收件箱上传和密钥。用 `GET /api/experts/published` 与 `POST /api/experts/published/{expert_id}/install` 列出和安装。

## 按专家的工具开关

`GET` / `PUT` `/agents/{id}/tool-settings` 打开或关闭该专家的内置工具和插件工具，对应**个性化**。插件开关立即生效。部分内置工具不能关闭（`ls`、`read_file`、`glob`、`grep`、`write_todos`、`task`）。

复制技能会生成快照，源和目标之后不会保持同步：

| 方法     | 路径                                              | 作用                                           |
| ------ | ----------------------------------------------- | -------------------------------------------- |
| `POST` | `/agents/{id}/skill-packages/{package_id}/copy` | 把选定技能包技能复制到工作区（`skill_slugs`，可选 `overwrite`） |
| `POST` | `/agents/{id}/skills/{slug}/push-to-package`    | 把工作区技能复制到你可修改的技能包                            |

`POST /skill-packages` 和 `PUT /skill-packages/{id}` 接受 `shared`。设为 `true` 后，其他登录用户可以查看并挂载，只有创建者能编辑或删除。`visibility` 和 `group_ids` 可以再收窄范围。

## MBTI 人格代码

Octop 使用 MBTI 人格代码来旋定专家的沟通风格。

列出所有可用代码：

```bash
curl http://127.0.0.1:8088/api/mbti/types \
  -H 'Authorization: Bearer <token>'
```

获取单个代码的详情：

```bash
curl http://127.0.0.1:8088/api/mbti/types/ENFP \
  -H 'Authorization: Bearer <token>'
```

将人格应用到现有专家并重新加载。专家 ID 放在 `X-Octop-Agent-Id` 头里：

```bash
curl -X POST http://127.0.0.1:8088/api/mbti/apply \
  -H 'Authorization: Bearer <token>' \
  -H 'X-Octop-Agent-Id: 1' \
  -H 'Content-Type: application/json' \
  -d '{"code": "ENFP"}'
```
