以编程方式使用文档

当您追踪不在支持列表中的代理框架或 LLM 客户端、通过 RunTree 或 REST API 手动发送运行，或诊断在 消息视图.

提取策略 是指每个集成的逻辑，它读取追踪中的 LLM 和工具运行，并生成消息视图渲染的有序对话。对于每个支持的集成，本页记录了决定 LangSmith 应用哪种策略的元数据键、策略在 inputs 和 outputs上期望的 JSON 结构，以及工具调用如何与其结果配对。

提取策略解析

对于每个追踪，第一个匹配的提取策略优先。每个策略的检测在看到来自另一个集成的标记时会明确地让位于其他策略。最常见的冲突： ls_provider: "openai" 与 LangChain 形状的负载配对；在这种情况下 OpenAI 策略会让位于 LangChain。如果没有策略匹配追踪的第一个运行，消息 API 将返回 400 no adapter pair found for trace format.

集成策略主要元数据信号追踪默认值（LangSmith SDK）
Vercel AI SDKvercells_integration: "vercel-ai-sdk" or ai_sdk_method是（wrapAISDK)
OpenAI 聊天补全openails_provider: "openai" or "azure" (no use_responses_api）是（wrap_openai)
OpenAI 响应openails_provider 加上 ls_invocation_params.use_responses_api: true是（wrap_openai 响应）
OpenAI 代理 SDKopenails_integration: "openai-agents-sdk"是（Python 追踪处理器）
Anthropic 消息（wrap_anthropic)anthropicls_message_format: "anthropic" （今天必须明确设置）部分：provider 已设置，格式键是选择性加入
Claude 代理 SDK（Python）anthropicls_integration: "claude-agent-sdk"是
Claude Codeanthropicls_integration: "claude-code"由 claude-code 本身设置
Claude 代理 SDK（JS）anthropic当前不 **自动匹配（发送** ）"claude-agent-sdk-js"Provider 是，格式否（差距）
LangChain 聊天模型langchainls_integration: "langchain_chat_model"Yes (langchain-core)
LangGraphlangchaingraph_id or langgraph_nodeYes (langgraph)
langchain.create_agentlangchainls_integration: "langchain_create_agent" （回退到其他信号）Yes (langchain)
深度代理langchainls_integration: "deepagents" or "deepagents-cli"Yes (deepagents)

LangChain 和 LangGraph

涵盖 BaseChatModel派生的 LLM 运行、LangGraph 图， deepagents，以及 langchain.create_agent.

检测

元数据上存在以下任何一项都会触发提取：

  • - ls_message_format is "langchain" （显式覆盖）
  • - ls_integration is "langchain_chat_model", "deepagents", or "deepagents-cli"
  • - graph_id 存在（LangGraph 根）
  • - langgraph_node 存在（LangGraph 子运行；子运行即使在 graph_id 仅在根上时也会携带此标记）

当这些标记存在时，OpenAI 检测会显式遵循 LangChain 的判断，因此即使 ls_provider: "openai".

追踪默认值

**langchain-core** BaseChatModel 在每次聊天模型运行时设置以下内容：

  • - metadata.ls_integration: "langchain_chat_model"
  • - 加上特定提供商的 _get_ls_params() 输出（ls_provider, ls_model_name, ls_model_type, ls_temperature, ls_max_tokens, ls_stop)

**langchain.create_agent** 设置 metadata.ls_integration: "langchain_create_agent" 在代理配置上。

LangGraph 设置 graph_id （根）以及 langgraph_node （每个子运行）。

深度代理 设置 metadata.ls_integration: "deepagents" 在根链运行上；CLI 变体使用 "deepagents-cli".

运行结构

LangChain 使用其构造函数格式序列化消息。 id 数组的最后一个元素标识类：

{
  "lc": 1,
  "type": "constructor",
  "id": ["langchain", "schema", "messages", "AIMessage"],
  "kwargs": {
    "content": "...",
    "id": "run-abc-123",
    "type": "ai",
    "tool_calls": [
      {"name": "search", "args": {}, "id": "call_1", "type": "tool_call"}
    ],
    "tool_call_id": "call_1"
  }
}

角色映射（ id 的最后一个元素 → 规范角色）：

  • - SystemMessage → system
  • - HumanMessage → human
  • - AIMessage → ai
  • - ToolMessage, FunctionMessage → tool
  • - ChatMessage → human

Inputs:

  • - inputs.messages is [[msg, msg, ...]]。LangChain 为批量生成包装了一层额外的数组；在提取过程中会展开外层数组。

输出 （多个路径，按顺序尝试）：

  1. outputs.generations[0][*].message：标准聊天模型输出
  2. outputs.messages[]：直接消息（例如，LangGraph 状态输出）
  3. outputs.output.update.messages[]：deepagents-cli 子代理输出；内部消息携带 tool_call_id 链接到子代理调用
  4. outputs.output （对象）：工具运行的回退

工具调用匹配

tool_calls[*].id 在助手消息上匹配以下任一项 kwargs.tool_call_id （构造函数格式）或顶层 tool_call_id （扁平格式）在工具结果消息上。

去重

优先 kwargs.id （构造函数格式），然后顶层 id （扁平格式），然后回退到 role + content 哈希。稳定的 LangChain 运行 ID 使重新发出时的去重成本低廉。

示例追踪

一个 LangChain 聊天模型运行，发出工具调用、工具运行和后续操作。注意其上的双层嵌套 inputs.messages ([[ ... ]]）和 generations 输出的信封。

[
  {
    "id": "0001",
    "trace_id": "trace-0005",
    "run_type": "llm",
    "name": "ChatOpenAI",
    "metadata": {
      "ls_integration": "langchain_chat_model",
      "ls_provider": "openai",
      "ls_model_name": "gpt-4o"
    },
    "inputs": {
      "messages": [[
        {"lc": 1, "type": "constructor", "id": ["langchain","schema","messages","SystemMessage"],
         "kwargs": {"content": "You are a helpful assistant.", "id": "sys-1"}},
        {"lc": 1, "type": "constructor", "id": ["langchain","schema","messages","HumanMessage"],
         "kwargs": {"content": "what is the weather in paris?", "id": "hu-1"}}
      ]]
    },
    "outputs": {
      "generations": [[{
        "message": {
          "lc": 1, "type": "constructor",
          "id": ["langchain","schema","messages","AIMessage"],
          "kwargs": {
            "content": "",
            "id": "ai-1",
            "tool_calls": [
              {"name": "get_weather", "args": {"city": "Paris"}, "id": "call_abc", "type": "tool_call"}
            ]
          }
        }
      }]]
    }
  },
  {
    "id": "0002",
    "trace_id": "trace-0005",
    "parent_run_id": "0001",
    "run_type": "tool",
    "name": "get_weather",
    "metadata": {"ls_integration": "langchain_chat_model"},
    "inputs": {"city": "Paris"},
    "outputs": {
      "output": {
        "lc": 1, "type": "constructor",
        "id": ["langchain","schema","messages","ToolMessage"],
        "kwargs": {"content": "Sunny, 22C", "tool_call_id": "call_abc", "id": "tool-1"}
      }
    }
  },
  {
    "id": "0003",
    "trace_id": "trace-0005",
    "run_type": "llm",
    "name": "ChatOpenAI",
    "metadata": {
      "ls_integration": "langchain_chat_model",
      "ls_provider": "openai",
      "ls_model_name": "gpt-4o"
    },
    "inputs": {
      "messages": [[
        {"lc": 1, "type": "constructor", "id": ["langchain","schema","messages","SystemMessage"],
         "kwargs": {"content": "You are a helpful assistant.", "id": "sys-1"}},
        {"lc": 1, "type": "constructor", "id": ["langchain","schema","messages","HumanMessage"],
         "kwargs": {"content": "what is the weather in paris?", "id": "hu-1"}},
        {"lc": 1, "type": "constructor", "id": ["langchain","schema","messages","AIMessage"],
         "kwargs": {"content": "", "id": "ai-1",
                    "tool_calls": [{"name": "get_weather", "args": {"city": "Paris"}, "id": "call_abc", "type": "tool_call"}]}},
        {"lc": 1, "type": "constructor", "id": ["langchain","schema","messages","ToolMessage"],
         "kwargs": {"content": "Sunny, 22C", "tool_call_id": "call_abc", "id": "tool-1"}}
      ]]
    },
    "outputs": {
      "generations": [[{
        "message": {
          "lc": 1, "type": "constructor",
          "id": ["langchain","schema","messages","AIMessage"],
          "kwargs": {"content": "It's sunny and 22°C in Paris.", "id": "ai-2"}
        }
      }]]
    }
  }
]

LangGraph 追踪看起来相同但添加了 graph_id / langgraph_node 到元数据中，并可能使用 outputs.messages[] 直接替代 outputs.generations.

OpenAI（wrap_openai)

一种提取策略覆盖 OpenAI API 形状（聊天补全和响应）和 OpenAI Agents SDK（响应形状）。检测从元数据中选取 API 形状。

检测

决策树，按顺序。匹配的第一条规则获胜。

1. metadata.ls_integration: - "openai-agents-sdk" → 响应 - "langchain_chat_model", "deepagents", "deepagents-cli" → 未声明（这些发出 LangChain 形状的有效载荷，带 ls_provider: "openai"；LangChain 提取接收它们） 2. metadata.ls_message_format （显式覆盖，优先于 ls_provider 启发式）： - "responses" → 响应 - "completions" → 补全 - "langchain", "anthropic" → 未声明 - 未知值落入规则 3，以便未来的格式字符串继续工作 3. metadata.graph_id or metadata.langgraph_node 存在 → 未认领 (LangGraph 子树；LangChain 提取甚至在...时也会获取它 ls_provider: "openai") 4. metadata.ls_provider is "openai" or "azure": - If metadata.ls_invocation_params.use_responses_api == true → 响应 - 否则 → 补全

追踪默认值

**wrap_openai** 在每次 LLM 运行中设置以下内容：

  • - metadata.ls_provider: "openai" (or "azure" 如果客户端是 AzureOpenAI / AsyncAzureOpenAI)
  • - metadata.ls_model_type: "chat" or "llm"
  • - metadata.ls_model_name, ls_temperature, ls_max_tokens, ls_stop
  • - metadata.ls_invocation_params：SDK 调用 kwargs 的白名单子集。当调用通过 client.responses.create or client.responses.parse时，此字典包含 use_responses_api: true.
  • - run_type: "llm"
  • - name: "ChatOpenAI", "OpenAI", "AzureChatOpenAI", or "AzureOpenAI" （可覆盖）

wrap_openai 不 **会** 发出 ls_integration or ls_message_format。检测回落到规则 4 (ls_provider).

OpenAI Agents SDK 使用追踪处理器（不是包装器）。在每个 span 上设置：

  • - metadata.ls_integration: "openai-agents-sdk"
  • - metadata.ls_integration_version：包版本
  • - metadata.ls_agent_type: "root" 在根 span 上
  • - LLM span 还携带 metadata.openai_trace_id 和 openai_span_id

Agents SDK 发出 Responses-API 形状的负载，但只有 outputs = {"output": [...]} 。响应的其余部分 (id, model, tools, usage) 位于 extra.metadata，而不是在 outputs.

运行形状

Completions:

  • - inputs.messages 是一个数组 {role, content, tool_calls?, tool_call_id?, refusal?, name?, id?}
  • - outputs.choices[*].message 具有相同的形状（通常为 role: "assistant")
  • - 工具调用 ID 位于 tool_calls[*].id; tool-result 消息通过顶级字段回链 tool_call_id

Responses:

  • - 可选的顶级 inputs.instructions (字符串) 被提升为合成系统消息并前置。
  • - inputs.input 是一个数组，其中每个项目是以下之一：
  • - 一个简单的 {role, content} 消息
  • - 一个带类型的 {type: "message", role, content}
  • - {type: "function_call", call_id, name, arguments} (助手角色)
  • - {type: "function_call_output", call_id, output} (工具角色)
  • - {type: "reasoning", ...} (助手角色)
  • - outputs.output 对于 LLM 运行具有相同的数组形状。对于工具运行，它可以是一个字符串、一个对象或一个裸露的顶级对象（Agents SDK 情况）；每个都被包装为一个工具角色消息，带有 content 设置为 JSON 文本。

工具调用匹配

  • - Completions: tool_call_id 在工具结果消息上匹配 tool_calls[*].id 在前面的助手消息上。
  • - Responses: call_id on function_call 匹配 call_id on function_call_output。裸露对象工具运行输出可能携带 call_id 在...的顶层 outputs.

去重

响应项目按以下内容去重 id 当存在时，否则按项目类型特定内容： call_id|arguments 用于 function_call, call_id|output 用于 function_call_output，以及 content 用于消息。

示例追踪

**聊天补全（wrap_openai):** 三次运行：一次工具调用的助手轮次、工具运行，以及带有最终答案的后续助手轮次。

[
  {
    "id": "0001",
    "trace_id": "trace-0002",
    "run_type": "llm",
    "name": "ChatOpenAI",
    "metadata": {"ls_provider": "openai", "ls_model_name": "gpt-4o"},
    "inputs": {
      "messages": [
        {"role": "system", "content": "You are a helpful assistant."},
        {"role": "user", "content": "what is the weather in paris?"}
      ]
    },
    "outputs": {
      "choices": [{
        "index": 0,
        "finish_reason": "tool_calls",
        "message": {
          "role": "assistant",
          "content": null,
          "tool_calls": [{
            "id": "call_abc123",
            "type": "function",
            "function": {"name": "get_weather", "arguments": "{\"city\":\"Paris\"}"}
          }]
        }
      }]
    }
  },
  {
    "id": "0002",
    "trace_id": "trace-0002",
    "parent_run_id": "0001",
    "run_type": "tool",
    "name": "get_weather",
    "inputs": {"city": "Paris"},
    "outputs": {"tool_call_id": "call_abc123", "role": "tool", "content": "Sunny, 22C"}
  },
  {
    "id": "0003",
    "trace_id": "trace-0002",
    "run_type": "llm",
    "name": "ChatOpenAI",
    "metadata": {"ls_provider": "openai", "ls_model_name": "gpt-4o"},
    "inputs": {
      "messages": [
        {"role": "system", "content": "You are a helpful assistant."},
        {"role": "user", "content": "what is the weather in paris?"},
        {"role": "assistant", "content": null, "tool_calls": [
          {"id": "call_abc123", "type": "function", "function": {"name": "get_weather", "arguments": "{\"city\":\"Paris\"}"}}
        ]},
        {"role": "tool", "tool_call_id": "call_abc123", "content": "Sunny, 22C"}
      ]
    },
    "outputs": {
      "choices": [{
        "index": 0,
        "finish_reason": "stop",
        "message": {"role": "assistant", "content": "It's sunny and 22°C in Paris."}
      }]
    }
  }
]

Responses API（OpenAI Agents SDK）： 项目是带类型的（function_call, function_call_output, message）而不是角色键控的。 inputs.instructions 被提升为合成系统消息。

[
  {
    "id": "0001",
    "trace_id": "trace-0003",
    "run_type": "llm",
    "name": "Helpful Assistant Response",
    "metadata": {"ls_integration": "openai-agents-sdk", "ls_model_name": "gpt-4.1"},
    "inputs": {
      "instructions": "You are a helpful assistant.",
      "input": [{"role": "user", "content": "what time is it in san francisco?"}]
    },
    "outputs": {
      "output": [{
        "type": "function_call",
        "call_id": "call_LVsl",
        "name": "get_time",
        "arguments": "{\"timezone\":\"America/Los_Angeles\"}",
        "id": "fc_0ed8"
      }]
    }
  },
  {
    "id": "0002",
    "trace_id": "trace-0003",
    "parent_run_id": "0001",
    "run_type": "tool",
    "name": "get_time",
    "metadata": {"ls_integration": "openai-agents-sdk"},
    "inputs": {"timezone": "America/Los_Angeles"},
    "outputs": {"output": "12:00 PM (America/Los_Angeles)", "call_id": "call_LVsl"}
  },
  {
    "id": "0003",
    "trace_id": "trace-0003",
    "run_type": "llm",
    "name": "Helpful Assistant Response",
    "metadata": {"ls_integration": "openai-agents-sdk", "ls_model_name": "gpt-4.1"},
    "inputs": {
      "instructions": "You are a helpful assistant.",
      "input": [
        {"role": "user", "content": "what time is it in san francisco?"},
        {"type": "function_call", "call_id": "call_LVsl", "name": "get_time", "arguments": "{\"timezone\":\"America/Los_Angeles\"}", "id": "fc_0ed8"},
        {"type": "function_call_output", "call_id": "call_LVsl", "output": "12:00 PM (America/Los_Angeles)"}
      ]
    },
    "outputs": {
      "output": [{
        "type": "message",
        "role": "assistant",
        "status": "completed",
        "content": [{"type": "output_text", "text": "It is currently 12:00 PM in San Francisco.", "annotations": []}]
      }]
    }
  }
]

Vercel AI SDK

检测

以下任一条件出现在 extra.metadata 的任何 LLM 运行上都会触发提取：

  • - ai_sdk_method key 存在（任意值），或
  • - ls_integration is "vercel-ai-sdk"

两者都由 LangSmith Vercel AI SDK 包装器自动设置。底层语言模型提供商（OpenAI、Anthropic、Google 等）无关紧要；包装器将所有这些规范化为单一消息信封。

追踪默认值

当 Vercel AI SDK 包装器在使用时，SDK 在每个 LLM 运行上设置：

  • - metadata.ls_integration: "vercel-ai-sdk"
  • - metadata.ai_sdk_method: "ai.doGenerate" or "ai.doStream"
  • - metadata.ls_model_name：模型 ID
  • - run_type: "llm"
  • - name: "ai.doGenerate" or "ai.doStream" （可覆盖）

运行形状

LLM 运行：

  • - run_type: "llm"
  • - inputs.messages or inputs.prompt 包含对话
  • - outputs.role 是以下之一 assistant, tool, user
  • - outputs.content 包含发出的内容。工具调用是 content 中的块，带有 toolCallId 和 toolName.

工具运行：

  • - run_type: "tool"
  • - inputs.toolCallId 匹配 LLM 输出的 toolCallId
  • - inputs.toolName or name 标识工具
  • - outputs.output or outputs.result 保存工具结果

工具调用匹配

优先按以下方式匹配 toolCallId；当 ID 不可用时，回退到工具名称。

追踪示例

两次运行的追踪：一次 LLM 运行请求工具调用，一次工具运行返回结果。每个条目都是一个 LangSmith 运行； inputs, outputs，以及 metadata 是线上的 JSON 编码字符串（此处为便于阅读而未转义显示）。

[
  {
    "id": "0001",
    "trace_id": "trace-0001",
    "run_type": "llm",
    "name": "ai.doGenerate",
    "metadata": {
      "ls_integration": "vercel-ai-sdk",
      "ai_sdk_method": "ai.doGenerate",
      "ls_model_name": "gpt-4o"
    },
    "inputs": {
      "prompt": [
        {"role": "user", "content": [{"type": "text", "text": "what's the weather in paris?"}]}
      ]
    },
    "outputs": {
      "role": "assistant",
      "content": [
        {"type": "tool-call", "toolCallId": "call_abc", "toolName": "get_weather", "input": {"city": "Paris"}}
      ]
    }
  },
  {
    "id": "0002",
    "trace_id": "trace-0001",
    "parent_run_id": "0001",
    "run_type": "tool",
    "name": "get_weather",
    "inputs": {"toolCallId": "call_abc", "toolName": "get_weather", "args": {"city": "Paris"}},
    "outputs": {"result": "Sunny, 22C"}
  }
]

Anthropic 消息 (wrap_anthropic)

涵盖 wrap_anthropic (the Messages-API wrapper) and the Claude Agent SDK / Claude Code integrations.

检测

元数据中以下任一内容都会触发提取：

  • - ls_message_format is "anthropic"
  • - ls_integration is "claude-agent-sdk" or "claude-code"

追踪默认值

**wrap_anthropic** 在每次 LLM 运行上设置以下内容：

  • - metadata.ls_provider: "anthropic"
  • - metadata.ls_model_type: "chat"
  • - metadata.ls_model_name, ls_temperature, ls_max_tokens, ls_stop
  • - metadata.ls_invocation_params：允许列表中的子集（mcp_servers, service_tier, tool_choice, top_k, top_p, stream, thinking)
  • - run_type: "llm", name: "ChatAnthropic" （可覆盖）

wrap_anthropic 会 **不** 发出 ls_integration or ls_message_format.

Claude Agent SDK (Python) 在根链运行上设置以下内容：

  • - metadata.ls_integration: "claude-agent-sdk"
  • - metadata.ls_integration_version：包版本
  • - 可选 metadata.model, permission_mode, max_turns

其合成的 LLM 子运行会获取 metadata.ls_provider: "anthropic" 和可选地 ls_model_name，但没有 ls_integration。它们依附于父链的声明（追踪的第一次运行决定选择）。

Claude Agent SDK (JS) 设置 metadata.ls_integration: "claude-agent-sdk-js" 和 ls_agent_type: "root".

运行形状

**wrap_anthropic** 消息 API：

  • - inputs.messages: [{role, content}, ...]
  • - 可选 inputs.system：字符串或内容块数组；成为前置的系统消息
  • - content 可以是字符串或数组 {type, ...} 内容块（text, tool_use, tool_result, image, thinking, redacted_thinking)
  • - 输出保留完整的 Anthropic Message 对象。内容位于以下位置之一：
  • - outputs.message.content （最常见，已包装）
  • - outputs.content 当 outputs.type == "message" （裸）
  • - outputs.content 当 outputs.role == "assistant" （Agent SDK 裸）
  • - outputs.output.messages[0].content （JS SDK）
  • - outputs.messages[0].content （Claude Code）

Claude Agent SDK / Claude Code:

  • - inputs.input （消息数组，相同的 Anthropic 消息形状）。 inputs.messages 当两者都存在且非空时，优先采用此方案。
  • - 工具运行输出使用 outputs.output （对象）或 outputs.content （顶级数组，子代理风格）。

工具调用匹配

tool_use_id 在助手端 tool_use 块匹配 tool_result.tool_use_id 在下一条用户消息中对应的结果块上。

示例追踪

wrap_anthropic 使用工具调用和后续操作的 Messages API。助手轮次返回一个包含 tool_use 块的内容数组；工具结果作为 tool_result 块发送回下一条用户消息中。

[
  {
    "id": "0001",
    "trace_id": "trace-0004",
    "run_type": "llm",
    "name": "ChatAnthropic",
    "metadata": {
      "ls_provider": "anthropic",
      "ls_model_name": "claude-opus-4-7",
      "ls_message_format": "anthropic"
    },
    "inputs": {
      "system": "You are a helpful assistant.",
      "messages": [
        {"role": "user", "content": "what is the weather in paris?"}
      ]
    },
    "outputs": {
      "message": {
        "id": "msg_01",
        "role": "assistant",
        "type": "message",
        "content": [
          {"type": "text", "text": "Let me check."},
          {"type": "tool_use", "id": "toolu_01", "name": "get_weather", "input": {"city": "Paris"}}
        ]
      }
    }
  },
  {
    "id": "0002",
    "trace_id": "trace-0004",
    "parent_run_id": "0001",
    "run_type": "tool",
    "name": "get_weather",
    "inputs": {"city": "Paris"},
    "outputs": {"output": {"temperature": 22, "condition": "Sunny"}}
  },
  {
    "id": "0003",
    "trace_id": "trace-0004",
    "run_type": "llm",
    "name": "ChatAnthropic",
    "metadata": {
      "ls_provider": "anthropic",
      "ls_model_name": "claude-opus-4-7",
      "ls_message_format": "anthropic"
    },
    "inputs": {
      "system": "You are a helpful assistant.",
      "messages": [
        {"role": "user", "content": "what is the weather in paris?"},
        {"role": "assistant", "content": [
          {"type": "text", "text": "Let me check."},
          {"type": "tool_use", "id": "toolu_01", "name": "get_weather", "input": {"city": "Paris"}}
        ]},
        {"role": "user", "content": [
          {"type": "tool_result", "tool_use_id": "toolu_01", "content": "Sunny, 22C"}
        ]}
      ]
    },
    "outputs": {
      "message": {
        "id": "msg_02",
        "role": "assistant",
        "type": "message",
        "content": [{"type": "text", "text": "It's sunny and 22°C in Paris."}]
      }
    }
  }
]

Claude Agent SDK / Claude Code traces look similar but use inputs.input 而不是 inputs.messages 并设置 ls_integration: "claude-agent-sdk" (or "claude-code"）在根链运行上。