#Step 19 — 관측·테스트·평가

const model = fakeModel()
  .respondWithTools([{ name: "get_weather", args: { city: "서울" }, id: "call_1" }])
  .respond(new AIMessage("서울은 맑고 23도입니다."));

const agent = createAgent({ model, tools });
const result = await agent.invoke({ messages: [new HumanMessage("서울 날씨 알려줘")] });

// 흔히 이렇게만 봅니다 — 여기엔 정보가 거의 없습니다.
console.log("최종 답:", result.messages.at(-1)?.text);

// 사실은 이만큼 일어났습니다. messages 배열이 곧 "궤적(trajectory)" 입니다.
for (const m of result.messages) {
  const toolCalls = (m as AIMessage).tool_calls ?? [];
  const suffix = toolCalls.length ? ` → tool_calls: ${toolCalls.map((t) => t.name).join(", ")}` : "";
  console.log(`  [${m.getType()}] ${JSON.stringify(m.text).slice(0, 40)}${suffix}`);
}

console.log("모델 호출 횟수:", model.callCount);

const agent = createAgent({
  model: "anthropic:claude-sonnet-4-6", // OpenAI 대안: "openai:gpt-5.5"
  tools,
  systemPrompt: "너는 한국 도시 정보 도우미다. 도구를 써서 답하라.",
});

const result = await agent.invoke({ messages: [{ role: "user", content: "제주 날씨랑 인구 알려줘" }] });
// → 이 실행이 통째로 smith.langchain.com 에 트레이스로 올라갑니다

import { LangChainTracer } from "@langchain/core/tracers/tracer_langchain";

const tracer = new LangChainTracer();
await agent.invoke({ messages: [{ role: "user", content: "..." }] }, { callbacks: [tracer] });

// 프로젝트를 코드에서 동적으로 지정할 수도 있습니다
const testTracer = new LangChainTracer({ projectName: "email-agent-test" });

await agent.invoke(
  { messages: [new HumanMessage("안녕")] },
  {
    runName: "greeting-flow",                        // 트레이스 목록에 표시될 이름
    tags: ["production", "weather-agent", "v1.0"],   // 필터용 (완전 일치 검색)
    metadata: {
      userId: "user-123",           // 특정 사용자 민원 추적
      sessionId: "sess-456",
      environment: "production",
      promptVersion: "2026-07-17",  // 프롬프트 버전 — A/B 비교의 핵심
    },
  }
);

console.log("fakeModel.calls[0].options 의 키:", Object.keys(model.calls[0].options ?? {}));

import { ConsoleCallbackHandler } from "@langchain/core/tracers/console";

await agent.invoke(
  { messages: [new HumanMessage("부산 날씨?")] },
  { callbacks: [new ConsoleCallbackHandler()] }  // ← 이 한 줄
);

for await (const ev of await agent.stream(
  { messages: [new HumanMessage("제주 인구?")] },
  { streamMode: "debug" }
)) {
  // 이벤트 구조는 결정적입니다: { step, type, timestamp, payload }
  const e = ev as { step: number; type: string; payload: { name?: string } };
  console.log(`  step=${e.step} type=${e.type} node=${e.payload?.name}`);
}

const loggingMiddleware = createMiddleware({
  name: "LoggingMiddleware",
  // 모델 호출을 감싸서 지연시간을 잰다
  wrapModelCall: async (request, handler) => {
    const started = Date.now();
    const response = await handler(request);
    console.log(`  [model] ${Date.now() - started}ms`);
    return response;
  },
  // 도구 호출을 감싸서 이름과 인자를 남긴다
  wrapToolCall: async (request, handler) => {
    const started = Date.now();
    console.log(`  [tool:start] ${request.toolCall.name} args=${JSON.stringify(request.toolCall.args)}`);
    const response = await handler(request);
    console.log(`  [tool:end]   ${request.toolCall.name} (${Date.now() - started}ms)`);
    return response;
  },
});

const agent = createAgent({ model, tools, middleware: [loggingMiddleware] });

check("서울 날씨 조회", (await getWeather.invoke({ city: "서울" })) === "서울: 맑음, 23도");
check("없는 도시는 '정보 없음'", (await getWeather.invoke({ city: "런던" })) === "런던: 날씨 정보 없음");
check("인구는 천단위 콤마", (await getPopulation.invoke({ city: "부산" })) === "부산: 3,300,000명");

import { fakeModel } from "langchain";

const model = fakeModel()
  .respondWithTools([{ name: "get_weather", args: { city: "서울" }, id: "call_1" }])
  .respond(new AIMessage("서울은 맑고 23도입니다."));

const agent = createAgent({ model, tools });
const result = await agent.invoke({ messages: [new HumanMessage("서울 날씨?")] });

check("메시지 4개 (human → ai → tool → ai)", result.messages.length === 4);
check("도구가 실제로 실행되어 ToolMessage 가 생김", result.messages[2].getType() === "tool");
check("ToolMessage 내용이 도구의 실제 반환값", result.messages[2].text === "서울: 맑음, 23도");
check("최종 답은 AI 메시지", result.messages.at(-1)?.getType() === "ai");
check("모델은 2번 호출됨", model.callCount === 2);

const failing = fakeModel().alwaysThrow(new Error("service unavailable"));
const agent = createAgent({ model: failing, tools });
let caught = "";
try {
  await agent.invoke({ messages: [new HumanMessage("서울 날씨?")] });
} catch (e) {
  caught = (e as Error).message;
}
check("모델 장애가 위로 전파된다", caught === "service unavailable");

// vitest.setup.ts
import { langchainMatchers } from "@langchain/core/testing";
expect.extend(langchainMatchers);

// agent.int.test.ts
test("agent calls weather tool", async () => {
  const agent = createAgent({ model: "claude-sonnet-4-6", tools: [getWeather] });
  const result = await agent.invoke({
    messages: [new HumanMessage("What's the weather in SF?")],
  });

  const aiMsg = result.messages.find((m) => AIMessage.isInstance(m) && m.tool_calls?.length);
  expect(aiMsg).toContainToolCall({ name: "get_weather" });
  expect(result.messages.at(-1)).toBeAIMessage();
});

// vitest.config.ts
import { configDefaults, defineConfig } from "vitest/config";

export default defineConfig((env) => {
  if (env.mode === "int") {
    return {
      test: {
        testTimeout: 100_000,          // 실제 모델은 느립니다
        include: ["**/*.int.test.ts"],
        setupFiles: ["dotenv/config"],
      },
    };
  }
  return {
    test: {
      testTimeout: 30_000,
      exclude: ["**/*.int.test.ts", ...configDefaults.exclude],  // 평소엔 제외
    },
  };
});

test.skipIf(!process.env.OPENAI_API_KEY)("agent responds with tool call", async () => { /* ... */ });

type Example = {
  id: string;
  input: string;
  referenceOutput: string;   // 기대 답변
  referenceTools: string[];  // 기대 도구 호출 순서 (19-7 에서 사용)
};

const dataset: Example[] = [
  { id: "ex-1", input: "서울 날씨 알려줘", referenceOutput: "맑음, 23도", referenceTools: ["get_weather"] },
  { id: "ex-2", input: "부산 인구는?", referenceOutput: "3,300,000명", referenceTools: ["get_population"] },
  { id: "ex-3", input: "제주 날씨랑 인구 둘 다", referenceOutput: "비, 21도 / 670,000명",
    referenceTools: ["get_weather", "get_population"] },
];

function containsEvaluator(outputs: { answer: string }, referenceOutput: string) {
  const keys = referenceOutput.split(" / ");
  const hit = keys.filter((k) => outputs.answer.includes(k)).length;
  return { key: "contains", score: hit / keys.length };
}

async function llmJudgeEvaluator(outputs: { answer: string }, referenceOutput: string) {
  // 실전에서는 아래 model 을 "anthropic:claude-sonnet-4-6" 등으로 바꿉니다.
  const judge = fakeModel().structuredResponse({
    score: outputs.answer.includes(referenceOutput.split(" / ")[0]) ? 1 : 0,
    reasoning: "기대 답의 핵심 키워드 포함 여부로 판정",
  });
  const judged = (await judge
    .withStructuredOutput(z.object({ score: z.number(), reasoning: z.string() }))
    .invoke(`기대: ${referenceOutput}\n실제: ${outputs.answer}\n0~1 로 채점하라.`)) as {
    score: number;
    reasoning: string;
  };
  return { key: "llm_judge", score: judged.score, comment: judged.reasoning };
}

function extractTrajectory(messages: BaseMessage[]): string[] {
  return messages
    .filter((m): m is AIMessage => m.getType() === "ai")
    .flatMap((m) => (m.tool_calls ?? []).map((tc) => tc.name));
}

type MatchMode = "strict" | "unordered" | "superset" | "subset";

function trajectoryMatch(actual: string[], reference: string[], mode: MatchMode): boolean {
  const sortedA = [...actual].sort();
  const sortedR = [...reference].sort();
  switch (mode) {
    case "strict":     // 같은 도구를 같은 순서로
      return actual.length === reference.length && actual.every((t, i) => t === reference[i]);
    case "unordered":  // 같은 도구 집합, 순서 무관
      return sortedA.length === sortedR.length && sortedA.every((t, i) => t === sortedR[i]);
    case "superset":   // 기대한 건 다 불렀고, 추가로 더 불러도 OK
      return reference.every((t) => actual.includes(t));
    case "subset":     // 기대 범위를 벗어난 도구는 안 불렀다
      return actual.every((t) => reference.includes(t));
  }
}

import { createTrajectoryMatchEvaluator } from "agentevals";

const evaluator = createTrajectoryMatchEvaluator({
  trajectoryMatchMode: "strict",  // "strict" | "unordered" | "superset" | "subset"
});

import { createTrajectoryLLMAsJudge, TRAJECTORY_ACCURACY_PROMPT } from "agentevals";

const evaluator = createTrajectoryLLMAsJudge({
  model: "openai:o3-mini",
  prompt: TRAJECTORY_ACCURACY_PROMPT,
});

// 기준 궤적을 함께 줄 수도 있습니다
import { TRAJECTORY_ACCURACY_PROMPT_WITH_REFERENCE } from "agentevals";

const THRESHOLD = 0.9;  // 궤적 정확도 최소치
let trajPass = 0;
for (const ex of dataset) {
  const out = await runAgentOn(ex);
  if (trajectoryMatch(extractTrajectory(out.messages), ex.referenceTools, "strict")) trajPass++;
}
const score = trajPass / dataset.length;
console.log(`  궤적 정확도: ${(score * 100).toFixed(0)}% (기준 ${THRESHOLD * 100}%)`);
if (score < THRESHOLD) {
  console.log(`  → CI 라면 여기서 process.exit(1). 기준 미달이므로 머지 차단.`);
}

import * as ls from "langsmith/vitest";

ls.describe("trajectory accuracy", () => {
  ls.test(
    "accurate trajectory",
    {
      inputs: { messages: [/* ... */] },
      referenceOutputs: { messages: [/* ... */] },
    },
    async ({ inputs, referenceOutputs }) => {
      // 에이전트 실행 + 평가자 호출
    }
  );
});

import { evaluate } from "langsmith/evaluation";

await evaluate(runAgent, {
  data: "your_dataset_name",       // LangSmith 데이터셋 이름
  evaluators: [trajectoryEvaluator],
});

// src/agent.ts
export const agent = createAgent({ model: "anthropic:claude-sonnet-4-6", tools, systemPrompt: "..." });

/**
 * Step 19 — 관측·테스트·평가
 * 실행: npx tsx docs/reference/langchain/step-19-observability-eval/practice.ts
 *
 * 이 파일은 [19-1] ~ [19-10] 블록으로 나뉘며, 본문 소제목과 1:1 대응합니다.
 *
 * 중요: 이 파일은 대부분 `fakeModel()` 로 동작하므로 **API 키 없이도 실행됩니다.**
 * 실제 모델을 호출하는 블록은 [19-2] 하나뿐이고, 키가 없으면 스스로 건너뜁니다.
 */
import "dotenv/config";
import {
  createAgent,
  createMiddleware,
  fakeModel,
  tool,
  AIMessage,
  HumanMessage,
  type BaseMessage,
} from "langchain";
import { ConsoleCallbackHandler } from "@langchain/core/tracers/console";
import * as z from "zod";

/* ===== 공통: 이 스텝 내내 쓰는 도구 2개 ===== */

// 도구는 결정적입니다. 같은 입력 → 항상 같은 출력. 그래서 단위 테스트가 됩니다.
const getWeather = tool(
  ({ city }) => {
    const table: Record<string, string> = {
      서울: "맑음, 23도",
      부산: "흐림, 26도",
      제주: "비, 21도",
    };
    const found = table[city];
    if (!found) return `${city}: 날씨 정보 없음`;
    return `${city}: ${found}`;
  },
  {
    name: "get_weather",
    description: "도시의 현재 날씨를 조회합니다. city 는 한국 도시명입니다.",
    schema: z.object({ city: z.string().describe("도시명, 예: 서울") }),
  }
);

const getPopulation = tool(
  ({ city }) => {
    const table: Record<string, number> = { 서울: 9_400_000, 부산: 3_300_000, 제주: 670_000 };
    const found = table[city];
    if (found === undefined) return `${city}: 인구 정보 없음`;
    return `${city}: ${found.toLocaleString("ko-KR")}명`;
  },
  {
    name: "get_population",
    description: "도시의 인구를 조회합니다.",
    schema: z.object({ city: z.string().describe("도시명, 예: 서울") }),
  }
);

const tools = [getWeather, getPopulation];

/* ===== [19-1] 에이전트는 왜 디버깅이 어려운가 ===== */

// invoke() 의 반환값만 보면 "최종 답" 하나입니다.
// 그 사이에 모델이 몇 번 불렸고 어떤 도구를 어떤 인자로 불렀는지는 안 보입니다.
{
  console.log("\n===== [19-1] 최종 답만 보면 아무것도 모른다 =====");

  const model = fakeModel()
    .respondWithTools([{ name: "get_weather", args: { city: "서울" }, id: "call_1" }])
    .respond(new AIMessage("서울은 맑고 23도입니다."));

  const agent = createAgent({ model, tools });
  const result = await agent.invoke({ messages: [new HumanMessage("서울 날씨 알려줘")] });

  // 흔히 이렇게만 봅니다 — 여기엔 정보가 거의 없습니다.
  console.log("최종 답:", result.messages.at(-1)?.text);

  // 사실은 이만큼 일어났습니다. messages 배열이 곧 "궤적(trajectory)" 입니다.
  console.log("\n실제로 벌어진 일 (messages 배열 전체):");
  for (const m of result.messages) {
    const toolCalls = (m as AIMessage).tool_calls ?? [];
    const suffix = toolCalls.length ? ` → tool_calls: ${toolCalls.map((t) => t.name).join(", ")}` : "";
    console.log(`  [${m.getType()}] ${JSON.stringify(m.text).slice(0, 40)}${suffix}`);
  }

  // 모델이 몇 번 불렸나? fakeModel 은 이것도 세어 줍니다.
  console.log("모델 호출 횟수:", model.callCount); // 2 (도구 호출 결정 1번 + 최종 답 1번)
}

/* ===== [19-2] LangSmith 트레이싱 켜기 ===== */

// 코드 변경 없음. 환경변수 3개만 세팅하면 자동으로 트레이스가 올라갑니다.
//   LANGSMITH_TRACING=true
//   LANGSMITH_API_KEY=lsv2_...
//   LANGSMITH_PROJECT=langchain-course   (선택. 없으면 "default")
{
  console.log("\n===== [19-2] LangSmith 트레이싱 =====");
  console.log("LANGSMITH_TRACING =", process.env.LANGSMITH_TRACING ?? "(미설정)");
  console.log("LANGSMITH_API_KEY =", process.env.LANGSMITH_API_KEY ? "(설정됨)" : "(미설정)");
  console.log("LANGSMITH_PROJECT =", process.env.LANGSMITH_PROJECT ?? "(미설정 → default)");

  // 이 블록만 실제 모델을 씁니다. 키가 없으면 건너뜁니다.
  if (process.env.ANTHROPIC_API_KEY) {
    const agent = createAgent({
      model: "anthropic:claude-sonnet-4-6", // OpenAI 대안: "openai:gpt-5.5"
      tools,
      systemPrompt: "너는 한국 도시 정보 도우미다. 도구를 써서 답하라.",
    });
    const result = await agent.invoke({ messages: [{ role: "user", content: "제주 날씨랑 인구 알려줘" }] });
    console.log("실제 모델 응답:", result.messages.at(-1)?.text);
    console.log("→ LANGSMITH_TRACING=true 였다면 smith.langchain.com 에 트레이스가 올라갔습니다.");
  } else {
    console.log("(ANTHROPIC_API_KEY 없음 → 실제 모델 호출 건너뜀)");
  }
}

/* ===== [19-3] 트레이스에 메타데이터/태그/runName 붙이기 ===== */

// 트레이스는 쌓이면 수만 개가 됩니다. 나중에 찾으려면 미리 라벨을 붙여야 합니다.
// runName / tags / metadata 는 invoke() 의 두 번째 인자(config)에 넣습니다.
{
  console.log("\n===== [19-3] runName / tags / metadata =====");

  const model = fakeModel().respond(new AIMessage("네, 도와드리겠습니다."));
  const agent = createAgent({ model, tools });

  await agent.invoke(
    { messages: [new HumanMessage("안녕")] },
    {
      runName: "greeting-flow", // 트레이스 목록에 표시될 이름
      tags: ["production", "weather-agent", "v1.0"], // 필터용 (완전 일치 검색)
      metadata: {
        userId: "user-123", // 특정 사용자 민원 추적
        sessionId: "sess-456",
        environment: "production",
        promptVersion: "2026-07-17", // 프롬프트 버전 — A/B 비교의 핵심
      },
    }
  );
  console.log("runName='greeting-flow', tags=[production, weather-agent, v1.0] 로 실행됨");

  // ⚠️ 함정: config 의 tags/metadata 는 트레이서로 갑니다.
  // fakeModel 이 기록하는 calls[i].options 에는 들어오지 않습니다.
  console.log("fakeModel.calls[0].options 의 키:", Object.keys(model.calls[0].options ?? {}));
  console.log("→ tags/metadata 가 없습니다. 이걸로는 라벨을 검증할 수 없습니다.");
}

/* ===== [19-4] LangSmith 없이 디버깅 ===== */

// (a) 콘솔 콜백 — 가장 빠른 방법. 모든 체인/모델/도구 시작·종료를 stdout 에 찍습니다.
{
  console.log("\n===== [19-4a] ConsoleCallbackHandler =====");

  const model = fakeModel()
    .respondWithTools([{ name: "get_weather", args: { city: "부산" }, id: "call_1" }])
    .respond(new AIMessage("부산은 흐리고 26도입니다."));

  const agent = createAgent({ model, tools });
  await agent.invoke(
    { messages: [new HumanMessage("부산 날씨?")] },
    { callbacks: [new ConsoleCallbackHandler()] } // ← 이 한 줄
  );
  console.log("(위 [chain/start] ... 로그가 ConsoleCallbackHandler 의 출력입니다)");
}

// (b) streamMode: "debug" — 노드 단위로 무슨 일이 일어나는지 이벤트로 받습니다.
{
  console.log("\n===== [19-4b] streamMode: 'debug' =====");

  const model = fakeModel()
    .respondWithTools([{ name: "get_population", args: { city: "제주" }, id: "call_1" }])
    .respond(new AIMessage("제주 인구는 67만명입니다."));

  const agent = createAgent({ model, tools });

  for await (const ev of await agent.stream(
    { messages: [new HumanMessage("제주 인구?")] },
    { streamMode: "debug" }
  )) {
    // 이벤트 구조는 결정적입니다: { step, type, timestamp, payload }
    //   type: "task"        → 노드 실행 시작 (payload.input 있음)
    //   type: "task_result" → 노드 실행 완료 (payload.result 있음)
    const e = ev as { step: number; type: string; payload: { name?: string } };
    console.log(`  step=${e.step} type=${e.type} node=${e.payload?.name}`);
  }
}

// (c) 커스텀 로깅 미들웨어 — 팀 전체에 일관된 로그를 강제하고 싶을 때.
{
  console.log("\n===== [19-4c] 커스텀 로깅 미들웨어 =====");

  const loggingMiddleware = createMiddleware({
    name: "LoggingMiddleware",
    // 모델 호출을 감싸서 지연시간을 잰다
    wrapModelCall: async (request, handler) => {
      const started = Date.now();
      const response = await handler(request);
      console.log(`  [model] ${Date.now() - started}ms`);
      return response;
    },
    // 도구 호출을 감싸서 이름과 인자를 남긴다
    wrapToolCall: async (request, handler) => {
      const started = Date.now();
      console.log(`  [tool:start] ${request.toolCall.name} args=${JSON.stringify(request.toolCall.args)}`);
      const response = await handler(request);
      console.log(`  [tool:end]   ${request.toolCall.name} (${Date.now() - started}ms)`);
      return response;
    },
  });

  const model = fakeModel()
    .respondWithTools([{ name: "get_weather", args: { city: "서울" }, id: "call_1" }])
    .respond(new AIMessage("서울은 맑고 23도입니다."));

  const agent = createAgent({ model, tools, middleware: [loggingMiddleware] });
  await agent.invoke({ messages: [new HumanMessage("서울 날씨?")] });
}

/* ===== [19-5] 에이전트 테스트 ===== */

// 아주 작은 테스트 러너. 실제로는 vitest 를 씁니다(본문 19-5 참고).
let passed = 0;
let failed = 0;
function check(label: string, cond: boolean) {
  if (cond) {
    passed++;
    console.log(`  ✓ ${label}`);
  } else {
    failed++;
    console.log(`  ✗ ${label}`);
  }
}

// (a) 도구 단위 테스트 — 모델이 전혀 필요 없습니다. 빠르고 결정적입니다.
{
  console.log("\n===== [19-5a] 도구 단위 테스트 (모델 없음) =====");

  check("서울 날씨 조회", (await getWeather.invoke({ city: "서울" })) === "서울: 맑음, 23도");
  check("없는 도시는 '정보 없음'", (await getWeather.invoke({ city: "런던" })) === "런던: 날씨 정보 없음");
  check("인구는 천단위 콤마", (await getPopulation.invoke({ city: "부산" })) === "부산: 3,300,000명");
}

// (b) 에이전트 테스트 — 모델을 fakeModel 로 갈아끼웁니다.
{
  console.log("\n===== [19-5b] fakeModel 로 에이전트 테스트 =====");

  const model = fakeModel()
    .respondWithTools([{ name: "get_weather", args: { city: "서울" }, id: "call_1" }])
    .respond(new AIMessage("서울은 맑고 23도입니다."));

  const agent = createAgent({ model, tools });
  const result = await agent.invoke({ messages: [new HumanMessage("서울 날씨?")] });

  check("메시지 4개 (human → ai → tool → ai)", result.messages.length === 4);
  check("도구가 실제로 실행되어 ToolMessage 가 생김", result.messages[2].getType() === "tool");
  check("ToolMessage 내용이 도구의 실제 반환값", result.messages[2].text === "서울: 맑음, 23도");
  check("최종 답은 AI 메시지", result.messages.at(-1)?.getType() === "ai");
  check("모델은 2번 호출됨", model.callCount === 2);

  // ⚠️ respondWithTools 의 content 는 입력 메시지를 그대로 되돌려줍니다.
  // 즉 "서울 날씨?" 가 AI 메시지 content 로 들어옵니다. 여기에 단언하지 마세요.
  console.log("  (참고) tool_calls 를 담은 AI 메시지의 content =", JSON.stringify(result.messages[1].text));
}

// (c) fakeModel 로 에러 경로 테스트 — 실제 모델로는 재현이 거의 불가능한 상황.
{
  console.log("\n===== [19-5c] 에러 경로 테스트 =====");

  const failing = fakeModel().alwaysThrow(new Error("service unavailable"));
  const agent = createAgent({ model: failing, tools });
  let caught = "";
  try {
    await agent.invoke({ messages: [new HumanMessage("서울 날씨?")] });
  } catch (e) {
    caught = (e as Error).message;
  }
  check("모델 장애가 위로 전파된다", caught === "service unavailable");

  // 큐가 비면 fakeModel 은 던집니다. 메시지는 결정적입니다.
  const oneShot = fakeModel().respond(new AIMessage("한 번만"));
  await oneShot.invoke([new HumanMessage("a")]);
  let queueErr = "";
  try {
    await oneShot.invoke([new HumanMessage("b")]);
  } catch (e) {
    queueErr = (e as Error).message;
  }
  console.log("  큐 소진 에러:", queueErr);
  check("큐 소진 시 명확한 에러", queueErr.startsWith("FakeModel: no response queued"));
}

/* ===== [19-6] 평가 — 데이터셋 + 평가자 ===== */

// 평가의 최소 구성: (1) 데이터셋 (2) 실행 함수 (3) 평가자 (4) 집계
type Example = {
  id: string;
  input: string;
  referenceOutput: string; // 기대 답변
  referenceTools: string[]; // 기대 도구 호출 순서 (19-7 에서 사용)
};

const dataset: Example[] = [
  { id: "ex-1", input: "서울 날씨 알려줘", referenceOutput: "맑음, 23도", referenceTools: ["get_weather"] },
  { id: "ex-2", input: "부산 인구는?", referenceOutput: "3,300,000명", referenceTools: ["get_population"] },
  {
    id: "ex-3",
    input: "제주 날씨랑 인구 둘 다",
    referenceOutput: "비, 21도 / 670,000명",
    referenceTools: ["get_weather", "get_population"],
  },
];

// 평가자 (1): 결정적 매칭 — 싸고 빠르고 안 틀립니다. 쓸 수 있으면 이걸 쓰세요.
function containsEvaluator(outputs: { answer: string }, referenceOutput: string) {
  const keys = referenceOutput.split(" / ");
  const hit = keys.filter((k) => outputs.answer.includes(k)).length;
  return { key: "contains", score: hit / keys.length };
}

// 평가자 (2): LLM-as-judge — 여기서는 실제 모델 대신 fakeModel 로 시늉만 냅니다.
// 이론은 /ai/9990-LLMJudge 참고. 여기서는 "어떻게 실행하는가" 만 봅니다.
async function llmJudgeEvaluator(outputs: { answer: string }, referenceOutput: string) {
  // 실전에서는 아래 model 을 "anthropic:claude-sonnet-4-6" 등으로 바꾸고
  // withStructuredOutput 으로 점수를 강제합니다.
  const judge = fakeModel().structuredResponse({
    score: outputs.answer.includes(referenceOutput.split(" / ")[0]) ? 1 : 0,
    reasoning: "기대 답의 핵심 키워드 포함 여부로 판정",
  });
  // 참고: fakeModel 의 withStructuredOutput 은 { raw, parsed } 형태까지 포함한
  // 유니온 타입을 반환하도록 선언돼 있어서, 여기서는 결과 타입을 명시해 줍니다.
  // 실제 모델(ChatAnthropic 등)에서는 이 단언 없이 바로 좁혀집니다.
  const judged = (await judge
    .withStructuredOutput(z.object({ score: z.number(), reasoning: z.string() }))
    .invoke(`기대: ${referenceOutput}\n실제: ${outputs.answer}\n0~1 로 채점하라.`)) as {
    score: number;
    reasoning: string;
  };
  return { key: "llm_judge", score: judged.score, comment: judged.reasoning };
}

// 스크립트로 시연하려면 각 예제의 응답을 미리 정해야 합니다(fakeModel).
const scripted: Record<string, () => ReturnType<typeof fakeModel>> = {
  "ex-1": () =>
    fakeModel()
      .respondWithTools([{ name: "get_weather", args: { city: "서울" }, id: "c1" }])
      .respond(new AIMessage("서울은 맑음, 23도 입니다.")),
  "ex-2": () =>
    fakeModel()
      .respondWithTools([{ name: "get_population", args: { city: "부산" }, id: "c1" }])
      .respond(new AIMessage("부산 인구는 3,300,000명 입니다.")),
  // ex-3 은 일부러 "운 좋게 맞은" 케이스로 만듭니다 — 도구를 하나만 부르고도 답은 맞습니다.
  "ex-3": () =>
    fakeModel()
      .respondWithTools([{ name: "get_weather", args: { city: "제주" }, id: "c1" }])
      .respond(new AIMessage("제주는 비, 21도 이고 인구는 670,000명 입니다.")),
};

async function runAgentOn(example: Example) {
  const model = scripted[example.id]();
  const agent = createAgent({ model, tools });
  const result = await agent.invoke({ messages: [new HumanMessage(example.input)] });
  return { answer: result.messages.at(-1)?.text ?? "", messages: result.messages };
}

{
  console.log("\n===== [19-6] 평가 실행 =====");
  for (const ex of dataset) {
    const out = await runAgentOn(ex);
    const c = containsEvaluator(out, ex.referenceOutput);
    const j = await llmJudgeEvaluator(out, ex.referenceOutput);
    console.log(`  ${ex.id}: contains=${c.score.toFixed(2)} llm_judge=${j.score.toFixed(2)}`);
  }
  console.log("  → ex-3 도 최종 답 기준으로는 만점입니다. 다음 절에서 이게 왜 위험한지 봅니다.");
}

/* ===== [19-7] 궤적(trajectory) 평가 ===== */

// 궤적 = 에이전트가 부른 도구의 이름과 순서. messages 배열에서 뽑아냅니다.
function extractTrajectory(messages: BaseMessage[]): string[] {
  return messages
    .filter((m): m is AIMessage => m.getType() === "ai")
    .flatMap((m) => (m.tool_calls ?? []).map((tc) => tc.name));
}

// 궤적 평가자 — agentevals 의 trajectoryMatchMode 를 직접 구현해 본 것입니다.
type MatchMode = "strict" | "unordered" | "superset" | "subset";
function trajectoryMatch(actual: string[], reference: string[], mode: MatchMode): boolean {
  const sortedA = [...actual].sort();
  const sortedR = [...reference].sort();
  switch (mode) {
    case "strict": // 같은 도구를 같은 순서로
      return actual.length === reference.length && actual.every((t, i) => t === reference[i]);
    case "unordered": // 같은 도구 집합, 순서 무관
      return sortedA.length === sortedR.length && sortedA.every((t, i) => t === sortedR[i]);
    case "superset": // 기대한 건 다 불렀고, 추가로 더 불러도 OK
      return reference.every((t) => actual.includes(t));
    case "subset": // 기대 범위를 벗어난 도구는 안 불렀다
      return actual.every((t) => reference.includes(t));
  }
}

{
  console.log("\n===== [19-7] 궤적 평가 =====");
  for (const ex of dataset) {
    const out = await runAgentOn(ex);
    const traj = extractTrajectory(out.messages);
    const strict = trajectoryMatch(traj, ex.referenceTools, "strict");
    const answerOk = containsEvaluator(out, ex.referenceOutput).score === 1;
    console.log(
      `  ${ex.id}: 궤적=[${traj.join(" → ")}] 기대=[${ex.referenceTools.join(" → ")}] ` +
        `strict=${strict ? "PASS" : "FAIL"} 최종답=${answerOk ? "PASS" : "FAIL"}`
    );
  }
  console.log("  → ex-3: 최종답 PASS / 궤적 FAIL. get_population 을 안 부르고 인구를 '지어냈습니다'.");
  console.log("    최종 답만 봤다면 환각을 만점으로 통과시켰을 겁니다.");
}

/* ===== [19-8] 회귀 방지 — CI 게이트 ===== */

// CI 는 "점수를 보여주는 것" 이 아니라 "기준 미달이면 빌드를 깨는 것" 입니다.
{
  console.log("\n===== [19-8] 회귀 게이트 =====");

  const THRESHOLD = 0.9; // 궤적 정확도 최소치
  let trajPass = 0;
  for (const ex of dataset) {
    const out = await runAgentOn(ex);
    if (trajectoryMatch(extractTrajectory(out.messages), ex.referenceTools, "strict")) trajPass++;
  }
  const score = trajPass / dataset.length;
  console.log(`  궤적 정확도: ${(score * 100).toFixed(0)}% (기준 ${THRESHOLD * 100}%)`);
  if (score < THRESHOLD) {
    console.log(`  → CI 라면 여기서 process.exit(1). 기준 미달이므로 머지 차단.`);
  } else {
    console.log(`  → 통과.`);
  }
}

/* ===== [19-9] LangGraph Studio ===== */

// Studio 는 코드가 아니라 설정입니다. 아래 내용을 project/langgraph.json 에 두고
//   npx @langchain/langgraph-cli dev
// 를 실행하면 됩니다. 본문 19-9 참고.
{
  console.log("\n===== [19-9] Studio =====");
  console.log(
    JSON.stringify(
      {
        dependencies: ["."],
        graphs: { agent: "./src/agent.ts:agent" },
        env: ".env",
      },
      null,
      2
    )
  );
  console.log("→ npx @langchain/langgraph-cli dev  후 https://smith.langchain.com/studio/?baseUrl=http://127.0.0.1:2024");
}

/* ===== [19-10] 종합 ===== */

{
  console.log("\n===== [19-10] 종합 =====");
  console.log(`단위 테스트: ${passed} 통과 / ${failed} 실패`);
  console.log(`
관측·테스트·평가 3층 요약
  1층 관측(observability): 무슨 일이 있었나?      → LangSmith 트레이스 / ConsoleCallbackHandler / streamMode debug
  2층 테스트(test):        코드가 안 깨졌나?      → 도구 단위 테스트 + fakeModel (빠름, 결정적, 무료)
  3층 평가(eval):          품질이 안 떨어졌나?    → 데이터셋 + 궤적 평가자 + LLM judge (느림, 비쌈, CI 게이트)
`);
}

/**
 * Step 19 — 관측·테스트·평가 / 연습문제
 * 실행: npx tsx docs/reference/langchain/step-19-observability-eval/exercise.ts
 *
 * 각 [문제 N] 아래를 채우세요. 정답은 solution.ts 에 있습니다.
 * 이 파일은 API 키 없이 돌아가야 합니다 — 실제 모델을 부르지 마세요.
 */
import "dotenv/config";
import {
  createAgent,
  createMiddleware,
  fakeModel,
  tool,
  AIMessage,
  HumanMessage,
  type BaseMessage,
} from "langchain";
import * as z from "zod";

/* ===== 공통 도구 (practice.ts 와 동일) ===== */

const getWeather = tool(
  ({ city }) => {
    const table: Record<string, string> = { 서울: "맑음, 23도", 부산: "흐림, 26도", 제주: "비, 21도" };
    const found = table[city];
    if (!found) return `${city}: 날씨 정보 없음`;
    return `${city}: ${found}`;
  },
  {
    name: "get_weather",
    description: "도시의 현재 날씨를 조회합니다.",
    schema: z.object({ city: z.string() }),
  }
);

const getPopulation = tool(
  ({ city }) => {
    const table: Record<string, number> = { 서울: 9_400_000, 부산: 3_300_000, 제주: 670_000 };
    const found = table[city];
    if (found === undefined) return `${city}: 인구 정보 없음`;
    return `${city}: ${found.toLocaleString("ko-KR")}명`;
  },
  {
    name: "get_population",
    description: "도시의 인구를 조회합니다.",
    schema: z.object({ city: z.string() }),
  }
);

const tools = [getWeather, getPopulation];

/* ===================================================================
 * [문제 1] 도구 단위 테스트
 *
 * getWeather / getPopulation 을 모델 없이 직접 호출해서 아래 3가지를 검증하세요.
 *   (1) getWeather({ city: "제주" }) === "제주: 비, 21도"
 *   (2) 표에 없는 도시("런던")는 "런던: 날씨 정보 없음" 을 반환한다
 *   (3) getPopulation({ city: "서울" }) 에 천단위 콤마가 들어있다
 *
 * 통과/실패를 console.log 로 출력하세요.
 * 힌트: await getWeather.invoke({ city: "제주" })
 * =================================================================== */
console.log("\n===== [문제 1] 도구 단위 테스트 =====");
// 여기에 작성

/* ===================================================================
 * [문제 2] fakeModel 로 2단계 도구 호출 에이전트 테스트
 *
 * "제주 날씨랑 인구 알려줘" 에 대해 에이전트가
 *   get_weather → get_population → 최종 답
 * 순서로 동작하도록 fakeModel 을 스크립팅하고 createAgent 로 실행하세요.
 *
 * 그리고 아래를 검증하세요.
 *   (1) result.messages 의 길이가 6 이다 (human, ai, tool, ai, tool, ai)
 *   (2) ToolMessage 가 2개다
 *   (3) model.callCount === 3
 *
 * 힌트: fakeModel().respondWithTools([...]).respondWithTools([...]).respond(new AIMessage("..."))
 * 힌트: 도구 호출 1번당 모델 호출이 1번씩 더 필요합니다.
 * =================================================================== */
console.log("\n===== [문제 2] 2단계 도구 호출 =====");
// 여기에 작성

/* ===================================================================
 * [문제 3] 궤적 추출 함수
 *
 * messages 배열에서 "호출된 도구 이름을 순서대로" 뽑는 extractTrajectory 를 구현하세요.
 *
 *   function extractTrajectory(messages: BaseMessage[]): string[]
 *
 * 문제 2 의 결과에 적용해서 ["get_weather", "get_population"] 이 나오는지 확인하세요.
 *
 * 힌트: AI 메시지만 고르고(m.getType() === "ai"), 각 메시지의 tool_calls 를 flatMap 하세요.
 * 힌트: tool_calls 는 없을 수 있습니다 (최종 답 메시지).
 * =================================================================== */
console.log("\n===== [문제 3] 궤적 추출 =====");
// 여기에 작성

/* ===================================================================
 * [문제 4] 궤적 평가자 — unordered 모드
 *
 * 아래 두 궤적은 "순서만 다르고 내용은 같습니다".
 *   actual    = ["get_population", "get_weather"]
 *   reference = ["get_weather", "get_population"]
 *
 * strict 모드로는 FAIL, unordered 모드로는 PASS 가 나오는
 * trajectoryMatch(actual, reference, mode) 를 구현하고 둘 다 출력하세요.
 *
 * 힌트: unordered 는 정렬 후 비교. 길이도 함께 봐야 합니다.
 * 힌트: 실무에서는 agentevals 의 createTrajectoryMatchEvaluator({ trajectoryMatchMode })
 *       를 쓰면 되지만, 원리를 알기 위해 직접 만들어 봅니다.
 * =================================================================== */
console.log("\n===== [문제 4] unordered 궤적 매칭 =====");
// 여기에 작성

/* ===================================================================
 * [문제 5] "운 좋게 맞은" 답 잡아내기
 *
 * 아래 에이전트는 get_weather 만 부르고서 인구까지 "지어내서" 답합니다.
 *   fakeModel()
 *     .respondWithTools([{ name: "get_weather", args: { city: "부산" }, id: "c1" }])
 *     .respond(new AIMessage("부산은 흐림, 26도 이고 인구는 3,300,000명 입니다."))
 *
 * 이 에이전트를 실행하고 두 가지 평가를 모두 돌려서, 결과가 갈리는 것을 보이세요.
 *   (1) 최종답 평가: 답에 "흐림, 26도" 와 "3,300,000명" 이 둘 다 있는가? → PASS 가 나올 것
 *   (2) 궤적 평가: 기대 궤적 ["get_weather", "get_population"] 과 strict 매칭 → FAIL 이 나올 것
 *
 * 그리고 "왜 (1) 만으로는 위험한가" 를 console.log 로 한 줄 설명하세요.
 * =================================================================== */
console.log("\n===== [문제 5] 환각을 통과시키는 평가 =====");
// 여기에 작성

/* ===================================================================
 * [문제 6] 도구 호출을 기록하는 미들웨어
 *
 * createMiddleware 로 auditMiddleware 를 만드세요.
 *   - wrapToolCall 에서 호출된 도구의 이름과 인자를 배열 auditLog 에 push
 *   - 그 미들웨어를 붙인 에이전트를 fakeModel 로 실행
 *   - 실행 후 auditLog 를 출력
 *
 * 기대: [{ name: "get_weather", args: { city: "서울" } }]
 *
 * 힌트: wrapToolCall: async (request, handler) => { ...; return handler(request); }
 * 힌트: request.toolCall.name / request.toolCall.args
 * =================================================================== */
console.log("\n===== [문제 6] 감사 로그 미들웨어 =====");
// 여기에 작성

/* ===================================================================
 * [문제 7] 회귀 게이트
 *
 * 아래 3개짜리 데이터셋으로 궤적 정확도를 계산하고,
 * 기준(0.9) 미달이면 "REGRESSION" 을 출력하는 게이트를 만드세요.
 * (실제 CI 라면 process.exit(1) 자리입니다 — 여기서는 출력만 하세요.)
 *
 * 각 예제의 에이전트 응답은 아래 scripted 를 그대로 쓰세요.
 * 정확도는 몇 %가 나오고, 어느 예제가 깨지나요? 주석으로 답을 적으세요.
 * =================================================================== */
console.log("\n===== [문제 7] 회귀 게이트 =====");

const dataset = [
  { id: "ex-1", input: "서울 날씨?", referenceTools: ["get_weather"] },
  { id: "ex-2", input: "부산 인구?", referenceTools: ["get_population"] },
  { id: "ex-3", input: "제주 날씨랑 인구", referenceTools: ["get_weather", "get_population"] },
];

const scripted: Record<string, () => ReturnType<typeof fakeModel>> = {
  "ex-1": () =>
    fakeModel()
      .respondWithTools([{ name: "get_weather", args: { city: "서울" }, id: "c1" }])
      .respond(new AIMessage("서울은 맑음, 23도 입니다.")),
  "ex-2": () =>
    fakeModel()
      .respondWithTools([{ name: "get_population", args: { city: "부산" }, id: "c1" }])
      .respond(new AIMessage("부산 인구는 3,300,000명 입니다.")),
  "ex-3": () =>
    fakeModel()
      .respondWithTools([{ name: "get_weather", args: { city: "제주" }, id: "c1" }])
      .respond(new AIMessage("제주는 비, 21도 이고 인구는 670,000명 입니다.")),
};

// 여기에 작성
// → 정확도는 몇 %인가요? (여기에 답)
// → 어느 예제가 왜 깨지나요? (여기에 답)

/* ===================================================================
 * [문제 8] 트레이스 라벨 설계 (코드 + 서술)
 *
 * "특정 사용자가 어제 겪은 오류를 다시 찾아야 한다" 는 상황을 가정합니다.
 * 에이전트를 실행하면서 runName / tags / metadata 를 적절히 붙이세요.
 *
 * 조건:
 *   - runName 으로 이 플로우를 식별할 수 있어야 한다
 *   - tags 로 환경(production)과 에이전트 버전을 필터할 수 있어야 한다
 *   - metadata 로 특정 사용자와 세션을 되짚을 수 있어야 한다
 *
 * 그리고 아래 질문에 주석으로 답하세요.
 *   (a) 사용자 이메일을 metadata 에 넣어도 될까요? 왜 그런가요?
 *   (b) tags 와 metadata 는 어떻게 나눠 쓰는 게 좋을까요?
 * =================================================================== */
console.log("\n===== [문제 8] 트레이스 라벨 설계 =====");
// 여기에 작성
// (a) (여기에 답)
// (b) (여기에 답)

/**
 * Step 19 — 관측·테스트·평가 / 정답과 해설
 * 실행: npx tsx docs/reference/langchain/step-19-observability-eval/solution.ts
 *
 * exercise.ts 를 스스로 풀어본 뒤에 열어보세요.
 */
import "dotenv/config";
import {
  createAgent,
  createMiddleware,
  fakeModel,
  tool,
  AIMessage,
  HumanMessage,
  type BaseMessage,
} from "langchain";
import * as z from "zod";

/* ===== 공통 도구 ===== */

const getWeather = tool(
  ({ city }) => {
    const table: Record<string, string> = { 서울: "맑음, 23도", 부산: "흐림, 26도", 제주: "비, 21도" };
    const found = table[city];
    if (!found) return `${city}: 날씨 정보 없음`;
    return `${city}: ${found}`;
  },
  {
    name: "get_weather",
    description: "도시의 현재 날씨를 조회합니다.",
    schema: z.object({ city: z.string() }),
  }
);

const getPopulation = tool(
  ({ city }) => {
    const table: Record<string, number> = { 서울: 9_400_000, 부산: 3_300_000, 제주: 670_000 };
    const found = table[city];
    if (found === undefined) return `${city}: 인구 정보 없음`;
    return `${city}: ${found.toLocaleString("ko-KR")}명`;
  },
  {
    name: "get_population",
    description: "도시의 인구를 조회합니다.",
    schema: z.object({ city: z.string() }),
  }
);

const tools = [getWeather, getPopulation];

/* 간단한 단언 헬퍼 */
function check(label: string, cond: boolean) {
  console.log(`  ${cond ? "✓" : "✗"} ${label}`);
}

/* ===================================================================
 * [정답 1] 도구 단위 테스트
 *
 * 해설: 도구는 순수 함수입니다 — 모델도, 네트워크도, API 키도 필요 없습니다.
 * 에이전트 테스트의 90%는 사실 여기서 끝나야 합니다. 도구가 틀리면
 * 모델이 아무리 똑똑해도 답이 틀리는데, 이건 모델 없이 1ms 만에 잡힙니다.
 * =================================================================== */
console.log("\n===== [정답 1] 도구 단위 테스트 =====");
{
  check("제주 날씨", (await getWeather.invoke({ city: "제주" })) === "제주: 비, 21도");
  check("없는 도시 폴백", (await getWeather.invoke({ city: "런던" })) === "런던: 날씨 정보 없음");
  check("천단위 콤마", (await getPopulation.invoke({ city: "서울" })).includes("9,400,000"));

  // 함정: 도구의 "정보 없음" 경로를 테스트 안 하면, 모델이 그 문자열을 받고
  // 어떻게 반응하는지도 영영 모릅니다. 폴백 경로도 반드시 테스트하세요.
}

/* ===================================================================
 * [정답 2] fakeModel 로 2단계 도구 호출 에이전트 테스트
 *
 * 해설: 핵심은 "도구 호출 1번당 모델 호출이 1번 더 필요하다" 입니다.
 * 도구를 2번 부르는 궤적은 모델 응답이 3개 필요합니다.
 *   모델#1 → get_weather 호출 결정
 *   모델#2 → (도구 결과 보고) get_population 호출 결정
 *   모델#3 → 최종 답
 * 큐에 2개만 넣으면 "FakeModel: no response queued for invocation 2" 로 터집니다.
 * =================================================================== */
console.log("\n===== [정답 2] 2단계 도구 호출 =====");
{
  const model = fakeModel()
    .respondWithTools([{ name: "get_weather", args: { city: "제주" }, id: "c1" }])
    .respondWithTools([{ name: "get_population", args: { city: "제주" }, id: "c2" }])
    .respond(new AIMessage("제주는 비, 21도 이고 인구는 670,000명 입니다."));

  const agent = createAgent({ model, tools });
  const result = await agent.invoke({ messages: [new HumanMessage("제주 날씨랑 인구 알려줘")] });

  check("메시지 6개", result.messages.length === 6);
  check("ToolMessage 2개", result.messages.filter((m) => m.getType() === "tool").length === 2);
  check("모델 3번 호출", model.callCount === 3);

  console.log("  궤적:", result.messages.map((m) => m.getType()).join(" → "));
}

/* ===================================================================
 * [정답 3] 궤적 추출 함수
 *
 * 해설: 궤적은 새로 만드는 게 아니라 messages 배열에 이미 들어 있습니다.
 * AI 메시지의 tool_calls 만 순서대로 모으면 됩니다.
 * 최종 답 AI 메시지에는 tool_calls 가 없으므로 `?? []` 로 방어해야 합니다.
 * =================================================================== */
console.log("\n===== [정답 3] 궤적 추출 =====");

function extractTrajectory(messages: BaseMessage[]): string[] {
  return messages
    .filter((m): m is AIMessage => m.getType() === "ai")
    .flatMap((m) => (m.tool_calls ?? []).map((tc) => tc.name));
}

{
  const model = fakeModel()
    .respondWithTools([{ name: "get_weather", args: { city: "제주" }, id: "c1" }])
    .respondWithTools([{ name: "get_population", args: { city: "제주" }, id: "c2" }])
    .respond(new AIMessage("제주는 비, 21도 이고 인구는 670,000명 입니다."));

  const agent = createAgent({ model, tools });
  const result = await agent.invoke({ messages: [new HumanMessage("제주 날씨랑 인구 알려줘")] });

  const traj = extractTrajectory(result.messages);
  console.log("  궤적:", traj);
  check("['get_weather','get_population']", traj.join(",") === "get_weather,get_population");
}

/* ===================================================================
 * [정답 4] 궤적 평가자 — unordered 모드
 *
 * 해설: 어떤 모드를 쓸지가 곧 "무엇을 요구사항으로 볼 것인가" 입니다.
 *   strict    — 순서까지 계약이다 (예: 권한 조회 후에만 결제)
 *   unordered — 순서는 모델 자유, 필요한 정보는 다 가져와야 한다
 *   superset  — 최소한 이것들은 불러라 (추가 호출 허용)
 *   subset    — 이 범위 밖의 도구는 부르지 마라 (안전 경계)
 * 대부분의 경우 unordered 가 맞습니다. strict 를 남발하면 모델이
 * 똑같이 정답인 다른 순서로 풀었을 때 테스트가 거짓으로 깨집니다.
 * =================================================================== */
console.log("\n===== [정답 4] unordered 궤적 매칭 =====");

type MatchMode = "strict" | "unordered" | "superset" | "subset";
function trajectoryMatch(actual: string[], reference: string[], mode: MatchMode): boolean {
  const sortedA = [...actual].sort();
  const sortedR = [...reference].sort();
  switch (mode) {
    case "strict":
      return actual.length === reference.length && actual.every((t, i) => t === reference[i]);
    case "unordered":
      // 함정: 길이 비교를 빼먹으면 ["get_weather"] 가
      // ["get_weather","get_weather"] 와 같다고 나옵니다.
      return sortedA.length === sortedR.length && sortedA.every((t, i) => t === sortedR[i]);
    case "superset":
      return reference.every((t) => actual.includes(t));
    case "subset":
      return actual.every((t) => reference.includes(t));
  }
}

{
  const actual = ["get_population", "get_weather"];
  const reference = ["get_weather", "get_population"];
  console.log("  strict   :", trajectoryMatch(actual, reference, "strict") ? "PASS" : "FAIL"); // FAIL
  console.log("  unordered:", trajectoryMatch(actual, reference, "unordered") ? "PASS" : "FAIL"); // PASS
  console.log("  → 같은 일을 했는데 strict 는 FAIL 입니다. 순서가 진짜 요구사항일 때만 strict 를 쓰세요.");
}

/* ===================================================================
 * [정답 5] "운 좋게 맞은" 답 잡아내기 — 이 스텝의 핵심
 *
 * 해설: 이게 최종답 평가만 돌리면 안 되는 이유입니다.
 * 에이전트는 get_population 을 부르지 않았습니다. 인구 숫자는 도구에서
 * 온 게 아니라 모델이 **기억에서 지어낸 것**입니다. 이번엔 우연히 맞았지만
 * 데이터가 바뀌면 즉시 틀립니다. 최종답 평가는 이걸 만점으로 통과시킵니다.
 * 궤적 평가만이 "출처 없이 답했다" 를 잡아냅니다.
 * =================================================================== */
console.log("\n===== [정답 5] 환각을 통과시키는 평가 =====");
{
  const model = fakeModel()
    .respondWithTools([{ name: "get_weather", args: { city: "부산" }, id: "c1" }])
    .respond(new AIMessage("부산은 흐림, 26도 이고 인구는 3,300,000명 입니다."));

  const agent = createAgent({ model, tools });
  const result = await agent.invoke({ messages: [new HumanMessage("부산 날씨랑 인구 알려줘")] });
  const answer = result.messages.at(-1)?.text ?? "";

  // (1) 최종답 평가
  const answerOk = answer.includes("흐림, 26도") && answer.includes("3,300,000명");
  console.log(`  최종답 평가: ${answerOk ? "PASS" : "FAIL"} — "${answer}"`);

  // (2) 궤적 평가
  const traj = extractTrajectory(result.messages);
  const trajOk = trajectoryMatch(traj, ["get_weather", "get_population"], "strict");
  console.log(`  궤적 평가  : ${trajOk ? "PASS" : "FAIL"} — 실제 궤적 [${traj.join(", ")}]`);

  console.log(
    "  → 왜 위험한가: 인구 숫자가 get_population 이 아니라 모델의 기억에서 나왔습니다.\n" +
      "    지금은 우연히 맞았지만 출처가 없으므로 데이터가 바뀌면 조용히 틀립니다.\n" +
      "    최종답만 보면 이 환각이 만점으로 통과합니다."
  );
}

/* ===================================================================
 * [정답 6] 도구 호출을 기록하는 미들웨어
 *
 * 해설: wrapToolCall 은 반드시 handler(request) 의 결과를 **반환**해야 합니다.
 * 로그만 찍고 return 을 빼먹으면 도구 결과가 사라져 대화가 조용히 깨집니다.
 * 이 미들웨어는 감사(audit) 로그뿐 아니라 "모델이 부르면 안 될 도구를 불렀는가"
 * 를 잡는 런타임 가드로도 확장할 수 있습니다.
 * =================================================================== */
console.log("\n===== [정답 6] 감사 로그 미들웨어 =====");
{
  const auditLog: Array<{ name: string; args: Record<string, unknown> }> = [];

  const auditMiddleware = createMiddleware({
    name: "AuditMiddleware",
    wrapToolCall: async (request, handler) => {
      auditLog.push({ name: request.toolCall.name, args: request.toolCall.args });
      return handler(request); // ← 이 return 을 빼면 도구 결과가 사라집니다
    },
  });

  const model = fakeModel()
    .respondWithTools([{ name: "get_weather", args: { city: "서울" }, id: "c1" }])
    .respond(new AIMessage("서울은 맑고 23도입니다."));

  const agent = createAgent({ model, tools, middleware: [auditMiddleware] });
  await agent.invoke({ messages: [new HumanMessage("서울 날씨?")] });

  console.log("  auditLog:", JSON.stringify(auditLog));
  check("도구 1건 기록", auditLog.length === 1 && auditLog[0].name === "get_weather");
}

/* ===================================================================
 * [정답 7] 회귀 게이트
 *
 * 해설: 정확도는 67% (2/3) 이고 ex-3 이 깨집니다.
 * ex-3 은 get_weather 만 부르고 get_population 을 건너뛰었습니다.
 * 최종 답은 그럴듯하지만 궤적이 기대와 다릅니다 — [정답 5] 와 같은 환각입니다.
 *
 * CI 의 요점은 점수를 "보여주는" 게 아니라 기준 미달이면 **빌드를 깨는** 것입니다.
 * 대시보드는 아무도 안 봅니다. 빨간 X 는 봅니다.
 * =================================================================== */
console.log("\n===== [정답 7] 회귀 게이트 =====");

const dataset = [
  { id: "ex-1", input: "서울 날씨?", referenceTools: ["get_weather"] },
  { id: "ex-2", input: "부산 인구?", referenceTools: ["get_population"] },
  { id: "ex-3", input: "제주 날씨랑 인구", referenceTools: ["get_weather", "get_population"] },
];

const scripted: Record<string, () => ReturnType<typeof fakeModel>> = {
  "ex-1": () =>
    fakeModel()
      .respondWithTools([{ name: "get_weather", args: { city: "서울" }, id: "c1" }])
      .respond(new AIMessage("서울은 맑음, 23도 입니다.")),
  "ex-2": () =>
    fakeModel()
      .respondWithTools([{ name: "get_population", args: { city: "부산" }, id: "c1" }])
      .respond(new AIMessage("부산 인구는 3,300,000명 입니다.")),
  "ex-3": () =>
    fakeModel()
      .respondWithTools([{ name: "get_weather", args: { city: "제주" }, id: "c1" }])
      .respond(new AIMessage("제주는 비, 21도 이고 인구는 670,000명 입니다.")),
};

{
  const THRESHOLD = 0.9;
  const failures: string[] = [];

  for (const ex of dataset) {
    const agent = createAgent({ model: scripted[ex.id](), tools });
    const result = await agent.invoke({ messages: [new HumanMessage(ex.input)] });
    const traj = extractTrajectory(result.messages);
    const ok = trajectoryMatch(traj, ex.referenceTools, "unordered");
    if (!ok) failures.push(`${ex.id}: 기대 [${ex.referenceTools.join(", ")}] / 실제 [${traj.join(", ")}]`);
  }

  const score = (dataset.length - failures.length) / dataset.length;
  console.log(`  궤적 정확도: ${(score * 100).toFixed(0)}% (기준 ${THRESHOLD * 100}%)`);
  for (const f of failures) console.log(`    실패 — ${f}`);

  if (score < THRESHOLD) {
    console.log("  REGRESSION — 실제 CI 라면 여기서 process.exit(1) 로 머지를 막습니다.");
  } else {
    console.log("  통과 — 머지 가능.");
  }
}
// → 정확도: 67% (3개 중 2개 통과)
// → ex-3 이 깨집니다. get_population 을 부르지 않고 인구를 지어냈기 때문입니다.

/* ===================================================================
 * [정답 8] 트레이스 라벨 설계
 *
 * 해설:
 * (a) 넣으면 안 됩니다. LANGSMITH_TRACING=true 는 프롬프트·도구 인자·응답을
 *     통째로 외부(LangSmith 서버)로 보냅니다. metadata 도 예외가 아닙니다.
 *     이메일은 개인정보이므로 해시하거나 내부 ID 로 바꿔서 넣어야 합니다.
 *     본문 값 자체를 가려야 한다면 langsmith/anonymizer 의 createAnonymizer 를 쓰거나,
 *     애초에 piiMiddleware 로 마스킹한 뒤 트레이싱하세요.
 *
 * (b) tags 는 "값이 몇 개 안 되고 필터링할 것" (환경, 버전, 기능 플래그).
 *     metadata 는 "값이 무한하고 나중에 되짚을 것" (userId, sessionId, requestId).
 *     tags 에 userId 를 넣으면 태그가 수만 개로 불어나 필터가 쓸모없어집니다.
 * =================================================================== */
console.log("\n===== [정답 8] 트레이스 라벨 설계 =====");
{
  // 개인정보는 그대로 넣지 않고 내부 ID / 해시로 바꿉니다.
  const internalUserId = "u_8f3a91"; // 이메일 대신 내부 ID
  const model = fakeModel().respond(new AIMessage("네, 확인했습니다."));
  const agent = createAgent({ model, tools });

  await agent.invoke(
    { messages: [new HumanMessage("서울 날씨?")] },
    {
      runName: "weather-query", // 이 플로우의 식별자
      tags: ["production", "agent-v1.2"], // 카디널리티 낮음 → 필터용
      metadata: {
        userId: internalUserId, // 카디널리티 높음 → 되짚기용
        sessionId: "sess_20260717_001",
        requestId: "req_abc123",
      },
    }
  );

  console.log("  runName=weather-query tags=[production, agent-v1.2] metadata={userId, sessionId, requestId}");
  console.log("  (a) 이메일은 metadata 에 넣지 않습니다 — 트레이싱은 데이터를 외부로 내보냅니다.");
  console.log("  (b) tags = 저카디널리티 필터 / metadata = 고카디널리티 추적.");
}