---
type: study
created: 2026-08-11
updated: 2026-08-11
sensitivity: standard
status: verified
tags:
  - study
  - langchain
  - langsmith
  - agent-server
  - assistants
topic: LangSmith Agent Server Assistants API
sources:
  - https://docs.langchain.com/langsmith/agent-server-api/assistants
  - https://docs.langchain.com/langsmith/agent-server-api/assistants/count-assistants
  - https://docs.langchain.com/langsmith/agent-server-api/assistants/create-assistant
  - https://docs.langchain.com/langsmith/agent-server-api/assistants/delete-assistant
  - https://docs.langchain.com/langsmith/agent-server-api/assistants/get-assistant
  - https://docs.langchain.com/langsmith/agent-server-api/assistants/get-assistant-graph
  - https://docs.langchain.com/langsmith/agent-server-api/assistants/get-assistant-schemas
  - https://docs.langchain.com/langsmith/agent-server-api/assistants/get-assistant-subgraphs
  - https://docs.langchain.com/langsmith/agent-server-api/assistants/get-assistant-subgraphs-by-namespace
  - https://docs.langchain.com/langsmith/agent-server-api/assistants/get-assistant-versions
  - https://docs.langchain.com/langsmith/agent-server-api/assistants/patch-assistant
  - https://docs.langchain.com/langsmith/agent-server-api/assistants/search-assistants
  - https://docs.langchain.com/langsmith/agent-server-api/assistants/set-latest-assistant-version
last_verified: 2026-08-11
---

# 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 可能包含内部实现信息，按租户和角色授权，不对匿名用户开放。