API 参考 · Builder

先跑通再查表：快速开始。本页 = 字段与接口参考（对齐 Dify「按能力查阅」）。

Agent Spec（机读要点）

字段	必填	说明
agent_name	✅	展示名；同用户下同名 practice Agent 幂等更新
system_prompt	✅	人设
description		简介
model		默认 deepseek-chat
recipe_id		如 edu_qa_thin；与 workflow 二选一
workflow		{ nodes, edges }；优先于 recipe
bind_entrypoint		默认 true
publish_agent		默认 true
agent_id		指定则更新该 Agent（禁 production）

服务端强制：visibility=practice，is_public=false。

---

Workflow JSON

{
  "nodes": [
    { "id": "start_1", "type": "start", "config": {}, "position": { "x": 0, "y": 0 } },
    {
      "id": "llm_1",
      "type": "llm",
      "config": {
        "systemPrompt": "...",
        "userPrompt": "{{start_1.user_message}}"
      },
      "position": { "x": 200, "y": 0 }
    },
    { "id": "end_1", "type": "end", "config": {}, "position": { "x": 400, "y": 0 } }
  ],
  "edges": [
    { "source": "start_1", "target": "llm_1" },
    { "source": "llm_1", "target": "end_1" }
  ]
}

常见 type：start / llm / http / condition / code / memory_load / memory_save / end。

内置 Recipe：edu_qa_thin = start → llm → end。

---

Entrypoint

{ "entrypoint": { "workflow_id": "<uuid>" } }

写入 Agent config_json；有图即默认进链。

---

接口

GET /api/builder/recipes

鉴权：flow:create_sandbox 或管理员。
响应示例：["edu_qa_thin", "http_call_thin", ...]

GET /api/builder/node-types

节点契约摘要（type / 必填 config / notes）。详见 节点参考。

POST /api/builder/validate

POST /api/builder/validate
Authorization: Bearer <token>
Content-Type: application/json

{ "workflow": { "nodes": [...], "edges": [...] } }

成功：data.valid=true + node_count / edge_count / node_types。
非法：HTTP 400 · BUILDER_WORKFLOW_INVALID。
provision 灌图前会再次校验，非法图不会落库发布。

Knowledge / Plugin / Attach（G3）

方法	路径	说明
POST	/api/builder/knowledge	创建知识库
POST	/api/builder/knowledge/{kb_id}/documents/text	纯文本入库
POST	/api/builder/plugins/http	注册学员自有 HTTP 插件
POST	/api/builder/attach	挂载 KB / Plugin 到练习 Agent

POST /api/builder/provision

POST /api/builder/provision
Authorization: Bearer <token>
Content-Type: application/json

{
  "agent_name": "高中数学答疑助教",
  "system_prompt": "你是高中数学助教…",
  "recipe_id": "edu_qa_thin",
  "industry": "education"
}

成功 data 要点：

字段	说明
agent_id	练习 Agent
workflow_id	若有图
entrypoint	{ workflow_id }
visibility	恒为 practice
reused	同名更新时为 true

测服示例前缀：https://chenyueinnokeji.com/test-api（本地开发多为 http://127.0.0.1:8000）。

---

禁止

• 学员文档引导自行跑平台 seed / 初始化脚本
• 经 Builder 改 visibility=production 的官网 Agent