--- type: study created: 2026-08-11 updated: 2026-08-11 sensitivity: standard status: verified tags: - study - langchain - langsmith - smith-api - issues-agent - beta topic: LangSmith Smith API Issues Agent、Issue 状态、Webhook 与修复验证 sources: - https://docs.langchain.com/langsmith/smith-api/issues-agent/create-the-issues-agent-for-a-session-beta - https://docs.langchain.com/langsmith/smith-api/issues-agent/delete-the-issues-agent-for-a-session-beta - https://docs.langchain.com/langsmith/smith-api/issues-agent/get-the-issues-agent-config-for-a-session-beta - https://docs.langchain.com/langsmith/smith-api/issues-agent/list-issues-agent-configs-beta - https://docs.langchain.com/langsmith/smith-api/issues-agent/roll-an-issues-agent-webhook-signing-secret - https://docs.langchain.com/langsmith/smith-api/issues-agent/save-the-agent-overview-for-a-session-beta - https://docs.langchain.com/langsmith/smith-api/issues-agent/update-the-issues-agent-config-for-a-session-beta - https://docs.langchain.com/langsmith/smith-api/issues/get-issue-beta - https://docs.langchain.com/langsmith/smith-api/issues/list-issues-beta - https://docs.langchain.com/langsmith/smith-api/issues/list-viewed-issues-for-a-session-beta - https://docs.langchain.com/langsmith/smith-api/issues/mark-issue-viewed-beta - https://docs.langchain.com/langsmith/smith-api/issues/record-a-fix-verification-verdict - https://docs.langchain.com/langsmith/smith-api/issues/start-preview-deploy-verification-for-a-fix last_verified: 2026-08-11 --- # Smith API：Issues Agent、Issue 状态与修复验证 Issues Agent 针对一个 tracing project/session 扫描 traces，提炼 issue，并可衔接 GitHub 修复与 preview deployment 验证。所有 create/get/list/update/delete 与 issue 查询页面都标注 Beta，接口和数据模型可能无通知变更；它适合受控试点，不应未经兼容层直接成为不可替代的生产控制面。 ## 每个 Session 一个 Issues Agent `POST /api/v1/platform/sessions/{session_id}/issues-agent` 创建配置并入队首次扫描。一个 session 已有 agent 时返回 409。初始配置可包含： - GitHub repo URL、base branch、repo subdirectory； - Context Hub repo handle； - priorities； - `run_filter` traces-filter DSL。 `run_filter` 是 Engine 的 prompt guidance，并不是服务端强制执行的查询边界。不能用它实现租户隔离、合规排除或安全访问控制；不应被分析的 trace 必须在采集、项目划分和服务端授权层隔离。 Agent 读模型还包含 cron enable/schedule、engine version、issue count、latest deployment run/thread、preview verification 开关、Agent Overview repo、每月 LCU 上限以及 workspace/session 标签。`tenant_name` 由服务端 join，便于 org admin 跨 workspace 列表展示；这不意味着普通 workspace 成员获得跨租户权限。 Delete 返回 204，并删除 agent config、其 issues 和 agent-overview Hub repo，是明确级联删除。执行前应导出仍需保留的 issue/overview，停止 cron 与在途修复；不要把它当“暂时关闭”。暂时停用应修改 cron 或相关 feature flag，而不是 delete。 ## PATCH 的三态字段 Update 是 partial patch，省略字段保持不变。特别要区分： - `run_filter`：字段缺失不改，空字符串清除； - `user_instructions`：空字符串清除，前端不能用 null；这是用户拥有的权威偏好，Engine 会在下一次扫描把它协调进 Overview，但不会自行编辑该字段； - `session_lcu_spend_limit_monthly`：字符串序列化以保留 NUMERIC(28,6) 精度；缺失不改，0 或正数为月上限，0 会立即视为已达上限，负数清除并存为 NULL； - `agent_overview_accepted`、cron、preview verify 等布尔值要显式区分“false”与“未发送”。 Session 限额与 Organization 限额独立、同时执行。配置 GitHub repo 发生变化时，服务端会清除相关 fix 字段；这与设置 overview repo ID 在同一 CRUD transaction 完成。客户端超时后先 GET 回读，不应再次用旧快照覆盖已发生的副作用。 ## Agent Overview 与 Prompt Hub `PATCH .../issues-agent/overview` 保存 overview content；若没有 backing repo 会创建私有 Prompt Hub repo，否则创建新 commit，并返回 repo ID 与 commit hash。Overview 是版本化知识，不是临时 UI 文本：更新前保留 commit，避免多个编辑者以最后写入覆盖。 `user_instructions` 与 Overview 不是同一事实源。前者属于用户、Engine 只读取；后者是协调后的 agent context，可由保存 endpoint 形成 commit。审核流程应展示差异并明确“accepted”状态，不能由后台扫描静默替用户接受。 ## Issue 模型与状态 Issue 包含 name、description、tags、首次/末次出现、关联 traces、proposed fix/context/prompt/example 修复、GitHub branch/PR、verification、watching_since 与 recurrence count。 状态枚举：open、fixing、watching、completed、ignored。严重级是整数并映射为 0=urgent、1=high、2=medium、3=low。不要按常见“数字越大越严重”的假设排序。 List 可按 session ID/name、status、severity、tag、updated_at 筛选；sort_by 为 created_at、updated_at 或 severity。limit 默认 50、上限 500，使用 offset。大规模增量同步应以 updated_at checkpoint 加 ID 去重，单靠 offset 在并发更新下可能跳项或重复。 ## Viewed 状态是用户维度 `POST /issues/{id}/views` 幂等记录“当前用户打开过该 issue”，成功 204；`GET /sessions/{session_id}/issues/views` 返回 issue ID 与 viewed_at。它只驱动 UI 的 unread row 与 Engine tab badge，不改变 issue 的业务 status，也不表示团队已确认或完成处置。 多设备可重复 mark viewed；404/403 后不要把本地 badge 强制清零。客户端将服务端 view set 与当前 issue list 合并展示即可，不需要创造新的共享“已读”状态。 ## Webhook Secret 轮换 `POST .../issues-agent/webhooks/{id}/roll-secret` 立即替换 signing secret，之后的投递马上使用新 secret。响应 webhook 对象包含 signing_secret、event_types、status/severity filter、URL 或 Slack channel/team 目标和 headers。 由于切换立即生效，消费者应支持短暂双 secret 验证窗口，或先协调停投/部署新 secret 再 rotate。完整 secret 只在 secret manager 传递，不进入普通 API 日志、trace 或笔记。Slack 目标与 URL 是互斥交付方向，组织安装由服务端解析；仍要防止将跨组织 channel 配置到错误 session。 ## Preview 修复验证闭环 `POST /issues/{id}/start-preview` 接收 commit_sha、run_id、thread_id：打开或复用 fix PR，添加 preview label，并调度轮询；preview ready 后恢复 fix run。返回 PR number 与 preview URL。 随后 `POST /issues/{id}/fix-verdict` 写入 status 与 detail，返回完整 verification：attempt、commit SHA、branch/PR、preview URL、deadline、ready check、run/thread/session IDs 与时间戳。 ```text issue fixing → commit/branch → open or reuse PR → preview deployment pending → replay verification → verdict → watching / completed / retry ``` Start-preview 可能在客户端超时前已经创建 PR/label，因此重试前先 GET issue/verification。Preview URL 属于外部执行面，测试数据要脱敏，凭据与网络权限最小化。Verdict detail 是诊断证据，不要存完整敏感 trace payload。 ## Beta 上线边界 1. 通过内部 adapter 封装 Beta schema，保存未知字段并容忍新增 enum；不要让业务表直接镜像所有 API 字段。 2. 每次升级做 contract test：create/get/patch、三态清除、list filter、view 幂等、overview commit、preview/verdict。 3. Cron 与扫描要有 LCU 上限、并发限制、失败退避和手动 kill switch。 4. Engine 提议的代码、prompt、context 和 examples 都必须人工或策略审批；Issue 的“proposed”字段不是已验证修复。 5. 对 delete cascade、secret rotation、GitHub repo 切换和 preview label 记录审计，并准备独立回滚路径。