#Step 06 — 서브에이전트

const files = Array.from({ length: 30 }, (_, i) => ({
  path: `/docs/note-${i + 1}.md`,
  body: `# 노트 ${i + 1}\n` + "이 문서에는 대략 400토큰 분량의 내용이 들어 있습니다. ".repeat(20),
}));

const 직접읽기_누적 = files.reduce((sum, f) => sum + f.body.length, 0);
const 서브에이전트_반환 = "30개 노트를 읽고 요약함: 핵심 주제는 A, B, C 세 가지.".length;

const middleware = createSubAgentMiddleware({
  defaultModel: MODEL,
  defaultTools: [],
  subagents: [
    { name: "researcher", description: "주제를 깊이 조사한다", systemPrompt: "너는 조사원이다." },
  ],
});

console.log(GENERAL_PURPOSE_SUBAGENT.name);
console.log(GENERAL_PURPOSE_SUBAGENT.systemPrompt);
console.log(DEFAULT_GENERAL_PURPOSE_DESCRIPTION);

const withGP = createSubAgentMiddleware({ defaultModel: MODEL, defaultTools: [], subagents: [] });
const withoutGP = createSubAgentMiddleware({
  defaultModel: MODEL,
  defaultTools: [],
  generalPurposeAgent: false,
  subagents: [{ name: "researcher", description: "조사 담당", systemPrompt: "너는 조사원이다." }],
});

const custom: SubAgent = {
  ...GENERAL_PURPOSE_SUBAGENT,
  name: "general-purpose",
  systemPrompt: "너는 만능 조수다. 항상 한국어로 보고한다.",
};

// (A) 최소 정의
const minimal: SubAgent = {
  name: "summarizer",
  description: "긴 글을 3줄로 요약한다",
  systemPrompt: "너는 요약가다. 항상 정확히 3줄로 요약하라.",
};

// (B) 모든 필드를 쓴 정의
const full: SubAgent = {
  name: "researcher",
  description:
    "웹에서 특정 주제를 조사한다. 주제 하나당 하나씩 부를 것. " +
    "출처 URL 과 함께 조사 결과를 반환한다.",
  systemPrompt:
    "너는 조사원이다. web_search 로 자료를 찾고, 찾은 내용을 근거와 함께 정리하라. " +
    "추측하지 말고 찾은 것만 보고하라.",
  tools: [webSearch],   // 지정하면 부모 도구를 물려받지 않고 이것만 씁니다
  model: CHEAP_MODEL,   // 서브에이전트별 모델 차등 (6-6)
  responseFormat: z.object({
    summary: z.string().describe("조사 요약"),
    sources: z.array(z.string()).describe("출처 URL 목록"),
    confidence: z.number().min(0).max(1).describe("확신도"),
  }),
  permissions: [
    // 부모 권한을 "병합" 이 아니라 "완전 교체" 합니다 (Step 05 참고)
    { operations: ["read"], paths: ["/research/**"], mode: "allow" },
    { operations: ["read", "write"], paths: ["/**"], mode: "deny" },
  ],
};

const agent = createDeepAgent({ model: MODEL, backend: new StateBackend(), subagents: [minimal, full] });

const vague = createSubAgentMiddleware({
  defaultModel: MODEL, defaultTools: [], generalPurposeAgent: false,
  subagents: [
    { name: "helper1", description: "도와준다", systemPrompt: "너는 SQL 전문가다." },
    { name: "helper2", description: "처리한다", systemPrompt: "너는 이미지 편집 전문가다." },
  ],
});

const clear = createSubAgentMiddleware({
  defaultModel: MODEL, defaultTools: [], generalPurposeAgent: false,
  subagents: [
    {
      name: "sql-expert",
      description: "SQL 쿼리를 작성하고 최적화한다. 데이터베이스 스키마 질문에도 답한다.",
      systemPrompt: "너는 SQL 전문가다.",
    },
    {
      name: "image-editor",
      description: "이미지를 자르고 리사이즈하고 포맷을 변환한다.",
      systemPrompt: "너는 이미지 편집 전문가다.",
    },
  ],
});

const scout: SubAgent = {
  name: "scout",
  description: "자료를 넓게 훑어 후보를 추린다. 정확도보다 커버리지가 중요할 때 쓴다.",
  systemPrompt: "너는 정찰병이다. 빠르게 훑고 후보만 추려라.",
  model: CHEAP_MODEL,     // 싼 모델
};

const analyst: SubAgent = {
  name: "analyst",
  description: "추려진 자료를 깊이 분석하고 결론을 낸다. 정확도가 중요할 때 쓴다.",
  systemPrompt: "너는 분석가다. 근거를 들어 결론을 내라.",
  model: MODEL,           // 비싼 모델
};

// 부모(종합 담당)는 비싼 모델
const agent = createDeepAgent({ model: MODEL, backend: new StateBackend(), subagents: [scout, analyst] });

const scout: SubAgent = { name: "scout", description: "…", systemPrompt: "…", model: "openai:gpt-5.5" };

// (1) 동기 — 그냥 평범한 SubAgent 입니다.
const syncSub: SubAgent = {
  name: "researcher",
  description: "주제 하나를 조사한다. 여러 주제면 주제당 하나씩 병렬로 부를 것.",
  systemPrompt: "너는 조사원이다.",
};

// (2) 비동기 — graphId 로 이미 배포된 그래프를 가리킵니다.
const asyncSubs: AsyncSubAgent[] = [
  {
    name: "long-researcher",
    description: "몇 분씩 걸리는 장기 조사를 백그라운드로 수행한다.",
    graphId: "researcher",                              // 같은 배포 안 (ASGI)
  },
  {
    name: "remote-coder",
    description: "원격 배포된 코딩 에이전트.",
    graphId: "coder",
    url: "https://coder-deployment.langsmith.dev",      // 원격이면 url 추가
  },
];

import { createCodeInterpreterMiddleware } from "@langchain/quickjs";

const agent = createDeepAgent({
  model: MODEL,
  subagents: [{
    name: "reviewer",
    description: "코드를 보안 관점에서 리뷰하고 줄 번호와 심각도를 인용한다",
    systemPrompt: "너는 보안 중심 코드 리뷰어다.",
  }],
  middleware: [createCodeInterpreterMiddleware()],
});

// 모델이 eval 도구 안에서 작성하는 코드
const files = (await tools.glob({ pattern: "src/routes/**/*.ts" }))
  .split("\n").filter(Boolean);

const reviews = await Promise.all(
  files.map((file) =>
    task({
      description: `${file} 을 인증 취약점 관점에서 리뷰하라. 줄 번호를 인용할 것.`,
      subagentType: "reviewer",
      responseSchema: issuesSchema,
    }),
  ),
);
const issues = reviews.flatMap((r) => r.issues);

const result = await task({
  description: string;          // 자식에게 줄 프롬프트
  subagentType: string;         // 서브에이전트 이름 (camelCase 주의!)
  responseSchema?: JSONSchema;  // 있으면 결과가 이미 파싱된 객체로 옴
});

const writer: SubAgent = {
  name: "report-writer",
  description:
    "주제에 대한 상세 리포트를 작성해 지정된 파일 경로에 저장한다. " +
    "반환값으로는 저장한 경로와 한 줄 요약만 준다.",
  systemPrompt:
    "너는 리포트 작성자다. 요청받은 내용을 write_file 로 지정된 경로에 저장하라. " +
    "최종 답변에는 리포트 전문을 넣지 말고, 저장 경로와 한 줄 요약만 적어라.",
};

const agent = createDeepAgent({
  model: MODEL,
  backend: new StateBackend(),
  subagents: [writer],
  systemPrompt:
    "너는 편집자다. report-writer 서브에이전트에게 리포트 작성을 시키고, " +
    "결과 파일을 read_file 로 읽어 사용자에게 핵심만 전달하라.",
});

const researcher: SubAgent = {
  name: "researcher",
  description:
    "기술 하나를 조사해 특징과 트레이드오프를 정리한다. " +
    "여러 기술을 비교해야 하면 기술 하나당 하나씩 병렬로 호출할 것. " +      // ← 병렬 지시
    "조사 결과를 /research/<기술명>.md 에 저장하고 경로만 반환한다.",        // ← 파일 전달
  systemPrompt:
    "너는 기술 조사원이다. web_search 로 자료를 찾아 특징/장점/단점을 정리하고, " +
    "지정된 경로에 write_file 로 저장하라. 최종 답변은 '저장 경로 + 한 줄 요약' 만 적어라. " +
    "너는 부모의 대화를 볼 수 없으므로, 프롬프트에 주어진 정보만으로 판단하라.",  // ← 격리 인지
  tools: [webSearch],       // ← 도구를 좁게 (자식이 또 task 를 못 부르게)
  model: CHEAP_MODEL,       // ← 조사는 싼 모델
};

const agent = createDeepAgent({
  model: MODEL,             // ← 종합은 비싼 모델
  backend: new StateBackend(),
  subagents: [researcher],
  systemPrompt:
    "너는 기술 선임이다. 비교 요청을 받으면 researcher 서브에이전트를 " +
    "대상 기술마다 하나씩 '병렬로' 띄워라(한 메시지에 task 를 여러 번 호출). " +
    "각자가 저장한 파일을 읽어 최종 비교표를 만들어라.",
});

const result = await agent.invoke({
  messages: [{
    role: "user",
    content: "Redis, PostgreSQL, DynamoDB 를 세션 저장소 용도로 비교해줘. 각각 조사한 뒤 표로 정리해줘.",
  }],
});

const perMessage = result.messages.map((m) => {
  const calls = (m as { tool_calls?: Array<{ name: string }> }).tool_calls ?? [];
  return calls.filter((c) => c.name === "task").length;
}).filter((n) => n > 0);

/**
 * Step 06 — 서브에이전트
 * 실행: npx tsx docs/reference/deepagent/step-06-subagents/practice.ts
 *
 * 이 파일은 본문 6-1 ~ 6-10 의 예제를 순서대로 담고 있습니다.
 * [6-2] ~ [6-6] 은 task 도구의 "구조" 를 들여다보는 예제라 API 키 없이도 돌아갑니다.
 * [6-9], [6-10] 은 실제 모델을 호출하므로 ANTHROPIC_API_KEY 가 필요합니다.
 */
import "dotenv/config";
import {
  createDeepAgent,
  createSubAgentMiddleware,
  StateBackend,
  GENERAL_PURPOSE_SUBAGENT,
  DEFAULT_GENERAL_PURPOSE_DESCRIPTION,
  isAsyncSubAgent,
  type SubAgent,
  type AsyncSubAgent,
} from "deepagents";
import { tool } from "langchain";
import * as z from "zod";

const MODEL = "anthropic:claude-sonnet-4-6";
// OpenAI 로 바꾸려면: const MODEL = "openai:gpt-5.5";  (OPENAI_API_KEY 필요)
const CHEAP_MODEL = "anthropic:claude-haiku-4-5";

function show(label: string, value: unknown, max = 220) {
  const s = typeof value === "string" ? value : JSON.stringify(value);
  console.log(`  ${label}: ${s.length > max ? s.slice(0, max) + " …" : s}`);
}

/** 서브에이전트 미들웨어에서 task 도구를 꺼내 보는 헬퍼 (교육용 내부 들여다보기) */
function taskToolOf(middleware: unknown) {
  const tools = (middleware as { tools?: Array<{ name: string; description: string; schema: unknown }> }).tools ?? [];
  return tools.find((t) => t.name === "task");
}

/* ===== [6-1] 컨텍스트 격리가 목적이다 ===== */
// 서브에이전트는 "일을 나눠서 빨리 하기" 가 아닙니다. 그건 부수 효과입니다.
// 진짜 목적은 "부모의 컨텍스트를 보호하기" 입니다.
//
// 부모가 직접 파일 30개를 읽으면 → 30개 내용이 전부 부모 대화에 쌓입니다.
// 서브에이전트가 읽으면      → 부모에게는 "요약 한 덩어리" 만 돌아옵니다.
//
// 아래는 그 차이를 토큰 수로 가늠해 보는 시뮬레이션입니다 (모델 호출 없음).
async function section_6_1() {
  console.log("\n=== [6-1] 컨텍스트 격리 ===");

  const files = Array.from({ length: 30 }, (_, i) => ({
    path: `/docs/note-${i + 1}.md`,
    body: `# 노트 ${i + 1}\n` + "이 문서에는 대략 400토큰 분량의 내용이 들어 있습니다. ".repeat(20),
  }));

  const 직접읽기_누적 = files.reduce((sum, f) => sum + f.body.length, 0);
  const 서브에이전트_반환 = "30개 노트를 읽고 요약함: 핵심 주제는 A, B, C 세 가지.".length;

  show("부모가 직접 30개 읽으면 부모 컨텍스트에 쌓이는 글자 수", 직접읽기_누적.toLocaleString());
  show("서브에이전트에 맡기면 부모에게 돌아오는 글자 수", 서브에이전트_반환.toLocaleString());
  show("압축비", `약 ${Math.round(직접읽기_누적 / 서브에이전트_반환)}:1`);

  console.log("  → 서브에이전트도 그 30개를 다 읽습니다. 토큰을 아끼는 게 아닙니다.");
  console.log("  → 다만 그 30개가 '부모의' 대화에는 안 남습니다. 그게 격리입니다.");
}

/* ===== [6-2] task 도구의 동작 ===== */
// 서브에이전트를 하나라도 주면 부모에게 `task` 도구가 자동으로 붙습니다.
// 부모는 이 도구로만 자식을 부를 수 있습니다.
async function section_6_2() {
  console.log("\n=== [6-2] task 도구 ===");

  const middleware = createSubAgentMiddleware({
    defaultModel: MODEL,
    defaultTools: [],
    subagents: [
      { name: "researcher", description: "주제를 깊이 조사한다", systemPrompt: "너는 조사원이다." },
    ],
  });

  const task = taskToolOf(middleware);
  show("도구 이름", task?.name);

  // task 도구의 입력 스키마는 딱 2개 필드입니다.
  const { toJsonSchema } = await import("@langchain/core/utils/json_schema");
  console.log("\n  --- task 도구 입력 스키마 ---");
  console.log(JSON.stringify(toJsonSchema(task!.schema as never), null, 2));

  // 즉 부모는 이렇게 부릅니다:
  //   task({ subagent_type: "researcher", description: "양자컴퓨팅 최신 동향을 조사해줘" })
  //
  // 그리고 돌아오는 것은 ToolMessage 문자열 "하나" 뿐입니다.
  // 자식이 도구를 50번 불렀든 파일을 30개 읽었든, 부모는 최종 보고서 한 덩어리만 봅니다.
}

/* ===== [6-3] 기본 general-purpose 서브에이전트 ===== */
// subagents 를 안 줘도 general-purpose 하나가 자동으로 붙어 있습니다.
async function section_6_3() {
  console.log("\n=== [6-3] general-purpose ===");

  show("이름", GENERAL_PURPOSE_SUBAGENT.name);
  show("systemPrompt", GENERAL_PURPOSE_SUBAGENT.systemPrompt);
  console.log("\n  --- 기본 description (부모가 이걸 보고 고릅니다) ---");
  console.log("  " + DEFAULT_GENERAL_PURPOSE_DESCRIPTION);

  // general-purpose 는 부모의 도구를 전부 물려받고, 부모의 모델을 씁니다.
  // 끄고 싶으면 createSubAgentMiddleware 에서 generalPurposeAgent: false 를 줍니다.
  const withGP = createSubAgentMiddleware({ defaultModel: MODEL, defaultTools: [], subagents: [] });
  const withoutGP = createSubAgentMiddleware({
    defaultModel: MODEL,
    defaultTools: [],
    generalPurposeAgent: false,
    subagents: [{ name: "researcher", description: "조사 담당", systemPrompt: "너는 조사원이다." }],
  });

  // ⚠️ description 전체에 .includes("general-purpose") 를 쓰면 안 됩니다.
  //    task 도구 설명의 "사용 요령" 문단에도 그 단어가 나오기 때문에 항상 true 가 나옵니다.
  //    실제 목록은 "- 이름: 설명" 형태의 줄들입니다.
  const agentList = (mw: unknown) =>
    (taskToolOf(mw)?.description ?? "")
      .split("\n")
      .filter((l) => l.startsWith("- "))
      .map((l) => (l.split(":")[0] ?? "").replace("- ", ""));

  show("\n  기본 상태의 서브에이전트 목록", agentList(withGP));
  show("generalPurposeAgent:false 면", agentList(withoutGP));

  // 같은 이름("general-purpose")으로 커스텀 서브에이전트를 주면 교체됩니다.
  const custom: SubAgent = {
    ...GENERAL_PURPOSE_SUBAGENT,
    name: "general-purpose",
    systemPrompt: "너는 만능 조수다. 항상 한국어로 보고한다.",
  };
  show("교체용 서브에이전트", { name: custom.name, systemPrompt: custom.systemPrompt });
}

/* ===== [6-4] 커스텀 SubAgent 정의 ===== */
// 필수는 name / description / systemPrompt 3개. 나머지는 전부 선택입니다.
async function section_6_4() {
  console.log("\n=== [6-4] 커스텀 SubAgent ===");

  const webSearch = tool(
    async ({ query }) => `[모의 검색 결과] "${query}" 에 대한 자료 3건을 찾았습니다.`,
    {
      name: "web_search",
      description: "웹을 검색해 자료를 찾는다",
      schema: z.object({ query: z.string().describe("검색어") }),
    },
  );

  // (A) 최소 정의
  const minimal: SubAgent = {
    name: "summarizer",
    description: "긴 글을 3줄로 요약한다",
    systemPrompt: "너는 요약가다. 항상 정확히 3줄로 요약하라.",
  };

  // (B) 모든 필드를 쓴 정의
  const full: SubAgent = {
    name: "researcher",
    description:
      "웹에서 특정 주제를 조사한다. 주제 하나당 하나씩 부를 것. " +
      "출처 URL 과 함께 조사 결과를 반환한다.",
    systemPrompt:
      "너는 조사원이다. web_search 로 자료를 찾고, 찾은 내용을 근거와 함께 정리하라. " +
      "추측하지 말고 찾은 것만 보고하라.",
    tools: [webSearch], // 지정하면 부모 도구를 물려받지 않고 이것만 씁니다
    model: CHEAP_MODEL, // 서브에이전트별 모델 차등 (6-6)
    responseFormat: z.object({
      // 구조화된 반환 (JSON 문자열로 부모에게 전달됨)
      summary: z.string().describe("조사 요약"),
      sources: z.array(z.string()).describe("출처 URL 목록"),
      confidence: z.number().min(0).max(1).describe("확신도"),
    }),
    permissions: [
      // 부모 권한을 "병합" 이 아니라 "완전 교체" 합니다 (Step 05 참고)
      { operations: ["read"], paths: ["/research/**"], mode: "allow" },
      { operations: ["read", "write"], paths: ["/**"], mode: "deny" },
    ],
  };

  show("(A) 최소 정의", { name: minimal.name, 필드수: Object.keys(minimal).length });
  show("(B) 전체 정의", { name: full.name, 필드: Object.keys(full) });

  const agent = createDeepAgent({
    model: MODEL,
    backend: new StateBackend(),
    subagents: [minimal, full],
  });
  show("에이전트 생성", typeof agent.invoke === "function");
}

/* ===== [6-5] description 이 라우팅을 결정한다 ===== */
// 부모는 자식의 systemPrompt 도, tools 도 못 봅니다. 오직 description 만 봅니다.
// 증거: task 도구의 설명 문자열에 각 서브에이전트의 description 이 그대로 박힙니다.
async function section_6_5() {
  console.log("\n=== [6-5] description 이 곧 라우팅 규칙 ===");

  const vague = createSubAgentMiddleware({
    defaultModel: MODEL,
    defaultTools: [],
    generalPurposeAgent: false,
    subagents: [
      { name: "helper1", description: "도와준다", systemPrompt: "너는 SQL 전문가다." },
      { name: "helper2", description: "처리한다", systemPrompt: "너는 이미지 편집 전문가다." },
    ],
  });

  const clear = createSubAgentMiddleware({
    defaultModel: MODEL,
    defaultTools: [],
    generalPurposeAgent: false,
    subagents: [
      {
        name: "sql-expert",
        description: "SQL 쿼리를 작성하고 최적화한다. 데이터베이스 스키마 질문에도 답한다.",
        systemPrompt: "너는 SQL 전문가다.",
      },
      {
        name: "image-editor",
        description: "이미지를 자르고 리사이즈하고 포맷을 변환한다.",
        systemPrompt: "너는 이미지 편집 전문가다.",
      },
    ],
  });

  console.log("\n  --- 모호한 description 이 부모에게 보이는 모습 ---");
  const vagueDesc = taskToolOf(vague)!.description;
  console.log("  " + vagueDesc.split("\n").filter((l) => l.startsWith("- ")).join("\n  "));
  console.log("  → 부모는 'SQL 짜줘' 를 받고 helper1/helper2 중 뭘 골라야 할지 알 수 없습니다.");

  console.log("\n  --- 명확한 description ---");
  const clearDesc = taskToolOf(clear)!.description;
  console.log("  " + clearDesc.split("\n").filter((l) => l.startsWith("- ")).join("\n  "));
  console.log("  → 부모는 망설임 없이 sql-expert 를 고릅니다.");

  // systemPrompt 는 task 도구 설명에 안 들어갑니다 — 부모는 못 봅니다.
  show("\n  task 설명에 'SQL 전문가다'(systemPrompt) 가 들어있나?", vagueDesc.includes("SQL 전문가다"));
}

/* ===== [6-6] 서브에이전트별 모델 차등 ===== */
// 싼 모델로 넓게 조사하고, 비싼 모델로 종합합니다.
async function section_6_6() {
  console.log("\n=== [6-6] 모델 차등 ===");

  const scout: SubAgent = {
    name: "scout",
    description: "자료를 넓게 훑어 후보를 추린다. 정확도보다 커버리지가 중요할 때 쓴다.",
    systemPrompt: "너는 정찰병이다. 빠르게 훑고 후보만 추려라.",
    model: CHEAP_MODEL, // 싼 모델
  };

  const analyst: SubAgent = {
    name: "analyst",
    description: "추려진 자료를 깊이 분석하고 결론을 낸다. 정확도가 중요할 때 쓴다.",
    systemPrompt: "너는 분석가다. 근거를 들어 결론을 내라.",
    model: MODEL, // 비싼 모델
  };

  // 부모(종합 담당)는 비싼 모델
  const agent = createDeepAgent({ model: MODEL, backend: new StateBackend(), subagents: [scout, analyst] });

  show("scout 모델", scout.model);
  show("analyst 모델", analyst.model);
  show("부모 모델", MODEL);
  show("에이전트 생성", typeof agent.invoke === "function");

  // model 을 생략하면 부모 모델을 그대로 물려받습니다.
  const inherits: SubAgent = { name: "x", description: "…", systemPrompt: "…" };
  show("model 생략 시", `부모 모델(${MODEL})을 상속`);
}

/* ===== [6-7] 비동기/병렬 서브에이전트 ===== */
// 두 가지를 구분해야 합니다.
//  (1) 동기 서브에이전트의 "병렬 실행": 부모가 task 를 여러 개 한 번에 호출 → 부모는 전부 끝날 때까지 기다림
//  (2) 비동기 서브에이전트(AsyncSubAgent): 부모가 작업을 띄우고 "즉시" 다른 일을 함
async function section_6_7() {
  console.log("\n=== [6-7] 비동기/병렬 ===");

  // (1) 동기 병렬 — 그냥 평범한 SubAgent 입니다. 부모가 한 메시지에 task 를 여러 번 부르면 됩니다.
  //     task 도구 설명에 "Launch multiple agents concurrently whenever possible" 이라고
  //     이미 지시가 들어 있어서, 모델이 알아서 병렬로 부릅니다.
  const syncSub: SubAgent = {
    name: "researcher",
    description: "주제 하나를 조사한다. 여러 주제면 주제당 하나씩 병렬로 부를 것.",
    systemPrompt: "너는 조사원이다.",
  };
  show("(1) 동기 서브에이전트", { name: syncSub.name, isAsync: isAsyncSubAgent(syncSub) });

  // (2) 비동기 서브에이전트 — graphId 로 Agent Protocol 서버의 그래프를 가리킵니다.
  //     systemPrompt 가 아니라 graphId 가 있다는 게 결정적 차이입니다.
  const asyncSubs: AsyncSubAgent[] = [
    {
      name: "long-researcher",
      description: "몇 분씩 걸리는 장기 조사를 백그라운드로 수행한다.",
      graphId: "researcher", // 같은 배포 안의 그래프 (ASGI)
    },
    {
      name: "remote-coder",
      description: "원격 배포된 코딩 에이전트.",
      graphId: "coder",
      url: "https://coder-deployment.langsmith.dev", // 원격이면 url 추가
    },
  ];
  for (const s of asyncSubs) show(`(2) ${s.name}`, { graphId: s.graphId, isAsync: isAsyncSubAgent(s) });

  // 비동기를 주면 부모는 task 대신 5개 도구를 받습니다:
  //   start_async_task / check_async_task / update_async_task / cancel_async_task / list_async_tasks
  console.log("\n  비동기 서브에이전트를 쓰면 부모가 받는 도구:");
  for (const t of ["start_async_task", "check_async_task", "update_async_task", "cancel_async_task", "list_async_tasks"]) {
    console.log(`    - ${t}`);
  }
  console.log("  → start 는 즉시 task id 를 돌려주고, 부모는 기다리지 않고 다음 일을 합니다.");
  console.log("  → 실행하려면 Agent Protocol 서버가 필요합니다 (langgraph dev --n-jobs-per-worker 10).");

  // 아래는 실제로 서버가 없으면 안 도므로 생성만 해둡니다.
  //   const agent = createDeepAgent({ model: MODEL, subagents: [...asyncSubs] });
}

/* ===== [6-8] 동적 서브에이전트 ===== */
// 인터프리터 안에서 task() 를 코드로 부릅니다 — 루프, 조건문, Promise.all 이 가능해집니다.
async function section_6_8() {
  console.log("\n=== [6-8] 동적 서브에이전트 ===");

  console.log("  @langchain/quickjs 의 createCodeInterpreterMiddleware 를 붙이면");
  console.log("  모델이 '코드로' 서브에이전트를 부를 수 있습니다:\n");

  const example = `
  // 모델이 eval 도구 안에서 작성하는 코드 (우리가 쓰는 게 아닙니다)
  const files = (await tools.glob({ pattern: "src/routes/**/*.ts" }))
    .split("\\n").filter(Boolean);

  const reviews = await Promise.all(
    files.map((file) =>
      task({
        description: \`\${file} 을 인증 취약점 관점에서 리뷰하라. 줄 번호를 인용할 것.\`,
        subagentType: "reviewer",
        responseSchema: issuesSchema,
      }),
    ),
  );
  const issues = reviews.flatMap((r) => r.issues);`;
  console.log(example);

  console.log("\n  설정은 이렇게 합니다:");
  console.log(`
  import { createCodeInterpreterMiddleware } from "@langchain/quickjs";

  const agent = createDeepAgent({
    model: MODEL,
    subagents: [{
      name: "reviewer",
      description: "코드를 보안 관점에서 리뷰하고 줄 번호와 심각도를 인용한다",
      systemPrompt: "너는 보안 중심 코드 리뷰어다.",
    }],
    middleware: [createCodeInterpreterMiddleware()],
  });`);

  console.log("\n  일반 task 와의 차이:");
  console.log("    - 일반 task: 부모가 '파일 개수만큼' 도구 호출을 직접 해야 함 (몇 개인지 미리 알아야 함)");
  console.log("    - 동적 task: 파일 개수를 런타임에 알아내서 그만큼 루프를 돎");
  console.log("  프롬프트에 'workflow' 라는 말을 넣으면 모델이 코드 오케스트레이션을 택하는 경향이 있습니다.");
}

/* ===== [6-9] 파일시스템으로 결과 주고받기 ===== */
// task 의 반환은 "문자열 하나" 입니다. 큰 결과는 파일로 넘기고 경로만 돌려받습니다.
async function section_6_9() {
  console.log("\n=== [6-9] 파일로 결과 주고받기 ===");

  if (!process.env.ANTHROPIC_API_KEY) {
    console.log("  ANTHROPIC_API_KEY 가 없어 건너뜁니다.");
    return;
  }

  const writer: SubAgent = {
    name: "report-writer",
    description:
      "주제에 대한 상세 리포트를 작성해 지정된 파일 경로에 저장한다. " +
      "반환값으로는 저장한 경로와 한 줄 요약만 준다.",
    systemPrompt:
      "너는 리포트 작성자다. 요청받은 내용을 write_file 로 지정된 경로에 저장하라. " +
      "최종 답변에는 리포트 전문을 넣지 말고, 저장 경로와 한 줄 요약만 적어라.",
  };

  const agent = createDeepAgent({
    model: MODEL,
    backend: new StateBackend(),
    subagents: [writer],
    systemPrompt:
      "너는 편집자다. report-writer 서브에이전트에게 리포트 작성을 시키고, " +
      "결과 파일을 read_file 로 읽어 사용자에게 핵심만 전달하라.",
  });

  const result = await agent.invoke({
    messages: [
      {
        role: "user",
        content:
          "TypeScript 의 satisfies 연산자에 대해 리포트를 /reports/satisfies.md 에 작성하게 하고, " +
          "그 파일을 읽어서 핵심 3가지만 알려줘.",
      },
    ],
  });

  console.log("\n  --- 최종 답변 (매번 다릅니다) ---");
  console.log("  " + String(result.messages.at(-1)?.content).split("\n").join("\n  "));

  // 서브에이전트가 쓴 파일은 부모 상태에 남습니다 — 같은 백엔드를 공유하기 때문입니다.
  const files = (result as { files?: Record<string, unknown> }).files;
  show("\n  상태에 남은 파일", files ? Object.keys(files) : "(없음)");
}

/* ===== [6-10] 실전 — 리서치 서브에이전트 3개 병렬 + 종합 ===== */
async function section_6_10() {
  console.log("\n=== [6-10] 병렬 리서치 + 종합 ===");

  if (!process.env.ANTHROPIC_API_KEY) {
    console.log("  ANTHROPIC_API_KEY 가 없어 건너뜁니다.");
    return;
  }

  // 모의 검색 도구 (실제로는 Tavily 등을 씁니다)
  const webSearch = tool(
    async ({ query }) => {
      const db: Record<string, string> = {
        redis: "Redis: 인메모리 키-값 저장소. 단일 스레드, 매우 빠름. 영속성은 RDB/AOF 옵션.",
        postgres: "PostgreSQL: 관계형 DB. ACID 완전 지원, JSONB 로 문서도 저장 가능.",
        dynamodb: "DynamoDB: AWS 관리형 NoSQL. 무제한 확장, 키 설계가 성능을 좌우.",
      };
      const hit = Object.entries(db).find(([k]) => query.toLowerCase().includes(k));
      return hit ? hit[1] : `"${query}" 에 대한 자료를 찾지 못했습니다.`;
    },
    {
      name: "web_search",
      description: "웹에서 기술 자료를 검색한다",
      schema: z.object({ query: z.string().describe("검색어") }),
    },
  );

  const researcher: SubAgent = {
    name: "researcher",
    description:
      "기술 하나를 조사해 특징과 트레이드오프를 정리한다. " +
      "여러 기술을 비교해야 하면 기술 하나당 하나씩 병렬로 호출할 것. " +
      "조사 결과를 /research/<기술명>.md 에 저장하고 경로만 반환한다.",
    systemPrompt:
      "너는 기술 조사원이다. web_search 로 자료를 찾아 특징/장점/단점을 정리하고, " +
      "지정된 경로에 write_file 로 저장하라. 최종 답변은 '저장 경로 + 한 줄 요약' 만 적어라. " +
      "너는 부모의 대화를 볼 수 없으므로, 프롬프트에 주어진 정보만으로 판단하라.",
    tools: [webSearch],
    model: CHEAP_MODEL, // 조사는 싼 모델로
  };

  const agent = createDeepAgent({
    model: MODEL, // 종합은 비싼 모델로
    backend: new StateBackend(),
    subagents: [researcher],
    systemPrompt:
      "너는 기술 선임이다. 비교 요청을 받으면 researcher 서브에이전트를 " +
      "대상 기술마다 하나씩 '병렬로' 띄워라(한 메시지에 task 를 여러 번 호출). " +
      "각자가 저장한 파일을 읽어 최종 비교표를 만들어라.",
  });

  const result = await agent.invoke({
    messages: [
      {
        role: "user",
        content:
          "Redis, PostgreSQL, DynamoDB 를 세션 저장소 용도로 비교해줘. " +
          "각각 조사한 뒤 표로 정리해줘.",
      },
    ],
  });

  console.log("\n  --- 최종 비교 (매번 다릅니다) ---");
  console.log("  " + String(result.messages.at(-1)?.content).split("\n").join("\n  "));

  // 부모가 실제로 task 를 몇 번 불렀는지 세어 봅니다.
  const taskCalls = result.messages.flatMap((m) => {
    const calls = (m as { tool_calls?: Array<{ name: string; args: Record<string, unknown> }> }).tool_calls ?? [];
    return calls.filter((c) => c.name === "task");
  });
  console.log(`\n  task 호출 횟수: ${taskCalls.length}`);
  for (const c of taskCalls) {
    show("  → subagent_type", c.args.subagent_type);
  }
  show("  부모 메시지 총 개수", result.messages.length);
}

/* ===== 실행 ===== */
async function main() {
  await section_6_1();
  await section_6_2();
  await section_6_3();
  await section_6_4();
  await section_6_5();
  await section_6_6();
  await section_6_7();
  await section_6_8();
  await section_6_9();
  await section_6_10();
}

main().catch((e) => {
  console.error(e);
  process.exit(1);
});

/**
 * Step 06 — 서브에이전트 · 연습문제
 * 실행: npx tsx docs/reference/deepagent/step-06-subagents/exercise.ts
 *
 * 문제 1~5 는 API 키 없이 풀 수 있습니다 (task 도구의 구조를 들여다보는 문제).
 * 문제 6~7 은 실제 모델을 호출합니다.
 *
 * 정답은 solution.ts 에 있습니다. 먼저 스스로 풀어보세요.
 */
import "dotenv/config";
import {
  createDeepAgent,
  createSubAgentMiddleware,
  StateBackend,
  GENERAL_PURPOSE_SUBAGENT,
  isAsyncSubAgent,
  type SubAgent,
  type AsyncSubAgent,
} from "deepagents";
import { tool } from "langchain";
import * as z from "zod";

const MODEL = "anthropic:claude-sonnet-4-6";
const CHEAP_MODEL = "anthropic:claude-haiku-4-5";

/** 서브에이전트 미들웨어에서 task 도구를 꺼내는 헬퍼 */
function taskToolOf(middleware: unknown) {
  const tools = (middleware as { tools?: Array<{ name: string; description: string; schema: unknown }> }).tools ?? [];
  return tools.find((t) => t.name === "task");
}

/** task 도구 설명에서 "- 이름: 설명" 목록만 뽑는 헬퍼 */
function agentList(middleware: unknown): string[] {
  return (taskToolOf(middleware)?.description ?? "")
    .split("\n")
    .filter((l) => l.startsWith("- "))
    .map((l) => l.replace("- ", ""));
}

/* ===== [문제 1] 서브에이전트를 쓸까 말까 ===== */
// 다음 4가지 상황에서 서브에이전트를 쓰는 게 맞는지 판단하고, 이유를 한 줄 주석으로 적으세요.
//
//  (a) 사용자가 "1+1은?" 이라고 물었다.
//      → 답:
//  (b) 코드베이스 전체(파일 200개)를 훑어 보안 취약점을 찾아야 한다.
//      → 답:
//  (c) 파일 하나를 읽어 오타 하나를 고쳐야 한다.
//      → 답:
//  (d) 서로 무관한 기술 5개를 각각 조사해 비교표를 만들어야 한다.
//      → 답:

/* ===== [문제 2] task 도구는 언제 생기나 ===== */
// createSubAgentMiddleware 를 두 가지로 만들어, task 도구의 "서브에이전트 목록" 을 각각 출력하세요.
//   (a) subagents: [] 이고 generalPurposeAgent 기본값
//   (b) subagents: [] 이고 generalPurposeAgent: false
// 힌트: 위의 agentList() 헬퍼를 쓰세요.
// 확인 후, (b)에서 task 도구가 어떻게 되는지 주석으로 적으세요.
function exercise2() {
  console.log("\n=== [문제 2] task 도구는 언제 생기나 ===");

  // TODO: 여기에 작성
}

/* ===== [문제 3] description 을 고쳐라 ===== */
// 아래 두 서브에이전트는 description 이 너무 모호해서 부모가 못 고릅니다.
// description 만 고쳐서, 부모가 "이번 달 매출 쿼리 좀 짜줘" 를 받았을 때
// 망설임 없이 sql 쪽을 고르게 만드세요. (systemPrompt 는 건드리지 마세요.)
// 고친 뒤 agentList() 로 부모에게 보이는 모습을 출력해 확인하세요.
function exercise3() {
  console.log("\n=== [문제 3] description 고치기 ===");

  const before: SubAgent[] = [
    { name: "db-helper", description: "DB 관련 작업", systemPrompt: "너는 SQL 전문가다." },
    { name: "report-helper", description: "리포트 관련 작업", systemPrompt: "너는 차트/리포트 렌더링 전문가다." },
  ];

  // TODO: after 배열을 만들고, before / after 를 agentList() 로 비교 출력하세요.
}

/* ===== [문제 4] 모델 차등 설계 ===== */
// "뉴스 기사 100건을 훑어 우리 회사 관련된 것만 추린 뒤, 그것들만 깊이 분석" 하는 파이프라인을
// 서브에이전트 2개로 설계하세요.
//   - 어느 쪽에 싼 모델(CHEAP_MODEL), 어느 쪽에 비싼 모델(MODEL)을 줄지 정하고
//   - 부모 모델은 무엇으로 할지 정하고
//   - 왜 그렇게 나눴는지 주석으로 적으세요.
// createDeepAgent 까지 만들어 생성이 되는지 확인하세요.
function exercise4() {
  console.log("\n=== [문제 4] 모델 차등 ===");

  // TODO: 여기에 작성
}

/* ===== [문제 5] 동기 vs 비동기 구분 ===== */
// 아래 4개 정의 중 어떤 것이 AsyncSubAgent 인지 isAsyncSubAgent() 로 판별해 출력하세요.
// 그리고 "무엇이 그 둘을 가르는가"(어떤 필드) 를 주석으로 적으세요.
function exercise5() {
  console.log("\n=== [문제 5] 동기 vs 비동기 ===");

  const candidates: Array<SubAgent | AsyncSubAgent> = [
    { name: "a", description: "조사한다", systemPrompt: "너는 조사원이다." },
    { name: "b", description: "조사한다", graphId: "researcher" },
    { name: "c", description: "코딩한다", graphId: "coder", url: "https://example.langsmith.dev" },
    { name: "d", description: "요약한다", systemPrompt: "너는 요약가다.", model: CHEAP_MODEL },
  ];

  // TODO: 여기에 작성
  // → 무엇이 둘을 가르나요? (여기에 설명)
}

/* ===== [문제 6] 부모 컨텍스트를 못 본다 ===== */
// 아래 에이전트는 "고장나 있습니다". 서브에이전트가 부모 대화를 못 보기 때문입니다.
// 1) 먼저 그대로 실행해서 어떻게 어긋나는지 관찰하세요.
// 2) 그다음 systemPrompt 를 고쳐서, 부모가 필요한 맥락을 task 프롬프트에 "다 담도록" 만드세요.
// (서브에이전트의 systemPrompt 가 아니라 "부모의" systemPrompt 를 고치는 게 포인트입니다.)
async function exercise6() {
  console.log("\n=== [문제 6] 서브에이전트는 부모 대화를 못 본다 ===");

  if (!process.env.ANTHROPIC_API_KEY) {
    console.log("  ANTHROPIC_API_KEY 가 없어 건너뜁니다.");
    return;
  }

  const translator: SubAgent = {
    name: "translator",
    description: "주어진 문장을 번역한다.",
    systemPrompt: "너는 번역가다. 주어진 문장을 번역하라.",
  };

  const agent = createDeepAgent({
    model: MODEL,
    backend: new StateBackend(),
    subagents: [translator],
    // TODO: 이 systemPrompt 가 문제입니다. 고치세요.
    systemPrompt: "너는 조수다. 번역이 필요하면 translator 를 불러라.",
  });

  const result = await agent.invoke({
    messages: [
      { role: "user", content: "나는 앞으로 모든 답변을 일본어로 받고 싶어. 기억해줘." },
      { role: "assistant", content: "알겠습니다. 앞으로 일본어로 답변드리겠습니다." },
      { role: "user", content: "'안녕하세요, 반갑습니다' 를 번역해줘." },
    ],
  });

  console.log("  " + String(result.messages.at(-1)?.content).split("\n").join("\n  "));
  // → translator 가 무슨 언어로 번역했나요? 왜 그런가요? (여기에 설명)
}

/* ===== [문제 7] 병렬 리서치 ===== */
// 아래 mockSearch 도구를 쓰는 researcher 서브에이전트를 만들고,
// 부모가 3개 주제(typescript / rust / go)를 "병렬로" 조사하게 만드세요.
// 요구사항:
//   - researcher 는 CHEAP_MODEL, 부모는 MODEL
//   - description 에 "주제 하나당 하나씩 병렬로 호출할 것" 을 명시
//   - 각 researcher 는 결과를 /research/<주제>.md 에 저장하고 경로만 반환
//   - 부모는 파일들을 읽어 비교표를 만듦
// 실행 후 task 호출이 몇 번 일어났는지 세어 출력하세요.
async function exercise7() {
  console.log("\n=== [문제 7] 병렬 리서치 ===");

  if (!process.env.ANTHROPIC_API_KEY) {
    console.log("  ANTHROPIC_API_KEY 가 없어 건너뜁니다.");
    return;
  }

  const mockSearch = tool(
    async ({ query }) => {
      const db: Record<string, string> = {
        typescript: "TypeScript: JS 의 상위집합. 정적 타입, 컴파일 필요. 생태계 거대.",
        rust: "Rust: 소유권 모델로 GC 없이 메모리 안전. 학습 곡선 가파름. 성능 최상.",
        go: "Go: 단순한 문법, 빠른 컴파일, goroutine 동시성. GC 있음.",
      };
      const hit = Object.entries(db).find(([k]) => query.toLowerCase().includes(k));
      return hit ? hit[1] : `"${query}" 자료 없음`;
    },
    {
      name: "web_search",
      description: "기술 자료를 검색한다",
      schema: z.object({ query: z.string().describe("검색어") }),
    },
  );

  // TODO: 여기에 작성
}

async function main() {
  exercise2();
  exercise3();
  exercise4();
  exercise5();
  await exercise6();
  await exercise7();
}

main().catch((e) => {
  console.error(e);
  process.exit(1);
});

/**
 * Step 06 — 서브에이전트 · 정답
 * 실행: npx tsx docs/reference/deepagent/step-06-subagents/solution.ts
 *
 * exercise.ts 를 스스로 풀어본 뒤에 열어보세요.
 */
import "dotenv/config";
import {
  createDeepAgent,
  createSubAgentMiddleware,
  StateBackend,
  isAsyncSubAgent,
  type SubAgent,
  type AsyncSubAgent,
} from "deepagents";
import { tool } from "langchain";
import * as z from "zod";

const MODEL = "anthropic:claude-sonnet-4-6";
const CHEAP_MODEL = "anthropic:claude-haiku-4-5";

function show(label: string, value: unknown, max = 220) {
  const s = typeof value === "string" ? value : JSON.stringify(value);
  console.log(`  ${label}: ${s.length > max ? s.slice(0, max) + " …" : s}`);
}

function taskToolOf(middleware: unknown) {
  const tools = (middleware as { tools?: Array<{ name: string; description: string; schema: unknown }> }).tools ?? [];
  return tools.find((t) => t.name === "task");
}

function agentList(middleware: unknown): string[] {
  return (taskToolOf(middleware)?.description ?? "")
    .split("\n")
    .filter((l) => l.startsWith("- "))
    .map((l) => l.replace("- ", ""));
}

/* ===== [정답 1] 서브에이전트를 쓸까 말까 ===== */
// (a) "1+1은?"
//     → 쓰지 않는다. 서브에이전트를 띄우는 것 자체가 LLM 호출 한 번 + 지연입니다.
//       task 도구 설명에도 "If the task is trivial (a few tool calls or simple lookup)" 은
//       쓰지 말라고 명시돼 있습니다.
//
// (b) 파일 200개를 훑어 취약점 찾기
//     → 쓴다. 전형적인 케이스입니다. 200개 파일 내용이 부모 컨텍스트에 쌓이면 터집니다.
//       서브에이전트가 다 읽고 "취약점 목록" 만 돌려주면 부모는 깨끗합니다.
//
// (c) 파일 하나 읽어 오타 하나 고치기
//     → 쓰지 않는다. 도구 2번이면 끝나는 일입니다. 위임이 토큰도 복잡도도 안 줄입니다.
//       오히려 자식이 파일을 다시 읽어야 해서 느려집니다.
//
// (d) 무관한 기술 5개 조사 후 비교
//     → 쓴다. 그리고 "병렬로" 씁니다. 각 조사는 서로 독립적이고,
//       각자 자료를 많이 읽지만 부모는 5개 요약만 받으면 됩니다.
//       task 설명의 LeBron/Jordan/Kobe 예시가 정확히 이 패턴입니다.
//
// 판단 기준 한 줄: "이 일이 컨텍스트를 많이 먹는데, 중간 과정은 안 봐도 되는가?"
//                  둘 다 예 → 서브에이전트. 하나라도 아니오 → 그냥 직접.

/* ===== [정답 2] task 도구는 언제 생기나 ===== */
function solution2() {
  console.log("\n=== [정답 2] task 도구는 언제 생기나 ===");

  const withGP = createSubAgentMiddleware({
    defaultModel: MODEL,
    defaultTools: [],
    subagents: [],
  });
  const withoutGP = createSubAgentMiddleware({
    defaultModel: MODEL,
    defaultTools: [],
    generalPurposeAgent: false,
    subagents: [],
  });

  show("(a) subagents:[] + 기본값 → 목록", agentList(withGP));
  show("(b) subagents:[] + generalPurposeAgent:false → 목록", agentList(withoutGP));
  show("(b) 에서 task 도구 자체가 있나?", taskToolOf(withoutGP) !== undefined);

  // 해설:
  //  (a) subagents 를 하나도 안 줬는데도 general-purpose 가 있습니다.
  //      → Deep Agent 는 기본으로 general-purpose 를 붙입니다. task 도구도 그래서 생깁니다.
  //  (b) generalPurposeAgent: false + subagents: [] 이면 목록이 빈 배열이 됩니다.
  //      → 그런데 task 도구 자체는 "여전히 존재합니다" (위 출력의 마지막 줄).
  //        부를 대상이 하나도 없는 도구가 모델에게 노출돼 있는 상태입니다.
  //
  // ⚠️ 함정 1: "나는 subagents 를 안 줬으니 서브에이전트가 없다" 고 생각하기 쉽지만
  //          general-purpose 가 이미 있습니다. 즉 모델은 언제든 task 를 부를 수 있고,
  //          그러면 예상 못 한 LLM 호출과 지연과 비용이 생깁니다.
  //
  // ⚠️ 함정 2: 반대로 generalPurposeAgent: false 로 다 끄면 목록만 비고 도구는 남습니다.
  //          모델이 그 빈 도구를 부르려 시도할 수 있습니다. 서브에이전트를 안 쓸 거라면
  //          createSubAgentMiddleware 를 아예 넣지 않는 쪽이 깔끔합니다.
  //
  // 💡 참고: createDeepAgent 는 이 미들웨어를 기본 스택에 넣어줍니다.
  //    여기서 createSubAgentMiddleware 를 직접 부른 건 내부를 들여다보려는 교육용 목적입니다.
  //    실무에서는 createDeepAgent({ subagents: [...] }) 만 쓰면 됩니다.
}

/* ===== [정답 3] description 을 고쳐라 ===== */
function solution3() {
  console.log("\n=== [정답 3] description 고치기 ===");

  const before: SubAgent[] = [
    { name: "db-helper", description: "DB 관련 작업", systemPrompt: "너는 SQL 전문가다." },
    { name: "report-helper", description: "리포트 관련 작업", systemPrompt: "너는 차트/리포트 렌더링 전문가다." },
  ];

  const after: SubAgent[] = [
    {
      name: "db-helper",
      // 좋은 description = 동사로 시작 + 무엇을 받아 무엇을 주는지 + 언제 부르는지
      description:
        "SQL 쿼리를 작성하고 최적화한다. 매출/집계/조인 같은 데이터 조회 요청이나 " +
        "테이블 스키마 질문이 오면 이걸 부를 것. 쿼리문과 설명을 반환한다.",
      systemPrompt: "너는 SQL 전문가다.",
    },
    {
      name: "report-helper",
      description:
        "이미 계산된 데이터를 받아 차트나 리포트 문서로 렌더링한다. " +
        "'표로 그려줘', '차트로 보여줘' 같은 시각화 요청에만 부를 것. " +
        "데이터를 조회하지는 못한다.",
      systemPrompt: "너는 차트/리포트 렌더링 전문가다.",
    },
  ];

  const mk = (subs: SubAgent[]) =>
    createSubAgentMiddleware({
      defaultModel: MODEL,
      defaultTools: [],
      generalPurposeAgent: false,
      subagents: subs,
    });

  console.log("\n  --- before (부모에게 보이는 전부) ---");
  for (const l of agentList(mk(before))) console.log("    - " + l);
  console.log("  → '이번 달 매출 쿼리 좀 짜줘' … db-helper? report-helper? 둘 다 '관련 작업' 입니다.");

  console.log("\n  --- after ---");
  for (const l of agentList(mk(after))) console.log("    - " + l);
  console.log("  → 'SQL 쿼리를 작성' + '매출/집계 요청이 오면' 이 있으니 db-helper 로 확정됩니다.");

  // ⚠️ 함정 (이 문제의 핵심): 부모는 자식의 systemPrompt 를 볼 수 없습니다.
  //    before 의 systemPrompt 에는 "너는 SQL 전문가다" 라고 또렷이 적혀 있지만,
  //    그건 자식이 실행될 때 쓰이는 것이지 부모의 선택에는 아무 영향이 없습니다.
  //    부모가 보는 것은 오직 description 뿐입니다.
  const desc = taskToolOf(mk(before))!.description;
  show("\n  task 설명에 'SQL 전문가다'(systemPrompt) 가 있나?", desc.includes("SQL 전문가다"));

  // 💡 description 작성 공식:
  //    "[동사]한다. [언제 부르는지]. [무엇을 반환하는지]."
  //    그리고 헷갈리는 형제가 있으면 "~는 못 한다" 로 경계를 그어주세요.
}

/* ===== [정답 4] 모델 차등 설계 ===== */
function solution4() {
  console.log("\n=== [정답 4] 모델 차등 ===");

  const screener: SubAgent = {
    name: "screener",
    description:
      "뉴스 기사 목록을 훑어 특정 키워드와 관련된 기사만 추린다. " +
      "많은 양을 빠르게 걸러야 할 때 부를 것. 관련 기사 제목 목록만 반환한다.",
    systemPrompt: "너는 선별가다. 관련 있는 것만 추려라. 분석하지 말고 추리기만 하라.",
    model: CHEAP_MODEL, // ← 싼 모델: 단순 분류, 양이 많음
  };

  const analyst: SubAgent = {
    name: "analyst",
    description:
      "추려진 기사 몇 건을 깊이 읽고 시사점과 리스크를 분석한다. " +
      "정확한 판단이 필요할 때 부를 것. 근거와 함께 분석 결과를 반환한다.",
    systemPrompt: "너는 분석가다. 근거를 들어 시사점과 리스크를 정리하라.",
    model: MODEL, // ← 비싼 모델: 소수, 정확도가 중요
  };

  const agent = createDeepAgent({
    model: MODEL, // ← 부모도 비싼 모델: 최종 종합은 품질이 중요
    backend: new StateBackend(),
    subagents: [screener, analyst],
    systemPrompt:
      "너는 리서치 리드다. 먼저 screener 로 관련 기사를 추리고, " +
      "추려진 것만 analyst 에게 넘겨 분석시킨 뒤 종합하라.",
  });

  show("screener", screener.model);
  show("analyst", analyst.model);
  show("부모", MODEL);
  show("에이전트 생성", typeof agent.invoke === "function");

  // 왜 이렇게 나눴나:
  //  - screener 는 "기사 100건" 이라는 큰 입력을 받지만 하는 일은 단순 분류입니다.
  //    양 × 단순 → 싼 모델이 정확히 맞는 자리입니다.
  //  - analyst 는 입력이 몇 건뿐이지만 틀리면 안 됩니다.
  //    소수 × 중요 → 비싼 모델.
  //  - 부모는 최종 결과물을 만듭니다. 사용자가 실제로 읽는 글이니 비싼 모델.
  //
  // 💡 일반 원칙: "입력이 크고 판단이 단순한 곳" 에 싼 모델을 넣으면 비용이 가장 많이 절감됩니다.
  //    반대로 부모(종합)를 싼 모델로 바꾸는 건 대개 손해입니다 — 품질 저하가 바로 보입니다.
  //
  // ⚠️ 함정: 싼 모델은 도구 호출을 덜 안정적으로 합니다.
  //    서브에이전트에게 도구를 많이 주면서 싼 모델을 쓰면, 도구를 안 부르거나
  //    엉뚱한 인자를 넣고도 "완료했습니다" 라고 보고합니다. 부모는 그걸 그대로 믿습니다
  //    (task 설명에 "The agent's outputs should generally be trusted" 라고 적혀 있습니다).
  //    싼 모델 서브에이전트는 도구를 최소로 주고 역할을 좁히세요.
}

/* ===== [정답 5] 동기 vs 비동기 구분 ===== */
function solution5() {
  console.log("\n=== [정답 5] 동기 vs 비동기 ===");

  const candidates: Array<SubAgent | AsyncSubAgent> = [
    { name: "a", description: "조사한다", systemPrompt: "너는 조사원이다." },
    { name: "b", description: "조사한다", graphId: "researcher" },
    { name: "c", description: "코딩한다", graphId: "coder", url: "https://example.langsmith.dev" },
    { name: "d", description: "요약한다", systemPrompt: "너는 요약가다.", model: CHEAP_MODEL },
  ];

  for (const c of candidates) {
    show(c.name, isAsyncSubAgent(c) ? "AsyncSubAgent (비동기)" : "SubAgent (동기)");
  }

  // → 무엇이 둘을 가르나요?
  //   `graphId` 필드의 존재입니다.
  //   - SubAgent      = systemPrompt 로 "여기서 즉석에서" 만들어지는 에이전트. task 로 부르고, 부모가 기다립니다.
  //   - AsyncSubAgent = graphId 로 "Agent Protocol 서버에 이미 배포된" 그래프를 가리킵니다.
  //                     start_async_task 로 띄우면 즉시 task id 가 오고, 부모는 안 기다립니다.
  //                     url 이 있으면 원격, 없으면 같은 배포 안(ASGI).
  //
  // ⚠️ 함정: 비동기는 "병렬" 과 다릅니다.
  //    동기 서브에이전트도 부모가 한 메시지에서 task 를 여러 번 부르면 "병렬로" 돕니다.
  //    다만 부모는 전부 끝날 때까지 기다립니다 (블로킹).
  //    비동기의 진짜 가치는 "부모가 안 기다리는 것" — 즉 사용자와 계속 대화하면서
  //    백그라운드로 몇 분짜리 작업을 굴리는 것입니다.
  //    "빨리 하고 싶어서" 비동기를 쓰는 거라면 잘못 고른 것입니다. 그냥 병렬 task 를 쓰세요.
}

/* ===== [정답 6] 부모 컨텍스트를 못 본다 ===== */
async function solution6() {
  console.log("\n=== [정답 6] 서브에이전트는 부모 대화를 못 본다 ===");

  if (!process.env.ANTHROPIC_API_KEY) {
    console.log("  ANTHROPIC_API_KEY 가 없어 건너뜁니다.");
    return;
  }

  const translator: SubAgent = {
    name: "translator",
    description: "주어진 문장을 지정된 언어로 번역한다. 대상 언어를 반드시 명시해서 부를 것.",
    systemPrompt: "너는 번역가다. 요청받은 대상 언어로 번역하라. 대상 언어가 없으면 되물어라.",
  };

  const messages = [
    { role: "user" as const, content: "나는 앞으로 모든 답변을 일본어로 받고 싶어. 기억해줘." },
    { role: "assistant" as const, content: "알겠습니다. 앞으로 일본어로 답변드리겠습니다." },
    { role: "user" as const, content: "'안녕하세요, 반갑습니다' 를 번역해줘." },
  ];

  // (1) 고장난 버전 — 부모가 맥락을 안 넘깁니다.
  const broken = createDeepAgent({
    model: MODEL,
    backend: new StateBackend(),
    subagents: [translator],
    systemPrompt: "너는 조수다. 번역이 필요하면 translator 를 불러라.",
  });

  const r1 = await broken.invoke({ messages });
  console.log("\n  --- (1) 고장난 버전 (매번 다릅니다) ---");
  console.log("  " + String(r1.messages.at(-1)?.content).split("\n").join("\n  "));

  // (2) 고친 버전 — 부모가 task 프롬프트에 맥락을 "다 담도록" 지시합니다.
  const fixed = createDeepAgent({
    model: MODEL,
    backend: new StateBackend(),
    subagents: [translator],
    systemPrompt:
      "너는 조수다. 번역이 필요하면 translator 서브에이전트를 불러라.\n" +
      "**중요**: 서브에이전트는 지금까지의 대화를 전혀 볼 수 없다. 완전히 백지 상태에서 시작한다.\n" +
      "그러므로 task 의 description 에는 서브에이전트가 일을 끝내는 데 필요한 모든 것을 담아야 한다:\n" +
      "- 번역할 원문 전체\n" +
      "- 대상 언어 (대화에서 사용자가 지정한 언어를 네가 직접 찾아서 명시할 것)\n" +
      "- 원하는 출력 형식\n" +
      "'사용자가 아까 말한 언어로' 같은 표현은 서브에이전트에게 아무 의미가 없다.",
  });

  const r2 = await fixed.invoke({ messages });
  console.log("\n  --- (2) 고친 버전 (매번 다릅니다) ---");
  console.log("  " + String(r2.messages.at(-1)?.content).split("\n").join("\n  "));

  // 부모가 실제로 자식에게 뭘 넘겼는지 봅시다 — 이게 이 문제의 핵심입니다.
  const taskArgs = r2.messages.flatMap((m) => {
    const calls = (m as { tool_calls?: Array<{ name: string; args: Record<string, unknown> }> }).tool_calls ?? [];
    return calls.filter((c) => c.name === "task").map((c) => c.args);
  });
  console.log("\n  --- 부모가 자식에게 넘긴 프롬프트 ---");
  for (const a of taskArgs) show("description", a.description, 400);

  // → translator 가 무슨 언어로 번역했나요? 왜 그런가요?
  //   (1) 에서는 대개 영어로 번역합니다. "일본어로 받고 싶어" 는 부모 대화에만 있고,
  //       translator 는 그 대화를 못 보기 때문입니다. translator 가 받는 것은
  //       "'안녕하세요, 반갑습니다' 를 번역해줘" 라는 문장 하나뿐이고,
  //       대상 언어가 없으니 기본값(영어)으로 갑니다.
  //   (2) 에서는 부모가 대화를 읽고 "일본어로" 를 직접 프롬프트에 박아 넣으므로 제대로 됩니다.
  //
  // ⚠️ 이게 서브에이전트 최대의 함정입니다. 그리고 "에러가 안 납니다."
  //    번역은 됐고, 결과도 그럴듯합니다. 언어만 틀렸습니다.
  //    부모는 자식을 믿으므로 검증도 안 합니다.
  //
  // 💡 원칙: task 의 description 은 "처음 만난 외주 업체에게 보내는 작업 지시서" 라고 생각하세요.
  //    그 사람은 우리 회사의 맥락을 하나도 모릅니다. 필요한 건 전부 문서에 적어야 합니다.
}

/* ===== [정답 7] 병렬 리서치 ===== */
async function solution7() {
  console.log("\n=== [정답 7] 병렬 리서치 ===");

  if (!process.env.ANTHROPIC_API_KEY) {
    console.log("  ANTHROPIC_API_KEY 가 없어 건너뜁니다.");
    return;
  }

  const mockSearch = tool(
    async ({ query }) => {
      const db: Record<string, string> = {
        typescript: "TypeScript: JS 의 상위집합. 정적 타입, 컴파일 필요. 생태계 거대.",
        rust: "Rust: 소유권 모델로 GC 없이 메모리 안전. 학습 곡선 가파름. 성능 최상.",
        go: "Go: 단순한 문법, 빠른 컴파일, goroutine 동시성. GC 있음.",
      };
      const hit = Object.entries(db).find(([k]) => query.toLowerCase().includes(k));
      return hit ? hit[1] : `"${query}" 자료 없음`;
    },
    {
      name: "web_search",
      description: "기술 자료를 검색한다",
      schema: z.object({ query: z.string().describe("검색어") }),
    },
  );

  const researcher: SubAgent = {
    name: "researcher",
    // description 에 "병렬" 지시를 넣는 것이 핵심입니다. 부모는 이것만 봅니다.
    description:
      "기술 하나를 조사해 특징과 트레이드오프를 정리한다. " +
      "여러 기술을 비교해야 하면 반드시 기술 하나당 하나씩 '병렬로' 호출할 것. " +
      "조사 결과를 지정된 파일 경로에 저장하고, 저장 경로와 한 줄 요약만 반환한다.",
    systemPrompt:
      "너는 기술 조사원이다. web_search 로 자료를 찾아 특징/장점/단점을 정리하고 " +
      "지정된 경로에 write_file 로 저장하라.\n" +
      "너는 부모의 대화를 볼 수 없다. 프롬프트에 주어진 정보만으로 판단하라.\n" +
      "최종 답변에는 조사 전문을 넣지 말고 '저장 경로 + 한 줄 요약' 만 적어라.",
    tools: [mockSearch],
    model: CHEAP_MODEL, // 조사는 싼 모델
  };

  const agent = createDeepAgent({
    model: MODEL, // 종합은 비싼 모델
    backend: new StateBackend(),
    subagents: [researcher],
    systemPrompt:
      "너는 기술 선임이다. 비교 요청을 받으면 researcher 서브에이전트를 대상 기술마다 하나씩 " +
      "'병렬로' 띄워라 — 한 메시지 안에서 task 를 여러 번 호출하면 병렬로 실행된다.\n" +
      "각 서브에이전트에게는 조사할 기술명과 저장할 파일 경로(/research/<기술명>.md)를 명시하라.\n" +
      "모두 끝나면 각 파일을 read_file 로 읽어 최종 비교표를 만들어라.",
  });

  const result = await agent.invoke({
    messages: [{ role: "user", content: "TypeScript, Rust, Go 를 백엔드 언어로 비교해줘." }],
  });

  console.log("\n  --- 최종 비교표 (매번 다릅니다) ---");
  console.log("  " + String(result.messages.at(-1)?.content).split("\n").join("\n  "));

  // task 호출 횟수 세기
  const taskCalls = result.messages.flatMap((m) => {
    const calls = (m as { tool_calls?: Array<{ name: string; args: Record<string, unknown> }> }).tool_calls ?? [];
    return calls.filter((c) => c.name === "task");
  });
  console.log(`\n  task 호출 횟수: ${taskCalls.length} (기대: 3)`);

  // 한 메시지에 여러 task 가 들어 있으면 병렬로 실행된 것입니다.
  const perMessage = result.messages.map((m) => {
    const calls = (m as { tool_calls?: Array<{ name: string }> }).tool_calls ?? [];
    return calls.filter((c) => c.name === "task").length;
  }).filter((n) => n > 0);
  show("메시지당 task 호출 수", perMessage);
  console.log("  → [3] 처럼 한 메시지에 3개면 병렬. [1,1,1] 이면 순차입니다.");

  const files = (result as { files?: Record<string, unknown> }).files;
  show("서브에이전트들이 남긴 파일", files ? Object.keys(files) : "(없음)");

  // ⚠️ 함정: 병렬 서브에이전트가 "같은 파일" 에 쓰면 서로를 덮어씁니다.
  //    그래서 위에서 경로를 /research/<기술명>.md 로 "기술마다 다르게" 지정했습니다.
  //    만약 전부 /research/result.md 에 쓰라고 했다면 마지막에 끝난 하나만 남고
  //    나머지는 조용히 사라집니다 — 에러 없이.
  //
  // ⚠️ 함정 2: 서브에이전트가 또 서브에이전트를 부르면 비용이 곱해집니다.
  //    researcher 에게 tools 를 명시했기 때문에(mockSearch 만) task 도구가 없습니다.
  //    tools 를 생략했다면 부모 도구를 물려받아 자식이 또 task 를 부를 수 있습니다.
  //    3개 × 3개 = 9개 에이전트가 되는 식이죠. 서브에이전트의 tools 는 좁게 주세요.
}

async function main() {
  solution2();
  solution3();
  solution4();
  solution5();
  await solution6();
  await solution7();
}

main().catch((e) => {
  console.error(e);
  process.exit(1);
});