> ## 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：创建、配置与控制专家

> 使用 Octop 的 /api/agents 端点创建、配置、启动、停止和重新加载 AI 专家，包含专家模板和 MBTI 人格端点。

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

## 路由

```text theme={null}
/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 theme={null}
curl http://127.0.0.1:8088/api/agents \
  -H 'Authorization: Bearer <token>'
```

## 创建专家

```bash theme={null}
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` *required*

专家的人类可读名称。

**persona\_mbti** `string`

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

**default\_model** `string`

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

**system\_prompt** `string`

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

**description** `string`

专家用途的简短描述。

**template\_name** `string`

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

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

## 启动与停止

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

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

## 重新加载专家

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

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

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

## 从专家模板创建

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

```bash theme={null}
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` | 把工作区技能复制到你可修改的技能包 |

## MBTI 人格代码

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

列出所有可用代码：

```bash theme={null}
curl http://127.0.0.1:8088/api/mbti/codes \
  -H 'Authorization: Bearer <token>'
```

获取单个代码的详情：

```bash theme={null}
curl http://127.0.0.1:8088/api/mbti/codes/ENFP \
  -H 'Authorization: Bearer <token>'
```

将人格应用到现有专家并重新加载：

```bash theme={null}
curl -X PUT http://127.0.0.1:8088/api/agents/1/mbti \
  -H 'Authorization: Bearer <token>' \
  -H 'Content-Type: application/json' \
  -d '{"code": "ENFP"}'
```


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