• 简体中文

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

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

      路由

      /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}从专家模板创建专家

      列出专家

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

      创建专家

      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": "处理客户支持请求的专家"
  }'

      请求字段

      namestringbody必填

      专家的人类可读名称。

      persona_mbtistringbody

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

      default_modelstringbody

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

      system_promptstringbody

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

      descriptionstringbody

      专家用途的简短描述。

      template_namestringbody

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

      注意

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

      启动与停止

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

      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 端点检查实际运行状态：

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

      重新加载专家

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

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

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

      从专家模板创建

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

      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 人格代码来旋定专家的沟通风格。

      列出所有可用代码：

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

      获取单个代码的详情：

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

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

      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"}'