Assistants：配置、版本与 Schema

Assistant 是“某个 graph 的已配置实例”，不是一次执行。它把 graph_id 与 config、静态 context、metadata、名称/描述绑定，并有自己的 UUID 和版本。Run 再引用 Assistant 执行。

端点地图

能力	方法与路径	成功/关键错误
创建	`POST /assistants`	200；graph 不存在 404；重复 409；根文档与 create 页是同一操作的两个入口
读取/删除	`GET`、`DELETE /assistants/{assistant_id}`	200；不存在 404
Patch	`PATCH /assistants/{assistant_id}`	200；结构错误 422
搜索/计数	`POST /assistants/search`、`POST /assistants/count`	metadata、graph、name 过滤
图结构	`GET /assistants/{id}/graph`	返回 graph 的节点/边视图
Schema	`GET /assistants/{id}/schemas`	input、output、state、config、context schemas
子图	`GET /assistants/{id}/subgraphs`	列全部子图
指定 namespace 子图	`GET /assistants/{id}/subgraphs/{namespace}`	namespace 不合法 422
版本列表	`POST /assistants/{id}/versions`	返回历史 Assistant 版本
设最新版本	`POST /assistants/{id}/latest`	把指定版本设为 latest

创建、更新与响应模型

AssistantCreate 只有 graph_id 必填；graph ID 通常来自 langgraph.json。可选：

自定义 assistant_id；未提供时生成 UUID；
config：tags、recursion limit、configurable 等图运行配置；
context：附加到 Assistant 的静态上下文；
metadata；
name（默认 Untitled）和 description；
if_exists：raise（默认）或 do_nothing。后一种会返回既有 Assistant，适合幂等 provisioning，但调用方仍要核对配置是否符合预期。

Patch 可更新 graph、config、context、metadata、name、description。响应的 Assistant 包含 ID、graph ID、配置、context、创建/更新时间、metadata、整数 version、name 和 description。

不能把 metadata 当安全控制；租户、owner 与权限必须由服务端可信身份和授权过滤决定。静态 context 会进入 Agent 行为面，变更需要和 prompt/config 一样做审查、版本与回滚。

搜索、字段选择与版本

搜索请求支持：

metadata 每个 KV 精确匹配；
graph ID；
name 大小写不敏感的 substring；
limit=10、offset=0，limit 范围 1–1000；
按 assistant ID、created/updated time、name、graph ID 排序；
select 只返回选定字段，降低大 config/context 的传输。

版本 API 解决“同一 Assistant 配置如何演进”。发布方应保存 Assistant ID + version，而不是只保存“latest”；线上回滚应把已验证版本显式设为 latest，并确认新的 Run 使用了目标版本。并发更新要使用外部发布锁或版本检查，避免两个流水线互相覆盖 latest。

Schema 与子图发现

GraphSchema 把 graph ID 与 input/output/state/config/context schema 暴露出来。客户端应用、Studio、生成式 UI 和接口网关应据此做输入校验，而不是猜测 messages 是唯一输入。子图列表与 namespace 查询适合检查嵌套图结构、流式 namespace 和调试，但不应把内部节点名长期写死为公共业务 API。

生产检查

创建时自带稳定 UUID，并用 if_exists=do_nothing 实现幂等后再对比 graph/config 摘要。
Run 前读取 Schema 并验证输入；Schema/版本变化进入兼容性检查。
Patch 与 latest 切换记录操作者、旧/新版本、配置 diff 和回滚版本。
删除前确认没有 Cron、Run 或外部客户端仍引用 Assistant。
graph/subgraph 与 config 可能包含内部实现信息，按租户和角色授权，不对匿名用户开放。