agent4.io

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

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

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

改 Agent 的**部分**字段——没传的字段保持原样。 ⚠️ 列表字段语义，别搞混：`tools=[...]` / `skills=[...]` / `knowledge_bases=[...]` 是 **整表替换**——你没读到的项会被挤掉。想"加一个 / 删一个"，用 `add_tools` / `remove_tools` （及 add_/remove_skills、add_/remove_knowledge_bases）：增量、幂等、不动其它项。 改完**读返回值**核对最终列表，别凭调用成功就宣布"已启用"。 另：工具也可以绑在技能上（

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

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

给某个 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

列出某 Agent 的分享入口（token / label / 是否停用 / 聊天链接 / 嵌入地址 / 外观配置）。 顶层 `pretty_url` 非空时，它是**发给人**的首选链接（见 create_share 的说明）。

按客户品牌配置这个分享入口的**外观**——没传的字段保持原样（服务端局部合并）。 - `theme_color`：品牌主色，`#RGB` 或 `#RRGGBB`。**只需要给这一个颜色。** 文字与前景色由服务端按 WCAG 对比度自动推导并落库（浅色品牌色会自动改用深色文字， 而不是白色）——**不要自己算配色，也不要试图设置文字颜色**，那会被覆盖。 - `logo_url`：绝对 URL。标题栏按高度自适应，任何比例都放得下；**收起态的气泡是方的**， 所以只有接近方形（宽高比 0.74–1.35）的图才会用在气泡上，横版字标会在

配置**租户全局**的 PWA 品牌与安装体验（作用于所有 `/s/` 独立聊天页）。 - `icon_source_url`：一张母图的公开 URL（≥192×192 的 PNG/JPG/WebP，最好是正方形 logo）。 服务端自动出全套：浏览器标签页 favicon(48) + 安装图标 192/512 + Android maskable(512)。 非正方形按中心裁方。设置后，终端用户「添加到主屏幕」装到的就是租户自己的图标。 - `install_prompt`：安装提示形态——`banner`（聊天页里一条可关闭的细横幅，默认）、

把客户自己的域名绑到本租户的对话页：`https://chat.client.com/` 直接呈现租户品牌页 （或指定 agent 的对话页），地址栏保持客户域名，证书自动签发。 **先让客户把 DNS 配好**：在他们的 DNS 商处添加 CNAME，指向返回里的 `cname_target` （`endpoint.agent4.io`）。要点： - **只支持子域**（如 `chat.client.com`）。裸域（`client.com`）无法用 CNAME —— 让客户 改用子域，或用支持 CNAME flattening 的 DNS 商（

列出本租户的技能。

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

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

改技能的部分字段——没传的保持原样（服务端 PATCH 合并，不再 GET+PUT 两跳）。 ⚠️ `tools=[...]` 是**整表替换**；加/删单个用 `add_tools`/`remove_tools`（增量、幂等）。 技能绑定的工具在该技能挂上的 Agent 聊天时自动生效——无需再写进 Agent 的 tools。

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

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

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

改知识库的部分字段——没传的保持原样（服务端 PATCH 合并）。

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

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

把某个字段的文字改写得更适合当"给 AI 的系统提示词",返回改好的那一段。 field ∈ persona | task | greeting | storyline_task | storyline_opening | storyline_ai_trigger | storyline_ai_criteria | skill_description | skill_instructions | kb_description | kb_instructions ——决定改写目标(Task 要像命令、知识库 description

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

用量统计。group ∈ total | agent | user | space | day | model。 只有 token 计数与事件数等**元数据**，不含任何对话内容。 用 group="user" 看谁用得最多，group="agent" 看哪个 Agent 最忙。

本租户的基本信息与配额（含自定义域名绑定状态，如有）。

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 a

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

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

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

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

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

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

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

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

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

新建故事线草稿。建完先 validate_storyline 自检，再 publish_storyline 发布。 concurrency——进度跟随谁："user"（默认）= 进度属于人，该用户所有会话共享一个 run， 适合教学大纲/入职引导/KYC；"session" = 进度属于案件，每个会话独立一个 run， 新开对话=新开一份申请，适合许可证申请/工单/按产品的流程。案件态写 blackboard （随 run 走），人的事实写 profile 维度（跨 run 共享）。 graph = {"nodes":[Node,...], "edg

改故事线草稿的**部分**字段——没传的保持原样（先 GET 再合并，底层是全量 PUT）。 concurrency："user"=进度属于人（全会话共享）；"session"=进度属于案件（每会话独立 run）。 改动只影响**之后**的入线，在途 run 不迁移。 ⚠️ 特别是 `graph`：不传 = 保持现有的图。（此工具曾把"不传 graph"当成空图整体替换—— 改个名字就清掉整张流程图。现已改为局部语义；真想清空图，显式传 `{"nodes":[],"edges":[]}`。） graph/Node/Exit/RuleAst 结构见 c

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

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

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

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

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

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