Adapter：把 Agent 接入 NiceEval

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

interface WebAgentOptions {
  baseUrl: string;
  apiKey?: string;
}

export function webAgent(options: WebAgentOptions): Agent {
  const baseUrl = options.baseUrl.replace(/\/$/, "");

  return defineAgent({
    name: "web-agent",
    async send(input, ctx) {
      ctx.progress({ message: "等待 Web Agent" });
      const response = await fetch(`${baseUrl}/api/turn`, {
        method: "POST",
        headers: {
          "content-type": "application/json",
          ...(options.apiKey ? { authorization: `Bearer ${options.apiKey}` } : {}),
          ...ctx.telemetry?.headers,
        },
        body: JSON.stringify({
          message: input.text,
          files: input.files,
          model: ctx.model,
          flags: ctx.flags,
        }),
        signal: ctx.signal,
      });

      if (!response.ok) {
        ctx.diagnostic({
          code: "agent-http-error",
          level: "error",
          message: `Web Agent 返回 HTTP ${response.status}`,
          data: { status: response.status },
        });
        return {
          status: "failed",
          events: [{ type: "error", message: `HTTP ${response.status}` }],
        };
      }

      const body = await response.json();
      return {
        status: "completed",
        events: body.events,
        data: body.data,
        usage: body.usage,
      };
    },
  });
}

// experiments/staging.ts
import { defineExperiment } from "niceeval";
import { webAgent } from "../agents/web-agent.ts";

export default defineExperiment({
  agent: webAgent({
    baseUrl: "https://staging.example.com",
    apiKey: process.env.STAGING_AGENT_API_KEY,
  }),
  model: "gpt-5.4",
  flags: { promptVariant: "concise" },
});

interface Agent {
  readonly name: string;
  send(input: TurnInput, ctx: AgentContext): Promise<Turn>;
  // 可选：setup / teardown（每沙箱一次的生命周期）；
  // 观测相关的可选成员不参与 send，见「OTel 接入」
}

interface TurnInput {
  readonly text: string;                          // 每轮必有：发送的文本；回答轮 = 回答文本（多条以换行连接）
  readonly files?: readonly InputFile[];          // 仅 t.sendFile 轮：附带的文件（base64）
  readonly responses?: readonly InputResponse[];  // 仅回答轮（t.respond / t.respondAll）：逐请求的结构化回答
  readonly outputSchema?: JsonSchema;             // 仅本轮声明了 output 时：结构化输出要求，已降为 JSON Schema
}

interface InputFile {
  readonly filename?: string;     // 可选，供 adapter / 模型参考
  readonly mimeType: string;      // 如 image/png
  readonly dataBase64: string;    // base64 内容，JSON 友好，可直接放进请求体
}

interface InputResponse {
  readonly requestId: string;    // 必有：对应哪条 input.requested 请求，多个请求并停时靠它对位
  readonly optionId?: string;    // 与 text 二选一：回答命中了请求 options 里的某个 id（approve / deny…）
  readonly text?: string;        // 与 optionId 二选一：自由文本回答（请求没有选项，或回答不是任何选项）
}

// ① 单个待处理请求，回答命中选项（approve / deny 同理，只是 optionId 不同）
await t.respond("approve");
// → { text: "approve",
//     responses: [{ requestId: "req_1", optionId: "approve" }] }

// ② 多个请求并停，用对象形式显式对位
await t.respond({ request, optionId: "deny" });
// → { text: "deny",
//     responses: [{ requestId: request.id, optionId: "deny" }] }

// ③ 回答不是任何选项 → 自由文本（等补充信息的请求就是这种）
await t.respond("收件人改成 ceo@corp.com");
// → { text: "收件人改成 ceo@corp.com",
//     responses: [{ requestId: "req_1", text: "收件人改成 ceo@corp.com" }] }

// ④ respondAll：每条待处理请求一条回答，同一个 optionId
await t.respondAll("approve");
// → { text: "approve\napprove",
//     responses: [{ requestId: "req_1", optionId: "approve" },
//                 { requestId: "req_2", optionId: "approve" }] }

interface AgentContext {
  // 每轮都在的反馈与运行上下文
  readonly signal: AbortSignal;    // 运行器的超时与取消：透传给你发出的每个请求
  readonly session: AgentSession;  // 本条会话线的状态槽
  progress(update: { message: string; current?: number; total?: number }): void;
  diagnostic(input: {
    code: string;
    level: "warning" | "error";
    message: string;
    data?: Readonly<Record<string, JsonValue>>;
    dedupeKey?: string;
  }): void;

  // 按接入档位出现的三个（见「接入分三个 Tier」）
  readonly model?: string;         // Tier 1 的模型对比：experiment.model 透传；应用接口收模型选择就转发
  readonly reasoningEffort?: string;  // 推理努力程度：experiment.reasoningEffort 透传，归属与 model 一致
  readonly telemetry?: Telemetry;  // Tier 2：本轮的 W3C trace context（headers，每轮一个新 traceparent）
  readonly flags: Readonly<Record<string, unknown>>;  // Tier 3 的 feature A/B：experiment.flags 透传；没配时是 {}
  readonly experimentId?: string;  // 路径推导的实验 id，与结果里的 experimentId 同源；不经 experiment 跑时是 undefined

  readonly sandbox: Sandbox;       // 非 sandbox 型 Agent 也会拿到一个 Sandbox（remote agent 是无操作的 stub）
}

interface AgentSession {
  // 会话续接：服务端记历史（接口收会话 id 的形状）
  readonly id?: string;                      // 本线记过的会话 id；新会话线是 undefined
  capture(id: string | undefined): void;     // 记回传的 id；只在还没记过时落地

  // 会话续接：客户端带全量历史（Chat Completions 形）
  history<TMsg>(): { get(): TMsg[]; commit(messages: TMsg[]): void };

  // HITL：停轮现场的存取（take 取到即清除，一次消费）
  hold<T>(state: T): void;
  take<T>(): T | undefined;

  // 逃生舱：自由状态槽，起始 {}，框架从不写入
  readonly state: Record<string, unknown>;
}

interface Turn {
  readonly events: StreamEvent[];          // ★ 标准事件流——每个 Adapter 的核心产物
  readonly data?: JsonValue;               // 本轮结构化产物；仅当 input.outputSchema 出现时填，运行器按声明校验
  readonly status: "completed" | "failed" | "waiting";  // waiting = 停轮等人（HITL）
  readonly usage?: Usage;
}

[
  { type: "action.called", callId: "c1", name: "get_weather", input: { city: "北京" } },
  { type: "action.result", callId: "c1", output: { temp: 21 }, status: "completed" },
  { type: "message", role: "assistant", text: "北京今天 21°C。" },
]

// eval 侧：output 声明既是给应用的要求，也是 turn.data 的类型来源
const turn = await t.send("这张发票总额多少?", {
  output: z.object({ amount: z.number(), currency: z.string() }),
});
turn.data.amount;   // 类型是 number——不是 unknown，不用手动收窄