list_agents

列出本租户的全部 Agent（名称 + 是否已发布）。

Parameters

No parameters.

Raw schema

{
  "type": "object",
  "properties": {},
  "title": "list_agentsArguments"
}

get_agent

取某个 Agent 的完整配置（soul/task/tools/skills/knowledge_bases/模型/参数等）。

Parameters1

name

string

required

Raw schema

{
  "type": "object",
  "properties": {
    "name": {
      "title": "Name",
      "type": "string"
    }
  },
  "required": [
    "name"
  ],
  "title": "get_agentArguments"
}

create_agent

新建 Agent。 soul = 人格/身份；task = 职责与边界；tools = 工具名白名单（先用 list_tools 看有哪些；系统工具时间/定位/天气会**默认自动启用**，不用手动列）；knowledge_bases = 挂载的知识库名（挂上后每轮自动检索注入）。 alias = **公开人类可读短名**，强烈**建议必填**：它就是这个 Agent 的好记网址那一段（`{public_base}/t/<租户>/<alias>`），方便直接发给人访问。用 URL-safe 的小写短横线名（如 `booking`、`suchka-venue`）；这里会自动帮你规范化。撞名/不合法会在 alias_result 里报错。

Parameters9

name	string	required
soul	string	optional
task	string	optional
tools	any	optional
skills	any	optional
knowledge_bases	any	optional
model	any	optional
published	boolean	optional
alias	string	optional

Raw schema

{
  "type": "object",
  "properties": {
    "name": {
      "title": "Name",
      "type": "string"
    },
    "soul": {
      "default": "",
      "title": "Soul",
      "type": "string"
    },
    "task": {
      "default": "",
      "title": "Task",
      "type": "string"
    },
    "tools": {
      "anyOf": [
        {
          "items": {
            "type": "string"
          },
          "type": "array"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Tools"
    },
    "skills": {
      "anyOf": [
        {
          "items": {
            "type": "string"
          },
          "type": "array"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Skills"
    },
    "knowledge_bases": {
      "anyOf": [
        {
          "items": {
            "type": "string"
          },
          "type": "array"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Knowledge Bases"
    },
    "model": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Model"
    },
    "published": {
      "default": false,
      "title": "Published",
      "type": "boolean"
    },
    "alias": {
      "default": "",
      "title": "Alias",
      "type": "string"
    }
  },
  "required": [
    "name"
  ],
  "title": "create_agentArguments"
}

update_agent

改 Agent 的**部分**字段——没传的字段保持原样。以前这里要先 GET、再合并、再 PUT，因为底层只有全量替换的 `PUT`。现在 `PATCH /agents/{name}` 就是这个语义，所以合并回到了它该在的地方——服务端，一处，所有调用方共用。

Parameters13

name	string	required
soul	any	optional
task	any	optional
tools	any	optional
skills	any	optional
knowledge_bases	any	optional
model	any	optional
published	any	optional
greeting	any	optional
auto_greeting	any	optional
ask_forms	any	optional
reasoning	any	optional
grounding_required	any	optional

Raw schema

{
  "type": "object",
  "properties": {
    "name": {
      "title": "Name",
      "type": "string"
    },
    "soul": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Soul"
    },
    "task": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Task"
    },
    "tools": {
      "anyOf": [
        {
          "items": {
            "type": "string"
          },
          "type": "array"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Tools"
    },
    "skills": {
      "anyOf": [
        {
          "items": {
            "type": "string"
          },
          "type": "array"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Skills"
    },
    "knowledge_bases": {
      "anyOf": [
        {
          "items": {
            "type": "string"
          },
          "type": "array"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Knowledge Bases"
    },
    "model": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Model"
    },
    "published": {
      "anyOf": [
        {
          "type": "boolean"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Published"
    },
    "greeting": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Greeting"
    },
    "auto_greeting": {
      "anyOf": [
        {
          "type": "boolean"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Auto Greeting"
    },
    "ask_forms": {
      "anyOf": [
        {
          "type": "boolean"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Ask Forms"
    },
    "reasoning": {
      "anyOf": [
        {
          "type": "boolean"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Reasoning"
    },
    "grounding_required": {
      "anyOf": [
        {
          "type": "boolean"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Grounding Required"
    }
  },
  "required": [
    "name"
  ],
  "title": "update_agentArguments"
}

list_tools

列出可分配给 Agent 的工具名 + 各自说明（含租户已接入的工具库/MCP 工具）。

Parameters

No parameters.

Raw schema

{
  "type": "object",
  "properties": {},
  "title": "list_toolsArguments"
}

list_mcp_servers

列出本租户工具库里已接入的 MCP server（只读；不含密钥字段）。

Parameters

No parameters.

Raw schema

{
  "type": "object",
  "properties": {},
  "title": "list_mcp_serversArguments"
}

create_share

给某个 Agent 生成一个**分享/集成入口**——终端用户由此真正访问它。 **`published=True` 只是「可见」，不等于「可达」**：要让终端用户用到这个 Agent，必须建一个 share。返回里带可直接打开的聊天链接（`{public_base}/s/<token>`）和网站嵌入地址（`{public_base}/embed/<token>`）。网站挂件贴一行到 </body> 前：`<script src="{public_base}/embed.js" data-token="<token>"></script>`。 label 给这个入口起个名（如「网站挂件」「客服链接」）。Telegram/WhatsApp 等渠道另在控制台该 Agent 的 Integration 页接入。 **没有网站？** 直接把返回的 `chat_url` 或 `qr_url`（二维码）发给租户：印在名片/传单/店内，客户扫码即打开整页聊天页，免登录、按浏览器自动记住回头客。

Parameters2

agent_name	string	required
label	string	optional

Raw schema

{
  "type": "object",
  "properties": {
    "agent_name": {
      "title": "Agent Name",
      "type": "string"
    },
    "label": {
      "default": "",
      "title": "Label",
      "type": "string"
    }
  },
  "required": [
    "agent_name"
  ],
  "title": "create_shareArguments"
}

list_shares

列出某 Agent 的分享入口（token / label / 是否停用 / 聊天链接 / 嵌入地址）。

Parameters1

agent_name

string

required

Raw schema

{
  "type": "object",
  "properties": {
    "agent_name": {
      "title": "Agent Name",
      "type": "string"
    }
  },
  "required": [
    "agent_name"
  ],
  "title": "list_sharesArguments"
}

list_skills

列出本租户的技能。

Parameters

No parameters.

Raw schema

{
  "type": "object",
  "properties": {},
  "title": "list_skillsArguments"
}

get_skill

取某个技能的完整内容（含 instructions 全文）。

Parameters1

name

string

required

Raw schema

{
  "type": "object",
  "properties": {
    "name": {
      "title": "Name",
      "type": "string"
    }
  },
  "required": [
    "name"
  ],
  "title": "get_skillArguments"
}

create_skill

新建技能。description = "何时用"（进系统提示，要短）；instructions = 详细指南（按需拉取）。

Parameters4

name	string	required
description	string	optional
instructions	string	optional
tools	any	optional

Raw schema

{
  "type": "object",
  "properties": {
    "name": {
      "title": "Name",
      "type": "string"
    },
    "description": {
      "default": "",
      "title": "Description",
      "type": "string"
    },
    "instructions": {
      "default": "",
      "title": "Instructions",
      "type": "string"
    },
    "tools": {
      "anyOf": [
        {
          "items": {
            "type": "string"
          },
          "type": "array"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Tools"
    }
  },
  "required": [
    "name"
  ],
  "title": "create_skillArguments"
}

update_skill

改技能的部分字段——同 update_agent，先 GET 再合并，避免全量替换抹掉没传的字段。

Parameters4

name	string	required
description	any	optional
instructions	any	optional
tools	any	optional

Raw schema

{
  "type": "object",
  "properties": {
    "name": {
      "title": "Name",
      "type": "string"
    },
    "description": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Description"
    },
    "instructions": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Instructions"
    },
    "tools": {
      "anyOf": [
        {
          "items": {
            "type": "string"
          },
          "type": "array"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Tools"
    }
  },
  "required": [
    "name"
  ],
  "title": "update_skillArguments"
}

list_knowledge_bases

列出本租户的知识库（含文档数/切片数/相关性下限）。

Parameters

No parameters.

Raw schema

{
  "type": "object",
  "properties": {},
  "title": "list_knowledge_basesArguments"
}

get_knowledge_base

取某个知识库的配置（含给模型看的 instructions 全文）。

Parameters1

name

string

required

Raw schema

{
  "type": "object",
  "properties": {
    "name": {
      "title": "Name",
      "type": "string"
    }
  },
  "required": [
    "name"
  ],
  "title": "get_knowledge_baseArguments"
}

create_knowledge_base

Create a knowledge base. **Write `instructions` at creation time — do not leave it blank.** It is injected next to this KB's excerpts whenever they are retrieved. It does NOT affect recall (recall is vector search + max_distance); it governs how the model USES what was retrieved. Derive it from the expected usage, one line each: - Scope: what it covers / does not, and what to do when out of scope ("Covers residential mortgages only; for car or personal loans, say so and hand off"). - Authority: where it ranks ("Current company policy; overrides industry norms"). - Usage rules specific to this content ("Any quoted rate must state its effective date"). The generic "answer from the excerpts; say when not covered" is built into the platform — never repeat it here. Blank is acceptable only for generic reference material with no special rules. Worked examples: search_agent4_docs("knowledge base instructions examples"). max_distance is the relevance cutoff (blank = global default 0.6); tighten for regulatory content, and calibrate against real queries rather than guessing.

Parameters4

name	string	required
instructions	string	optional
description	string	optional
max_distance	any	optional

Raw schema

{
  "type": "object",
  "properties": {
    "name": {
      "title": "Name",
      "type": "string"
    },
    "instructions": {
      "default": "",
      "title": "Instructions",
      "type": "string"
    },
    "description": {
      "default": "",
      "title": "Description",
      "type": "string"
    },
    "max_distance": {
      "anyOf": [
        {
          "type": "number"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Max Distance"
    }
  },
  "required": [
    "name"
  ],
  "title": "create_knowledge_baseArguments"
}

update_knowledge_base

改知识库的部分字段（先 GET 再合并，同 update_agent）。

Parameters4

name	string	required
instructions	any	optional
description	any	optional
max_distance	any	optional

Raw schema

{
  "type": "object",
  "properties": {
    "name": {
      "title": "Name",
      "type": "string"
    },
    "instructions": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Instructions"
    },
    "description": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Description"
    },
    "max_distance": {
      "anyOf": [
        {
          "type": "number"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Max Distance"
    }
  },
  "required": [
    "name"
  ],
  "title": "update_knowledge_baseArguments"
}

add_knowledge_text

往知识库里加一篇**文本**文档（同步完成切片+嵌入，返回真实切片数）。要传**本地文件**（pdf/docx…）用 `add_knowledge_file`。

Parameters3

kb_name	string	required
title	string	required
content	string	required

Raw schema

{
  "type": "object",
  "properties": {
    "kb_name": {
      "title": "Kb Name",
      "type": "string"
    },
    "title": {
      "title": "Title",
      "type": "string"
    },
    "content": {
      "title": "Content",
      "type": "string"
    }
  },
  "required": [
    "kb_name",
    "title",
    "content"
  ],
  "title": "add_knowledge_textArguments"
}

add_knowledge_file

把一个本地文件的内容加进知识库（txt/md/html/pdf/docx）。 **本 MCP 跑在平台服务器上，读不到你本机的路径。** 文本类请自己读出内容再调 `add_knowledge_text`；二进制（pdf/docx）走控制台上传，或用 curl 打 `/knowledge-bases/{name}/documents/upload`。 **整个文件夹要灌库时，压成 zip 传那一个端点即可**——子目录会被遍历， md/txt/pdf/html/docx 逐份入库，文档名用压缩包内的相对路径（`2025/rates.pdf` 与 `2026/rates.pdf` 因此不会混作一份）。zip 里的图片、`.DS_Store` 等自动忽略；若包内有加密、损坏或异常高压缩比的文件，**整包会被拒绝**并指明是哪一份。

Parameters3

kb_name	string	required
path	string	required
title	any	optional

Raw schema

{
  "type": "object",
  "properties": {
    "kb_name": {
      "title": "Kb Name",
      "type": "string"
    },
    "path": {
      "title": "Path",
      "type": "string"
    },
    "title": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Title"
    }
  },
  "required": [
    "kb_name",
    "path"
  ],
  "title": "add_knowledge_fileArguments"
}

search_knowledge_base

按该知识库检索，返回命中的片段与距离。走的是**与真实对话完全相同**的检索路径——用它验证阈值和切片是否合理：返回空表示这个问题会被判为"未覆盖"，Agent 届时会回答"知识库里没有"。

Parameters2

kb_name	string	required
query	string	required

Raw schema

{
  "type": "object",
  "properties": {
    "kb_name": {
      "title": "Kb Name",
      "type": "string"
    },
    "query": {
      "title": "Query",
      "type": "string"
    }
  },
  "required": [
    "kb_name",
    "query"
  ],
  "title": "search_knowledge_baseArguments"
}

improve_prompt

Parameters4

field	string	required
current	string	optional
hint	string	optional
context	any	optional

Raw schema

{
  "type": "object",
  "properties": {
    "field": {
      "title": "Field",
      "type": "string"
    },
    "current": {
      "default": "",
      "title": "Current",
      "type": "string"
    },
    "hint": {
      "default": "",
      "title": "Hint",
      "type": "string"
    },
    "context": {
      "anyOf": [
        {
          "additionalProperties": true,
          "type": "object"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Context"
    }
  },
  "required": [
    "field"
  ],
  "title": "improve_promptArguments"
}

diagnose_prompt

先读一遍某字段,返回一串**具体**的改进建议(字符串数组)。 field 同 improve_prompt。current = 要诊断的当前文字(必填,空文本无从诊断)。典型用法:先 diagnose_prompt 拿到建议列表,挑出想采纳的,再把它们并进 improve_prompt 的 hint。

Parameters3

field	string	required
current	string	required
context	any	optional

Raw schema

{
  "type": "object",
  "properties": {
    "field": {
      "title": "Field",
      "type": "string"
    },
    "current": {
      "title": "Current",
      "type": "string"
    },
    "context": {
      "anyOf": [
        {
          "additionalProperties": true,
          "type": "object"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Context"
    }
  },
  "required": [
    "field",
    "current"
  ],
  "title": "diagnose_promptArguments"
}

usage_stats

Parameters1

group

string

optional

Raw schema

{
  "type": "object",
  "properties": {
    "group": {
      "default": "total",
      "title": "Group",
      "type": "string"
    }
  },
  "title": "usage_statsArguments"
}

tenant_info

本租户的基本信息与配额。

Parameters

No parameters.

Raw schema

{
  "type": "object",
  "properties": {},
  "title": "tenant_infoArguments"
}

search_agent4_docs

Search agent4.io's own product docs — concepts (what a thing *is*) and cookbook recipes (which tool to *call*). Use when you're unsure how an agent4.io feature works, what a term means, or how to build something on the platform. Returns top passages with title, layer ("concept"|"ops"), url and a snippet. Public content; no tenant data involved.

Parameters2

query	string	required
k	integer	optional

Raw schema

{
  "type": "object",
  "properties": {
    "query": {
      "title": "Query",
      "type": "string"
    },
    "k": {
      "default": 5,
      "title": "K",
      "type": "integer"
    }
  },
  "required": [
    "query"
  ],
  "title": "search_agent4_docsArguments"
}

list_end_users

列出本租户的**终端用户**（跟你的 Agent 聊天的那些人）——只回名录，不含任何对话正文。每个用户带：显示名、登录方式（email / oauth:* / proxy）、邮箱（如有）、空间/会话/文档数、最近 24h token 用量，以及 `console_url`（点进去看详情）。 q 按名字或外部 id 过滤；sort ∈ recent（默认）| tokens24h（按 24h 用量降序）。翻页：把返回的 next_cursor 传回 cursor。典型：list_end_users(sort="tokens24h") 找最活跃/最耗量的用户。

Parameters4

q	string	optional
sort	string	optional
limit	integer	optional
cursor	string	optional

Raw schema

{
  "type": "object",
  "properties": {
    "q": {
      "default": "",
      "title": "Q",
      "type": "string"
    },
    "sort": {
      "default": "recent",
      "title": "Sort",
      "type": "string"
    },
    "limit": {
      "default": 50,
      "title": "Limit",
      "type": "integer"
    },
    "cursor": {
      "default": "",
      "title": "Cursor",
      "type": "string"
    }
  },
  "title": "list_end_usersArguments"
}

get_end_user

取某个终端用户的详情：基础画像（名字、联系邮箱/电话、城市、时区）+ 其空间列表。不含任何对话正文。带 `console_url` 指向该用户的详情页。

Parameters1

uid

string

required

Raw schema

{
  "type": "object",
  "properties": {
    "uid": {
      "title": "Uid",
      "type": "string"
    }
  },
  "required": [
    "uid"
  ],
  "title": "get_end_userArguments"
}

list_user_sessions

列出某终端用户的**会话**——只回元数据：所属 Agent、标题（AI 概括）、消息条数、token、时间。 **不返回消息正文。** 对话记录在控制台里渲染查看：每条会话带 `console_url`——**直达并自动弹出这一段对话**（会话多时不用去详情页里翻），另有 `user_console_url` 指向用户详情页作整体入口。把链接交给租户，由人点进去读原文。翻页把 next_cursor 传回 cursor。

Parameters3

uid	string	required
limit	integer	optional
cursor	string	optional

Raw schema

{
  "type": "object",
  "properties": {
    "uid": {
      "title": "Uid",
      "type": "string"
    },
    "limit": {
      "default": 50,
      "title": "Limit",
      "type": "integer"
    },
    "cursor": {
      "default": "",
      "title": "Cursor",
      "type": "string"
    }
  },
  "required": [
    "uid"
  ],
  "title": "list_user_sessionsArguments"
}

list_page_contexts

列出本租户的全部页面行动指南（含匹配规则、开场白模式、位置）。

Parameters

No parameters.

Raw schema

{
  "type": "object",
  "properties": {},
  "title": "list_page_contextsArguments"
}

upsert_page_context

新建或整条替换一份页面行动指南。 `context` 是**服务端**塞给智能体的页面背景——写"谁会落到这一页、他在决定什么、他通常担心什么"，不要写价格、配额这类事实（那些归知识库，且知识库的效力更高）。 `url_pattern` 是 glob（如 `*/pricing`、`*/solutions/*`），只匹配路径、忽略查询串与结尾斜杠；不给就只能由页面显式报 key。解析顺序：显式 key > url_pattern > 默认。 `greeting_mode="generated"` 让开场白与推荐问题按访客语言即时生成（推荐）； `"static"` 则用你写死的 `greeting` / `questions`。 **这是整条替换**：没传的字段会落回默认值而不是保持原样。改单个字段请先 `list_page_contexts` 读回当前值，合并后再传。

Parameters9

key	string	required
label	string	optional
context	string	optional
url_pattern	any	optional
greeting	any	optional
questions	any	optional
greeting_mode	string	optional
position	integer	optional
is_default	boolean	optional

Raw schema

{
  "type": "object",
  "properties": {
    "key": {
      "title": "Key",
      "type": "string"
    },
    "label": {
      "default": "",
      "title": "Label",
      "type": "string"
    },
    "context": {
      "default": "",
      "title": "Context",
      "type": "string"
    },
    "url_pattern": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Url Pattern"
    },
    "greeting": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Greeting"
    },
    "questions": {
      "anyOf": [
        {
          "items": {
            "type": "string"
          },
          "type": "array"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Questions"
    },
    "greeting_mode": {
      "default": "generated",
      "title": "Greeting Mode",
      "type": "string"
    },
    "position": {
      "default": 100,
      "title": "Position",
      "type": "integer"
    },
    "is_default": {
      "default": false,
      "title": "Is Default",
      "type": "boolean"
    }
  },
  "required": [
    "key"
  ],
  "title": "upsert_page_contextArguments"
}

resolve_page_context

给一个 URL（或 key），看它会命中哪一份指南——写完匹配规则务必用它验一次。 glob 很容易写出"看着对、实际不匹配"的规则（少一个 `*`、多一层路径），而线上表现只是访客悄悄拿到了默认剧本，没有任何报错。

Parameters2

url	string	optional
key	string	optional

Raw schema

{
  "type": "object",
  "properties": {
    "url": {
      "default": "",
      "title": "Url",
      "type": "string"
    },
    "key": {
      "default": "",
      "title": "Key",
      "type": "string"
    }
  },
  "title": "resolve_page_contextArguments"
}

page_context_stats

每份指南的打开数与推荐问题点击数——用来找"写了没人点"的文案。

Parameters

No parameters.

Raw schema

{
  "type": "object",
  "properties": {},
  "title": "page_context_statsArguments"
}

list_storylines

列出本租户的故事线（可按 agent 过滤）。含状态、版本、是否默认线。

Parameters1

agent

any

optional

Raw schema

{
  "type": "object",
  "properties": {
    "agent": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Agent"
    }
  },
  "title": "list_storylinesArguments"
}

get_storyline

取一条故事线的完整定义（整图 graph + profile_schema + 顶层字段）。

Parameters1

storyline_id

string

required

Raw schema

{
  "type": "object",
  "properties": {
    "storyline_id": {
      "title": "Storyline Id",
      "type": "string"
    }
  },
  "required": [
    "storyline_id"
  ],
  "title": "get_storylineArguments"
}

create_storyline

新建故事线草稿。建完先 validate_storyline 自检，再 publish_storyline 发布。 graph = {"nodes":[Node,...], "edges":[]}（edges 由 exits 派生，可留空）。 Node = { node_key: 稳定 uuid（编辑中不变，出口/漏斗按它引用）, title, task（可含 {维度}/{blackboard.键} 插值）, type: "task"(默认) | "document_review"(视觉预审上传件) | "export"(导出结构化报告) | "parallel"(并行/AND-join), review: {"checkpoints":[str]} —— type=document_review：逐条视觉审查点, export: {"sections":[str]} —— type=export：报告章节, parallel: {"branches":[{"key":str,"label":str,"to_node_key":str},...]} —— type=parallel：声明若干必需分支，各指向一条子流程入口；用户可任意顺序做，引擎自动追踪完成度，全部完成后才走本节点唯一的 join 出口（放 exits[0]）。分支子流程末步用普通 exit 回到本 parallel 节点即可，无需手写完成标记。 flags: {"is_entry":bool, "is_terminal":bool}, on_enter_opening: 入场主动说一句（空=静默切换）, ai_eval_trigger: 何时跑 ai 判定的自然语言条件（空=每轮可判）, callback: {"mode":"none"|"backend"|"ui_redirect", "wait_timeout_secs":int, "signal_name":str}, profile_writes: [{"dim":str, "source":"ai"|"rule"|"callback"}] —— 本节点写哪些维度, resources: {"skills":[str],"knowledge_bases":[str],"tools":[str],"resource_mode":"additive"|"replace"}, exits: [Exit,...]（按列表顺序=优先级；确定性 rule/callback/user_choice 先判，ai 最后） } Exit = {"kind":..., "label":str, "to_node_key":str, "ai_criteria":str —— kind=ai：一句自然语言判据, "user_choice":{"button_text":str} —— kind=user_choice, "rule_ast":RuleAst —— kind=rule（见下，AST 非字符串）, "callback_signal":"done"|"timeout"|"canceled" —— kind=callback, "target_storyline_id":str, —— kind=goto_storyline "writes":[{"ref":"dim"|"blackboard","key":str,"op":"set"|"inc","value":<num|str|bool>},...]} —— 走过此出口时确定性写状态（把 profile_writes 的 source='rule' 落地）： set=赋值（做完成标记/分支旗）、inc=自增（循环/重试计数，value 缺省 1）。dim 写受 profile_schema 约束。 kind ∈ ai|user_choice|rule|callback|goto_storyline。组合出常见控制流（都确定性、不赌 LLM）：if/else/switch=同一节点多条 rule 出口（顺序=优先级）； loop/重试=回边 + writes 的 inc 计数 + rule 上限门；AND-join=parallel 节点或 hub+完成标记+and 规则。 RuleAst 二选一：比较 {"op":">="|">"|"<="|"<"|"=="|"!=", "left":{"ref":"dim"|"blackboard","key":str}, "right":{"value":<num|str|bool>}} 布尔 {"op":"and"|"or", "clauses":[RuleAst,...]} profile_schema = 维度定义，如 {"listening":{"type":"int","min":0,"max":100,"visible_to_user":true}}。 on_complete="goto_next" 时必须给 next_storyline_id（否则 validate/publish 被拦）。入线（谁在何时进入本线）：is_default=true 首次对话自动入线（每 Agent 至多一条）； allow_agent_enroll=true 则 Agent 可在对话中自行把用户带入本线——此时务必写 enroll_trigger （一句自然语言的「何时进入」，如「访客表示想申请贷款」），否则 Agent 无触发依据、几乎不入线；须发布后生效，与 is_default、手动指派相互独立。详见 /docs/tenant-guide/storylines。

Parameters12

agent_name	string	required
key	string	required
name	string	optional
description	string	optional
graph	any	optional
profile_schema	any	optional
is_default	boolean	optional
learner_visibility	string	optional
on_complete	string	optional
next_storyline_id	any	optional
allow_agent_enroll	boolean	optional
enroll_trigger	string	optional

Raw schema

{
  "type": "object",
  "properties": {
    "agent_name": {
      "title": "Agent Name",
      "type": "string"
    },
    "key": {
      "title": "Key",
      "type": "string"
    },
    "name": {
      "default": "",
      "title": "Name",
      "type": "string"
    },
    "description": {
      "default": "",
      "title": "Description",
      "type": "string"
    },
    "graph": {
      "anyOf": [
        {
          "additionalProperties": true,
          "type": "object"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Graph"
    },
    "profile_schema": {
      "anyOf": [
        {
          "additionalProperties": true,
          "type": "object"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Profile Schema"
    },
    "is_default": {
      "default": false,
      "title": "Is Default",
      "type": "boolean"
    },
    "learner_visibility": {
      "default": "hidden",
      "title": "Learner Visibility",
      "type": "string"
    },
    "on_complete": {
      "default": "end",
      "title": "On Complete",
      "type": "string"
    },
    "next_storyline_id": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Next Storyline Id"
    },
    "allow_agent_enroll": {
      "default": false,
      "title": "Allow Agent Enroll",
      "type": "boolean"
    },
    "enroll_trigger": {
      "default": "",
      "title": "Enroll Trigger",
      "type": "string"
    }
  },
  "required": [
    "agent_name",
    "key"
  ],
  "title": "create_storylineArguments"
}

update_storyline

整体替换一条故事线草稿（PUT 语义）。graph/Node/Exit/RuleAst 结构见 create_storyline。 expected_version 传入可做乐观锁校验。

Parameters14

storyline_id	string	required
agent_name	string	required
key	string	required
name	string	optional
description	string	optional
graph	any	optional
profile_schema	any	optional
is_default	boolean	optional
learner_visibility	string	optional
on_complete	string	optional
expected_version	any	optional
next_storyline_id	any	optional
allow_agent_enroll	boolean	optional
enroll_trigger	string	optional

Raw schema

{
  "type": "object",
  "properties": {
    "storyline_id": {
      "title": "Storyline Id",
      "type": "string"
    },
    "agent_name": {
      "title": "Agent Name",
      "type": "string"
    },
    "key": {
      "title": "Key",
      "type": "string"
    },
    "name": {
      "default": "",
      "title": "Name",
      "type": "string"
    },
    "description": {
      "default": "",
      "title": "Description",
      "type": "string"
    },
    "graph": {
      "anyOf": [
        {
          "additionalProperties": true,
          "type": "object"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Graph"
    },
    "profile_schema": {
      "anyOf": [
        {
          "additionalProperties": true,
          "type": "object"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Profile Schema"
    },
    "is_default": {
      "default": false,
      "title": "Is Default",
      "type": "boolean"
    },
    "learner_visibility": {
      "default": "hidden",
      "title": "Learner Visibility",
      "type": "string"
    },
    "on_complete": {
      "default": "end",
      "title": "On Complete",
      "type": "string"
    },
    "expected_version": {
      "anyOf": [
        {
          "type": "integer"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Expected Version"
    },
    "next_storyline_id": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Next Storyline Id"
    },
    "allow_agent_enroll": {
      "default": false,
      "title": "Allow Agent Enroll",
      "type": "boolean"
    },
    "enroll_trigger": {
      "default": "",
      "title": "Enroll Trigger",
      "type": "string"
    }
  },
  "required": [
    "storyline_id",
    "agent_name",
    "key"
  ],
  "title": "update_storylineArguments"
}

validate_storyline

校验故事线图（入口/死胡同/不可达/悬空/跳线目标/规则维度）。返回 {ok, errors}。发布前必过。

Parameters1

storyline_id

string

required

Raw schema

{
  "type": "object",
  "properties": {
    "storyline_id": {
      "title": "Storyline Id",
      "type": "string"
    }
  },
  "required": [
    "storyline_id"
  ],
  "title": "validate_storylineArguments"
}

publish_storyline

发布故事线：先校验（有阻塞错误则 422），通过后冻结为不可变版本并置 published。

Parameters1

storyline_id

string

required

Raw schema

{
  "type": "object",
  "properties": {
    "storyline_id": {
      "title": "Storyline Id",
      "type": "string"
    }
  },
  "required": [
    "storyline_id"
  ],
  "title": "publish_storylineArguments"
}

unpublish_storyline

下线（归档）：不再自动入线，在途用户下一轮静默降级为普通 Agent（进度保留，重新发布可续）。

Parameters1

storyline_id

string

required

Raw schema

{
  "type": "object",
  "properties": {
    "storyline_id": {
      "title": "Storyline Id",
      "type": "string"
    }
  },
  "required": [
    "storyline_id"
  ],
  "title": "unpublish_storylineArguments"
}

clone_storyline

复制一条故事线为新草稿（新 key、未发布、不抢默认、不带串联指向），供改动微调。

Parameters1

storyline_id

string

required

Raw schema

{
  "type": "object",
  "properties": {
    "storyline_id": {
      "title": "Storyline Id",
      "type": "string"
    }
  },
  "required": [
    "storyline_id"
  ],
  "title": "clone_storylineArguments"
}

export_storyline

导出可移植的故事线 JSON（schema_version + 定义，不含租户/版本/id），供备份、迁移或再导入。

Parameters1

storyline_id

string

required

Raw schema

{
  "type": "object",
  "properties": {
    "storyline_id": {
      "title": "Storyline Id",
      "type": "string"
    }
  },
  "required": [
    "storyline_id"
  ],
  "title": "export_storylineArguments"
}

import_storyline

导入一份导出的故事线 JSON，落成草稿。**「读小说/资料生成故事线」这类产物由此落地**。 payload = export_storyline 的返回结构（schema_version + graph + profile_schema + 顶层字段）。版本号感知：高于系统支持的版本会被拒。始终新建、不抢默认、key 冲突自动改名。 override_agent_name 可把导入的线改绑到目标租户存在的 Agent。

Parameters2

payload	object	required
override_agent_name	any	optional

Raw schema

{
  "type": "object",
  "properties": {
    "payload": {
      "additionalProperties": true,
      "title": "Payload",
      "type": "object"
    },
    "override_agent_name": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Override Agent Name"
    }
  },
  "required": [
    "payload"
  ],
  "title": "import_storylineArguments"
}

io.agent4/agent4-tenant (MCP)

🛠️ Key Features

🚀 Use Cases

⚡ Developer Benefits

⚠️ Limitations

list_agents

get_agent

create_agent

update_agent

list_tools

list_mcp_servers

create_share

list_shares

list_skills

get_skill

create_skill

update_skill

list_knowledge_bases

get_knowledge_base

create_knowledge_base

update_knowledge_base

add_knowledge_text

add_knowledge_file

search_knowledge_base

improve_prompt

diagnose_prompt

usage_stats

tenant_info

search_agent4_docs

list_end_users

get_end_user

list_user_sessions

list_page_contexts

upsert_page_context

resolve_page_context

page_context_stats

list_storylines

get_storyline

create_storyline

update_storyline

validate_storyline

publish_storyline

unpublish_storyline

clone_storyline

export_storyline

import_storyline

Install

Remote endpoint