主题
编码智能体元数据契约
用于规范化编码智能体在向 LangSmith 发送运行时必须输出的追踪元数据的元数据模式。
该模式是编码智能体附加到 LangSmith 运行的元数据的权威契约。它定义了每次运行必须包含哪些字段、在运行时能够提供时应当包含哪些字段，以及哪些字段仅适用于特定的运行类型。
编码智能体集成使用该模式，以确保其追踪结构一致、可查询，并与 LangSmith 的可观测性和过滤功能兼容。
支持的集成
以下集成实现了该模式：
| 集成 | ls_integration 值 |
|---|---|
| Claude Code | claude-code |
| OpenAI Codex | openai-codex |
| Deep Agents | deepagents-code |
| Cursor | cursor |
| Pi | pi |
| Opencode | opencode |
| GitHub Copilot | copilot |
全局身份信息块
每种运行类型都必须在其元数据中包含以下身份字段：
| 字段 | 描述 |
|---|---|
ls_agent_type | 该运行在智能体中的类型。应为 "root"、"subagent"、"middleware" 或 "compaction" 之一。 |
ls_agent_purpose | 智能体的高层用途，例如 "coding"。 |
ls_integration | 发送该运行的集成的标识符（参见支持的集成）。 |
ls_agent_runtime | 人类可读的运行时名称，例如 "Claude Code 1.0.28"。 |
thread_id | 会话线程的稳定标识符。用于在 LangSmith 的 Threads 视图中对相关运行进行分组。 |
ls_trace_schema_version | 当前为 "coding-agent-v1"。 |
可用性层级
该模式中的字段被标记为以下三种可用性层级之一：
| 层级 | 含义 |
|---|---|
| always | 必须在每次运行中存在。 |
| where_known | 当运行时能够暴露该值时必须提供。仅在运行时确实无法提供该信息时才省略。 |
| contextual | 可选元数据。不适用时省略。 |
运行类型
该模式区分五种运行类型。某些字段仅适用于其中一部分运行类型。
| 运行类型 | 描述 |
|---|---|
root | 表示一次完整智能体轮次或会话的顶层运行。 |
llm | 一轮对话中的一次语言模型调用。 |
tool | 一轮对话中的一次工具调用。 |
subagent | 嵌套或委派的子智能体运行。 |
interrupted | 在完成之前被中断的运行。 |
各运行类型的必填字段
所有运行类型
全局身份信息块 中的字段在所有运行类型上都是必须的。
所有运行类型上还需要的其他字段：
| 字段 | 层级 | 描述 |
|---|---|---|
ls_agent_version | where_known | 智能体运行时的版本字符串，例如 "1.0.28"。 |
git_branch | where_known | 正在编辑的仓库中当前活动的 Git 分支。 |
git_commit_sha | where_known | 当前 Git 提交的完整 SHA。 |
git_repo_url | where_known | 仓库的远程 URL。 |
working_directory | where_known | 工作目录的绝对路径。 |
llm 运行
| 字段 | 层级 | 描述 |
|---|---|---|
ls_model_name | where_known | 模型标识符，例如 "claude-opus-4-5"。 |
ls_provider | where_known | 模型服务商，例如 "anthropic"。 |
tool 运行
| 字段 | 层级 | 描述 |
|---|---|---|
ls_tool_name | always | 被调用的工具名称，例如 "bash" 或 "computer"。 |
subagent 运行
| 字段 | 层级 | 描述 |
|---|---|---|
ls_subagent_id | always | 子智能体的稳定标识符。 |
ls_subagent_type | always | 子智能体的类型或角色，例如 "researcher"。 |
interrupted 运行
被中断的运行携带与 root 运行相同的字段。运行类型本身即表明异常终止状态；不会额外增加必填字段。