---
type: study
created: 2026-08-11
updated: 2026-08-11
sensitivity: standard
status: verified
tags:
  - study
  - langchain
  - langsmith
  - smith-api
  - threads
  - context-hub
topic: LangSmith Smith API Threads 查询、Context Hub 目录、Repo 所有权与 ACE 执行边界
sources:
  - https://docs.langchain.com/langsmith/smith-api/ace/execute
  - https://docs.langchain.com/langsmith/smith-api/directories/create-directory-commit
  - https://docs.langchain.com/langsmith/smith-api/directories/delete-directory-repository
  - https://docs.langchain.com/langsmith/smith-api/directories/get-directory-contents
  - https://docs.langchain.com/langsmith/smith-api/ownerships/add-repo-owner
  - https://docs.langchain.com/langsmith/smith-api/ownerships/list-repo-owners
  - https://docs.langchain.com/langsmith/smith-api/ownerships/remove-repo-owner
  - https://docs.langchain.com/langsmith/smith-api/threads/query-single-thread-stats
  - https://docs.langchain.com/langsmith/smith-api/threads/query-thread-traces
  - https://docs.langchain.com/langsmith/smith-api/threads/query-threads
last_verified: 2026-08-11
---

# Smith API：Threads、Context Hub 目录、Repo 所有权与 ACE

这一组把会话级观测查询、Agent/Skill 内容版本、Prompt Hub repo 所有权和自定义代码测试入口连接起来。共同原则是“稳定标识与显式作用域”：Thread 必须和 project UUID 一起查询，目录内容必须固定 commit/tag，repo 所有权必须经过现有 owner 授权，任意代码执行则只应存在于强隔离测试域。

## 查询 Threads

`POST /api/v2/threads/query` 在一个 tracing project 内按时间窗口与 filter 查询会话线程。请求字段：

- project_id；
- min_start_time，默认当前 UTC 前 1 天，inclusive；
- max_start_time，默认当前 UTC，exclusive；
- filter，作用在每个 thread 的 root run；
- page_size，默认 20、范围 1–100；
- opaque cursor。

返回按最近活动排序的 thread summary：turn/errored-turn 数、首末 trace、输入输出预览、最后错误、p50/p99、token/cost 总计与细分、feedback stats。响应可能少于 page_size 但仍有 next_cursor，不能用 `items.length < page_size` 判断结束；只有 next_cursor 为空才结束。

时间边界必须固定在整次翻页期间，不能每页都让默认“now”漂移。增量同步保存 opaque cursor 与窗口上限，最终按 thread_id 去重。filter 使用 LangSmith filter expression，不拼接未转义的用户片段。

## 查询 Thread 内 Traces

`GET /api/v2/threads/{thread_id}/traces` 必填 project_id，page_size 同为 1–100，用 cursor 翻页。filter 针对每个 root trace run。`selects` 控制投影，可选 thread/trace ID、op、token/cost、time/latency、inputs/outputs/full or preview、error/full or preview、name 等。

只有选择的字段才出现；trace_id 始终返回。若完全省略 selects，trace_id 是唯一 fallback 字段。调用方不能把“字段不存在”解释成值为 0/null，也不应默认选 full inputs/outputs；列表先取 ID、preview、status/cost，用户明确下钻后再读取完整 payload，以降低延迟与敏感数据暴露。

## 单 Thread 聚合统计

`GET /api/v2/threads/{thread_id}/stats` 必填 session_id 与至少一个重复的 `selects` 参数。可选择：

- turns 与首/末 start/end time；
- latency p50/p99；
- prompt/completion/total tokens 与细分类；
- prompt/completion/total cost 与细分类；
- feedback stats。

响应只填选中的聚合字段。成本单位是 USD，latency 单位是秒；细节字段的 raw keys 与模型相关，不能硬编码固定 category。Stats 还支持 trace filter，因此同一 thread 在不同 filter 下结果可不同，监控指标必须记录 filter/version。

三个 Thread V2 endpoint 的 self-hosted 最低版本是 LangSmith v0.16。Security 明确要求 API Key 或 Bearer 之外还要 Tenant ID；project/session ID 仍由服务端验证归属。错误使用 RFC 7807 Problem Details，包含 LangSmith 扩展 remedy，并明确区分 400、401、403、404、422、500、503、504。

## Context Hub Directory Commit

Directory API 将 agent/skill repo 表示为扁平 file tree。路径中的 owner 可用 `-` 代表当前 workspace。

`POST /api/v1/platform/hub/repos/{owner}/{repo}/directories/commits` 的 `files` 是 path 到 Entry 的 map：对象表示创建/更新文件或 link，null 表示 delete/unlink。`parent_commit` 提供乐观并发基线；409 时应重新读取 latest 并做三方合并，不能直接覆盖。

`skip_webhooks` 是单一 boolean。文档特别指出它不同于 Prompt Hub CreateCommit 的 bool-or-list 形状：Context Hub v1 不支持按 webhook 逐个过滤。复用 SDK model 时不能把两个字段当同一类型。

Get directory 可按 commit hash、tag 或 latest 解析，返回 commit hash/ID 与 flattened files。生产 agent 启动应固定已审批 commit，而不是每次读 latest；latest 适合编辑器浏览。Delete directory repo 会删除 agent/skill repo 及其拥有的 child file repos，成功 204，是高风险级联操作，需备份 commit 与依赖引用。

## Prompt Hub Repo Owners

Repo owner API 使用 `{owner}/{repo}`：

- Add 以 email 指定新 owner，调用者必须已经是 owner；
- List 要求 repo read permission；
- Remove 以 identity_id 指定，调用者也必须是现有 owner。

返回 owner 含 ls_user_id、created_at，以及可能为空的 identity_id、email、full_name。对 repo tenant 之外的用户，identity/email 可因 PII 保护而为空；客户端不能因为 null 就删除或覆盖 owner。转移所有权时先添加并验证新 owner，再删除旧 owner，并避免移除最后一个可管理 owner。

Add/remove 是写操作，超时后先 list 核对；email 是邀请定位符，不是稳定主键，后续移除使用 identity UUID。Owner 变更需审计，但对普通读者脱敏 email/identity。

## ACE Execute 的边界

`POST /api/v1/ace/execute` 页面只将其描述为“为测试目的执行自定义代码”。请求必填 code、language、args[]，响应是无结构 object；只有 200/422 被形式化。

它没有在这些页面中承诺：支持哪些语言、隔离级别、网络/文件权限、资源上限、幂等性、输出 schema 或长期兼容性。因此不能把它当通用生产 compute API。调用前必须由目标环境的额外文档或实测确认能力，并在外层设置：

- 允许语言与代码大小白名单；
- CPU、内存、墙钟、输出与并发限额；
- 无长期 secret、最小网络和只读输入；
- 每次执行独立身份与审计；
- 超时不自动重放有副作用代码。

模型生成代码也必须经过相同隔离，不能因为来源是 Agent 就提升权限。若业务需要可恢复、文件 I/O 或明确命令语义，应选择 Sandbox API，而不是依赖 ACE 的通用 object contract。

## 组合使用的安全路径

```text
Thread query（最小 selects）
  → 识别需要分析的 trace
  → 固定 Context Hub commit
  → 校验 repo owner / read permission
  → 在受控 Sandbox 或测试 ACE 中执行
  → 结果写回独立评估/Issue 流程
```

Thread inputs/outputs 与 repo files 都可能包含敏感数据或可执行指令。不要把 trace 内容未经审查直接拼进 code，也不要让 repo 中的 instruction 自动获得控制面凭据。固定 project、tenant、commit 与执行身份，才能让一次分析可复现、可审计和可撤销。