接入你的 Agent：选接入方式，传配置

快速开始里的 Adapter 写死了一个 localhost 地址，只能单轮对话。真实项目很快会遇到这些问题：本地和预发环境地址不同，想比较两个模型，想检查工具调用。这一页说明怎样把那个最小 Adapter 变成能长期用的接入。

先选接入方式

AI SDK 应用

基于 Vercel AI SDK 的应用，用内置适配器直接连现有 HTTP 接口，不用手写映射。

Claude Code、Codex 等 Coding Agent

用内置 Sandbox Agent，把 Agent 放进隔离环境里跑。

其它 AI 应用

手写一个 Adapter 的 send 函数。应用已有 OTel 埋点的，还能接入 OTel看调用瀑布图。

被测对象不是对话式 Agent，而是提供发帖、生图这类业务操作的应用时，用 defineAdapter，见评估自定义应用。

连接真实的入口

被测对象是独立的 HTTP 服务时，Adapter 应该调用线上实际使用的那个接口，即使服务代码和评估用例在同一个仓库里。不要为了方便改成在进程内直接调用函数：

HTTP 层、序列化、中间件和流式传输都会被绕过，评估通过不代表线上行为正确。
HTTP Adapter 换一个 baseUrl 就能连本地、预发或生产；进程内调用只能在当前代码库里跑。

Agent 本来就只提供 SDK、函数或 CLI 时，就在 send 里直接调用它，不要为了套用 HTTP 写法额外搭一个服务。被测服务的启动和停止不归 Adapter 管。先用项目自己的开发命令、部署脚本或 CI 把服务起好，确认健康检查通过，再运行评估。服务起不来时，让评估如实报错，不要用写死的回复冒充运行结果。需要每次评估自动起停的服务，见启动实验共享服务。

两条传配置的通道

接入里最容易乱的是“这个值该从哪里传”。只有两条通道：

连到哪里、怎么鉴权，走 Adapter 工厂。 URL、鉴权 header、协议开关这类环境级配置，作为工厂参数写在 Experiment 文件里。
这次跑什么配置，走 ctx。 Experiment 里的 model 和 flags，NiceEval 每轮经 ctx 交给 send。Adapter 不解释它们的含义，原样转给应用。

把快速开始里的 Adapter 改成工厂：

// agents/my-agent.ts
import { completeEvidenceCoverage, defineAgent } from "niceeval/adapter";
import type { Agent } from "niceeval/adapter";

export function myAgent(options: { baseUrl: string }): Agent {
  return defineAgent({
    name: "my-agent",
    evidenceCoverage: completeEvidenceCoverage,
    async send(input, ctx) {
      const r = await fetch(`${options.baseUrl}/chat`, { // 连到哪里：来自工厂参数
        method: "POST",
        headers: { "content-type": "application/json" },
        body: JSON.stringify({
          message: input.text,
          model: ctx.model, // 跑哪个模型：来自 Experiment
          flags: ctx.flags, // 开哪些开关：来自 Experiment
        }),
        signal: ctx.signal, // 超时和取消
      });
      const body = await r.json();
      return {
        status: r.ok ? "completed" : "failed",
        events: [{ type: "message", role: "assistant", text: body.reply }],
      };
    },
  });
}

Experiment 里调用工厂，再声明 model 和 flags：

// experiments/local.ts
import { defineExperiment } from "niceeval";
import { myAgent } from "../agents/my-agent.ts";

export default defineExperiment({
  agent: myAgent({ baseUrl: "http://localhost:3000" }),
  model: "gpt-5.4",
  flags: { promptVariant: "concise" },
});

要分别评估本地和生产，写两个 Experiment，只换 baseUrl：

// experiments/prod.ts
export default defineExperiment({
  agent: myAgent({ baseUrl: "https://api.example.com" }),
  model: "gpt-5.4",
});

pnpm exec niceeval exp local
pnpm exec niceeval exp prod

不要把 URL 写进命令行。Experiment ID 后面的位置参数只用来筛选评估用例。 ctx 上每轮能用到的字段：

字段	来自	Adapter 怎么用
`signal`	NiceEval 的超时和取消	挂到发出的每个请求上
`model`	Experiment 的 `model`	应用接口接受模型选择就转发，不接受就忽略
`flags`	Experiment 的 `flags`	原样转发，放请求体或 header 都行
`session`	每段对话一份	多轮续接和人工介入的状态存取，见编写 Send
`telemetry`	配置了 OTel 接入时出现	把 `headers` 里的 `traceparent` 放进请求头，见 OTel 接入
`progress(update)`	当前这轮调用	在终端显示正在做什么，不保存
`diagnostic(input)`	当前这轮调用	记下事后要回看的异常，会随结果保存

报告进度和异常

调用上游比较慢，或者响应不完整时，用 ctx 报告，不要直接 console.log：

async send(input, ctx) {
  ctx.progress({ message: "等待上游模型" });
  const response = await callAgent(input, { signal: ctx.signal });

  if (response.eventsIncomplete) {
    ctx.diagnostic({
      code: "incomplete-event-stream",
      level: "warning",
      message: "上游响应缺少工具结果事件",
      data: { requestId: response.requestId },
      dedupeKey: `incomplete-event-stream:${response.requestId}`,
    });
  }

  return toTurn(response);
}

三种情况分开处理：

被测 Agent 正常回复了，但这一轮它自己报告失败：返回 status: "failed"。这次运行会得出结论，通常是 failed。
连接失败、响应没法解析，评估没法继续：直接抛出异常。这次运行记为 errored，终端会给出 locator。
能继续，但有值得记下的异常：写一条 ctx.diagnostic。它不会改变通过与否。

终端只显示一行错误摘要。完整的错误信息、堆栈和诊断，用 niceeval show @<locator> 查看。

没跑通时先查哪里

fetch 直接抛错，例如连接被拒：应用没起来，或者 URL 不对。先用 curl 对同一个接口发一次请求确认。
t.succeeded() 没过：请求发出去了，但 Adapter 返回了 failed。检查应用的错误响应是怎么映射到 status 的。
只有内容断言没过：接入已经通了。用 niceeval show @<locator> --execution 看应用实际回了什么，再决定改断言还是改应用。

按需加上更多能力

最小接入只能检查回复文本。下面这些能力都只改 Adapter，已有的评估用例不用动：

想检查	Adapter 要做的	怎么做
调用了哪些工具、顺序、没调用什么	把应用返回的工具调用映射成标准事件	编写 Send · 第四步
多轮对话、并行的独立会话	用 `ctx.session` 续接上下文	编写 Send · 第二步
token 和费用	返回 `usage`	编写 Send · 第三步
需要人审批才继续的流程	返回 `waiting` 并说明在等什么	HITL
浏览器里的调用瀑布图	让应用把 OTel span 也发给 NiceEval	OTel 接入
比较两版 prompt 或功能开关	应用把变体做成可以用 `flags` 切换	编写实验

各项能力分别需要应用配合到什么程度，见 Tier。

参考实现

examples/zh/tier1 有五个可运行的接入示例：AI SDK v7、Claude SDK、Codex SDK、Pi SDK 和 LangGraph。它们覆盖工具调用断言、多轮隔离、HITL 的批准与拒绝，以及调用瀑布图。send 的完整字段见 Adapter，全部官方适配器见官方适配器一览。

开始使用

接入你的应用

写好评估用例

评估 Coding Agent

实验与对比

看结果与迭代

提速：并发与复用

基础设施与 CI

问题排查

接入你的 Agent：选接入方式，传配置

先选接入方式

AI SDK 应用

Claude Code、Codex 等 Coding Agent

其它 AI 应用

连接真实的入口

两条传配置的通道

报告进度和异常

没跑通时先查哪里

按需加上更多能力

参考实现

​先选接入方式

AI SDK 应用

Claude Code、Codex 等 Coding Agent

其它 AI 应用

​连接真实的入口

​两条传配置的通道

​报告进度和异常

​没跑通时先查哪里

​按需加上更多能力

​参考实现

先选接入方式

连接真实的入口

两条传配置的通道

报告进度和异常

没跑通时先查哪里

按需加上更多能力

参考实现