Target、Graph 与 Agent 轨迹评估

Target function 契约

evaluate() 的 target 接收一个 Example 的 inputs，返回应用输出字典；evaluator 必须与该输出结构一致。target 内的 traceable 调用会成为根 target trace 的 child runs，因此既能评最终输出，也能访问内部步骤。单个模型调用、非 LLM 组件、完整应用、LangChain Runnable 和已编译 LangGraph graph 都可以成为 target。

Python 大任务优先 aevaluate()；JavaScript/TypeScript 的 evaluate() 本身已经是 async。Graph 只要包含 async node，Python 必须使用 aevaluate()。元数据中的保留键 models、prompts、tools 会填充 experiment 专用列，便于分组与过滤，但应写真实版本/标识，不能把它们当自由文本备注。

三种运行入口

入口	适合	代价
SDK	常规自动化、CI、大批量实验	功能最完整，需引入 SDK
Playground	无代码比较 prompt/model	dataset input key 必须匹配 prompt variables；最多 15 个输入变量
REST API	非 Python/TS 或受限环境	需自行创建 dataset、project/run、关联 example、上传 feedback 和处理重试

SDK 是官方推荐入口，包含更多性能与可靠性处理。Playground 跑实验前建议先提交 prompt 版本，否则之后难以复现实验。REST 只是不便使用 SDK 时的协议级替代，不应遗漏幂等、分页、轮询、部分失败与限流控制。

OpenTelemetry 应用接入

已经使用 OTel 的应用可以绕开 evaluate()：创建关联 dataset 的 experiment session，把 traces 发往 LangSmith，并给根 span 设置：

langsmith.trace.session_id：路由到 experiment；
langsmith.reference_example_id：关联具体 Example；
langsmith.span.kind：标识 chain/model/tool 等类型；
inputs / outputs：记录 target 输入输出。

自托管 OTLP endpoint 使用实例地址并追加 /api/v1/otel。experiment/session 与 example ID 若漏传或错传，trace 即使可见也不能成为正确的评估行。2026-02 文档示例中 Strands TypeScript SDK 尚不支持该 OTel observability 路径，这是示例集成限制，不是 OTel 协议本身的能力判断。

中间步骤与 Graph

RAG 等流水线应分别评 retrieval 和 generation。自定义 evaluator 可遍历 run/rootRun 读取 child runs；相关示例要求 langsmith>=0.3.13。如果 Graph state 已保存 messages、工具结果或决策，优先直接从最终 state 评估；只有 state 不含所需证据时才下钻 trace，减少对内部 span 命名的脆弱耦合。

Graph 有三种测试粒度：

端到端调用整个 graph，判断最终 state；
从 state 或 Run 检查中间节点/工具调用；
直接调用单个 node，降低运行时间和模型费用。

端到端不能替代节点测试，节点测试也不能证明 routing、checkpoint、并发与恢复路径正确。

Multi-turn simulation

OpenEvals simulator 在 simulated user 与 app 间轮流传递单条 chat message。app 接收 message 与 thread_id，并按 thread 维护历史；运行到 max_turns 或自定义 stopping condition，返回完整 trajectory。模拟的优势是低成本覆盖上下文丢失、重复行为和长对话失败，缺点是表面面积更大、可重复性比固定单轮 dataset 低。

使用 pytest/Vitest/Jest 时通过 trajectory evaluators 在对话结束后评分；使用 evaluate() 时把 simulation 放入 target，target 输出完整 trajectory。persona 可以作为 dataset 字段逐例变化；固定初始 response 和随机种子/模型参数有助于重现。

Trajectory match

AgentEvals 支持四种匹配：

模式	语义	适合
strict	消息和工具调用顺序完全一致	授权前必须查策略等强顺序流程
unordered	同一组工具，顺序不限	可并行或顺序无关的检索
subset	实际工具只能来自 reference	防止越权与无关工具调用
superset	至少包含 reference 工具，可有额外调用	验证最低必需动作

默认工具相等还要求参数相同，可用 match mode/override 调整。路径存在多种正确解时，用 LLM-as-judge 按效率、合理性和 rubric 判断，可选 reference trajectory；代价是更慢、更贵且非确定。高风险动作仍应保留确定性 policy/argument 检查，不能只靠 judge。