サブエージェントとは何か - 独立した文脈を持つ並列ワーカーの仕組みと使いどころ

import java.util.List;
import java.util.stream.Collectors;

public final class ComparisonPrompts {
  private ComparisonPrompts() {}

  public record DocumentInput(String title, String author, String genre, String fullText) {}

  public record DocumentSummary(String title, String summary) {}

  public static String buildSingleAgentBatchAnalysisPrompt(List<DocumentInput> documents) {
    String documentText =
        documents.stream()
            .map(
                doc ->
                    """
                    # 文献: %s

                    著者: %s
                    ジャンル: %s

                    ## 本文

                    %s
                    """
                        .formatted(
                            doc.title(),
                            emptyIfNull(doc.author()),
                            emptyIfNull(doc.genre()),
                            emptyIfNull(doc.fullText())))
            .collect(Collectors.joining("\n\n---\n\n"));

    return """
        あなたは複数文献の横断分析を行うシングルエージェントです。

        以下に全ての文献本文を一括で提示します。
        このプロンプト内の文献本文だけを根拠に横断分析してください。

        目的は、単一文献の要約ではなく、
        複数文献をまたいで見える共通点・相違点・傾向・構造を明らかにすることです。

        ## 分析観点

        1. 共通テーマ
        2. 頻出概念
        3. 共通する構造
        4. 文献ごとの差異
        5. 著者・語り手・立場による違い
        6. 主張の共通点
        7. 主張の相違点
        8. 時代背景や文脈による違い
        9. 読者への影響
        10. 特徴的なパターン
        11. 全体から得られる知見
        12. 今後さらに調べるべき論点

        ## 出力形式

        ## 1. 全体要約

        ## 2. 共通点

        ## 3. 相違点

        ## 4. 文献別特徴一覧

        | 文献 | 主題 | 主な特徴 | 独自性 | 他文献との差分 |
        |---|---|---|---|---|

        ## 5. 頻出テーマ

        ## 6. 頻出概念

        ## 7. 構造上の共通点

        ## 8. 構造上の違い

        ## 9. 横断的な知見

        ## 10. 結論

        ## 注意

        - 推測ではなく、提示された文献本文の内容に基づいて分析してください。
        - 本文に根拠がない内容は断定しないでください。
        - 文献紹介ではなく、横断分析をしてください。
        - 日本語で出力してください。

        # 文献本文

        %s
        """.formatted(documentText);
  }

  public static String buildSubAgentSummaryPrompt(DocumentInput doc) {
    return """
        あなたは文献分析サブエージェントです。

        担当する文献は1件のみです。

        後続の親エージェントが複数文献を横断分析できるよう、
        重要情報を抽出して構造化要約を作成してください。

        ## 重要な方針

        - 他文献との比較はしないでください。
        - この文献単体から読み取れる内容だけを書いてください。
        - 親エージェントが横断分析しやすいように、簡潔かつ情報密度高くまとめてください。
        - 事実、解釈、注目点を分けてください。
        - 不明な項目は無理に補完せず「不明」と書いてください。
        - 日本語で出力してください。

        ## 出力形式

        ## 1. 基本情報

        - タイトル:
        - 著者:
        - ジャンル:
        - 想定読者:

        ## 2. 全体要約

        ## 3. 主要トピック

        ## 4. 重要な概念

        ## 5. 重要な人物・主体・組織

        ## 6. 重要な出来事・論点

        ## 7. 主張・メッセージ

        ## 8. 構造上の特徴

        ## 9. 頻出テーマ

        ## 10. 頻出モチーフ

        ## 11. 文体・語り口・説明スタイル

        ## 12. 他文献との比較で重要になりそうな特徴

        ## 13. 注意すべき解釈ポイント

        ## 14. この文献を一言で表すと

        ## 文献情報

        タイトル: %s
        著者: %s
        ジャンル: %s

        ## 本文

        %s
        """
        .formatted(
            doc.title(),
            emptyIfNull(doc.author()),
            emptyIfNull(doc.genre()),
            emptyIfNull(doc.fullText()));
  }

  public static String buildParentCrossAnalysisPrompt(List<DocumentSummary> summaries) {
    String summaryText =
        summaries.stream()
            .map(
                s ->
                    """
                    # 文献: %s

                    %s
                    """
                        .formatted(s.title(), s.summary()))
            .collect(Collectors.joining("\n\n---\n\n"));

    return """
        あなたは複数文献の横断分析エージェントです。

        以下は、各サブエージェントが1文献ずつ読んで作成した構造化要約です。
        あなたは本文全文ではなく、これらの要約だけを使って横断分析してください。

        目的は、複数文献をまたいで見える
        共通点・相違点・傾向・構造・重要な示唆を明らかにすることです。

        ## 分析観点

        1. 共通テーマ
        2. 共通概念
        3. 相違点
        4. 特徴的なパターン
        5. 頻出モチーフ
        6. 構造上の共通点
        7. 構造上の差異
        8. 主張やメッセージの共通点
        9. 主張やメッセージの相違点
        10. 全体から得られる知見
        11. 重要な示唆
        12. 今後さらに調べるべき論点

        ## 出力形式

        ## 1. 全体要約

        ## 2. 共通点

        ## 3. 相違点

        ## 4. 文献別特徴表

        | 文献 | 主題 | 特徴 | 独自性 | 他文献との差分 |
        |---|---|---|---|---|

        ## 5. 頻出テーマ

        ## 6. 頻出概念

        ## 7. 構造上の共通点

        ## 8. 構造上の差異

        ## 9. 横断的な発見

        ## 10. 重要な示唆

        ## 11. 結論

        ## 注意

        - 要約に存在しない内容を推測で補わないでください。
        - 根拠は要約に含まれる情報に限定してください。
        - 根拠が弱い場合は「要約から見る限り」と明記してください。
        - 文献紹介ではなく、横断分析をしてください。
        - 日本語で出力してください。

        # 文献要約

        %s
        """.formatted(summaryText);
  }

  private static String emptyIfNull(String value) {
    return value == null ? "" : value;
  }
}

import com.anthropic.client.AnthropicClient;
import com.anthropic.client.okhttp.AnthropicOkHttpClient;
import com.anthropic.models.messages.MessageCountTokensParams;
import com.google.common.base.Splitter;
import com.google.common.collect.ImmutableMap;
import com.google.genai.Client;
import com.openai.client.OpenAIClient;
import com.openai.client.okhttp.OpenAIOkHttpClient;
import com.openai.models.responses.inputtokens.InputTokenCountParams;
import java.io.IOException;
import java.nio.charset.Charset;
import java.nio.file.Files;
import java.nio.file.Path;
import java.util.Comparator;
import java.util.LinkedHashMap;
import java.util.List;
import java.util.Locale;
import java.util.Map;
import java.util.stream.Collectors;
import org.apache.commons.lang3.StringUtils;
import org.apache.commons.lang3.Strings;

public class TokenComparison {

  public record TokenReport(long totalInputTokens, long peakContextTokens) {}

  public enum Provider {
    OPENAI,
    ANTHROPIC,
    GEMINI
  }

  public record ProviderModel(Provider provider, String label, String modelId) {}

  public interface TokenCounter {
    long countInputTokens(String model, String prompt);
  }

  public static final class OpenAiInputTokenCounter implements TokenCounter {
    private final OpenAIClient client = OpenAIOkHttpClient.fromEnv();

    @Override
    public long countInputTokens(String model, String prompt) {
      return client
          .responses()
          .inputTokens()
          .count(InputTokenCountParams.builder().model(model).input(prompt).build())
          .inputTokens();
    }
  }

  public static final class AnthropicInputTokenCounter implements TokenCounter {
    private final AnthropicClient client = AnthropicOkHttpClient.fromEnv();

    @Override
    public long countInputTokens(String model, String prompt) {
      return client
          .messages()
          .countTokens(MessageCountTokensParams.builder().model(model).addUserMessage(prompt).build())
          .inputTokens();
    }
  }

  public static final class GeminiInputTokenCounter implements TokenCounter {
    private final Client client = new Client();

    @Override
    public long countInputTokens(String model, String prompt) {
      return client.models.countTokens(model, prompt, null).totalTokens().orElse(0);
    }
  }

  public static TokenReport measureSingleAgent(
      ProviderModel providerModel,
      List<ComparisonPrompts.DocumentInput> documents,
      TokenCounter tokenCounter) {
    var report = new MutableTokenReport();

    System.out.printf("%n=== シングルエージェント方式: %s / %s ===%n", providerModel.label(), providerModel.modelId());
    long tokens = tokenCounter.countInputTokens(providerModel.modelId(), ComparisonPrompts.buildSingleAgentBatchAnalysisPrompt(documents));
    report.addIndependentContext(tokens);
    System.out.printf("[single/batch-final] documents=%d inputTokens=%d peakContextTokens=%d%n", documents.size(), tokens, report.peakContextTokens);
    return report.toRecord();
  }

  public static TokenReport measureSubAgents(
      ProviderModel providerModel,
      List<ComparisonPrompts.DocumentInput> documents,
      List<ComparisonPrompts.DocumentSummary> summaries,
      TokenCounter tokenCounter) {
    var report = new MutableTokenReport();

    System.out.printf("%n=== サブエージェント方式: %s / %s ===%n", providerModel.label(), providerModel.modelId());
    for (ComparisonPrompts.DocumentInput doc : documents) {
      long tokens = tokenCounter.countInputTokens(providerModel.modelId(), ComparisonPrompts.buildSubAgentSummaryPrompt(doc));
      report.addIndependentContext(tokens);
      System.out.printf("[sub/summary] title=%s inputTokens=%d peakContextTokens=%d%n", doc.title(), tokens, report.peakContextTokens);
    }

    long parentTokens = tokenCounter.countInputTokens(providerModel.modelId(), ComparisonPrompts.buildParentCrossAnalysisPrompt(summaries));
    report.addIndependentContext(parentTokens);
    System.out.printf("[parent/final] inputTokens=%d peakContextTokens=%d%n", parentTokens, report.peakContextTokens);
    return report.toRecord();
  }

  private static final class MutableTokenReport {
    long totalInputTokens;
    long peakContextTokens;

    void addIndependentContext(long tokens) {
      totalInputTokens += tokens;
      peakContextTokens = Math.max(peakContextTokens, tokens);
    }

    TokenReport toRecord() {
      return new TokenReport(totalInputTokens, peakContextTokens);
    }
  }

  public static void printComparison(ProviderModel providerModel, TokenReport single, TokenReport sub) {
    System.out.printf("%n=== 比較結果: %s / %s ===%n", providerModel.label(), providerModel.modelId());
    System.out.printf("シングルエージェント totalInputTokens=%d%n", single.totalInputTokens());
    System.out.printf("シングルエージェント peakContextTokens=%d%n", single.peakContextTokens());
    System.out.printf("サブエージェント totalInputTokens=%d%n", sub.totalInputTokens());
    System.out.printf("サブエージェント peakContextTokens=%d%n", sub.peakContextTokens());
    System.out.printf("ピークコンテキスト削減率=%.2f%%%n", reductionRate(single, sub) * 100.0);
  }

  public static void printSummaryTable(Map<ProviderModel, TokenReport> singleReports, Map<ProviderModel, TokenReport> subReports) {
    System.out.println("\n=== モデル別サマリー ===");
    System.out.println("| Provider | Model | Single total | Single peak | Sub total | Sub peak | Peak reduction |");
    System.out.println("|---|---|---:|---:|---:|---:|---:|");
    singleReports.forEach(
        (pm, single) -> {
          TokenReport sub = subReports.get(pm);
          System.out.printf("| %s | %s | %d | %d | %d | %d | %.2f%% |%n", pm.label(), pm.modelId(), single.totalInputTokens(), single.peakContextTokens(), sub.totalInputTokens(), sub.peakContextTokens(), reductionRate(single, sub) * 100.0);
        });
  }

  private static double reductionRate(TokenReport single, TokenReport sub) {
    return single.peakContextTokens() == 0 ? 0.0 : 1.0 - (double) sub.peakContextTokens() / single.peakContextTokens();
  }

  private static TokenCounter tokenCounterFor(Provider provider) {
    return switch (provider) {
      case OPENAI -> new OpenAiInputTokenCounter();
      case ANTHROPIC -> new AnthropicInputTokenCounter();
      case GEMINI -> new GeminiInputTokenCounter();
    };
  }

  private static List<ComparisonPrompts.DocumentInput> loadDocumentsFromDirectory(Path documentsDir, Charset charset) throws IOException {
    try (var paths = Files.list(documentsDir)) {
      return paths
          .filter(Files::isRegularFile)
          .filter(path -> path.getFileName().toString().endsWith(".txt"))
          .sorted(Comparator.comparing(path -> path.getFileName().toString()))
          .map(path -> readDocumentFile(path, charset))
          .toList();
    }
  }

  private static ComparisonPrompts.DocumentInput readDocumentFile(Path file, Charset charset) {
    ParsedText parsed = parseFrontMatter(readString(file, charset));
    String body = parsed.body();
    String title = StringUtils.defaultIfBlank(parsed.metadata().get("title"), firstNonBlankLine(body));
    String author = StringUtils.defaultIfBlank(parsed.metadata().get("author"), nthNonBlankLine(body, 2));
    String genre = StringUtils.defaultString(parsed.metadata().get("genre"));
    return new ComparisonPrompts.DocumentInput(StringUtils.defaultIfBlank(title, stripExtension(file.getFileName().toString())), author, genre, body);
  }

  private static List<ComparisonPrompts.DocumentSummary> loadSummariesFromDirectory(Path summariesDir, List<ComparisonPrompts.DocumentInput> documents, Charset charset) throws IOException {
    Map<String, String> summaryByTitle;
    try (var paths = Files.list(summariesDir)) {
      summaryByTitle = paths
          .filter(Files::isRegularFile)
          .filter(path -> path.getFileName().toString().endsWith(".txt"))
          .sorted(Comparator.comparing(path -> path.getFileName().toString()))
          .map(path -> Map.entry(detectSummaryTitle(path, charset), parseFrontMatter(readString(path, charset)).body()))
          .collect(Collectors.toMap(Map.Entry::getKey, Map.Entry::getValue, (left, right) -> left));
    }

    return documents.stream()
        .map(doc -> new ComparisonPrompts.DocumentSummary(doc.title(), StringUtils.defaultIfBlank(summaryByTitle.get(doc.title()), fallbackSummary(doc.fullText()))))
        .toList();
  }

  private static List<ComparisonPrompts.DocumentSummary> buildFallbackSummaries(List<ComparisonPrompts.DocumentInput> documents) {
    return documents.stream().map(doc -> new ComparisonPrompts.DocumentSummary(doc.title(), fallbackSummary(doc.fullText()))).toList();
  }

  private static String fallbackSummary(String text) {
    return """
        ## 注意
        要約ファイルがないため、本文冒頭から仮要約を作っています。

        ## 仮要約
        %s
        """.formatted(StringUtils.abbreviate(text, 1_000));
  }

  private record ParsedText(Map<String, String> metadata, String body) {}

  private static ParsedText parseFrontMatter(String raw) {
    String normalized = StringUtils.replaceEach(raw, new String[] {"\r\n", "\r"}, new String[] {"\n", "\n"});
    if (!normalized.startsWith("---\n") || !normalized.substring(4).contains("\n---\n")) {
      return new ParsedText(Map.of(), normalized);
    }

    String metadataBlock = StringUtils.substringBetween(normalized, "---\n", "\n---\n");
    String body = StringUtils.substringAfter(normalized, "\n---\n");
    Map<String, String> metadata = Splitter.on('\n').omitEmptyStrings().splitToStream(metadataBlock)
        .map(line -> StringUtils.splitByWholeSeparator(line, ":", 2))
        .filter(parts -> parts.length == 2)
        .collect(ImmutableMap.toImmutableMap(parts -> parts[0].trim().toLowerCase(Locale.ROOT), parts -> parts[1].trim(), (left, right) -> left));
    return new ParsedText(metadata, body);
  }

  private static String detectSummaryTitle(Path path, Charset charset) {
    ParsedText parsed = parseFrontMatter(readString(path, charset));
    return StringUtils.firstNonBlank(parsed.metadata().get("title"), extractLabeledValue(parsed.body(), "タイトル"), firstNonHeadingLine(parsed.body()), stripExtension(path.getFileName().toString()));
  }

  private static String extractLabeledValue(String text, String label) {
    return Splitter.on('\n').splitToStream(StringUtils.defaultString(text))
        .map(line -> Strings.CS.removeStart(Strings.CS.removeStart(line.trim(), "- "), "* "))
        .filter(line -> Strings.CI.startsWithAny(line, label + ":", label + "："))
        .map(line -> line.replaceFirst("^[^:：]*[:：]", "").trim())
        .findFirst()
        .orElse("");
  }

  private static String firstNonBlankLine(String text) {
    return nthNonBlankLine(text, 1);
  }

  private static String firstNonHeadingLine(String text) {
    return Splitter.on('\n').trimResults().omitEmptyStrings().splitToStream(StringUtils.defaultString(text)).filter(line -> !line.startsWith("#")).findFirst().orElse("");
  }

  private static String nthNonBlankLine(String text, int n) {
    return Splitter.on('\n').trimResults().omitEmptyStrings().splitToStream(StringUtils.defaultString(text)).skip(n - 1L).findFirst().orElse("");
  }

  private static String stripExtension(String fileName) {
    return StringUtils.substringBeforeLast(fileName, ".");
  }

  private static String readString(Path path, Charset charset) {
    try {
      return Files.readString(path, charset);
    } catch (IOException e) {
      throw new RuntimeException(e);
    }
  }

  public static void main(String[] args) throws IOException {
    List<ProviderModel> providerModels = List.of(
        new ProviderModel(Provider.OPENAI, "GPT", "gpt-5.5"),
        new ProviderModel(Provider.ANTHROPIC, "Claude Opus", "claude-opus-4-8"),
        new ProviderModel(Provider.GEMINI, "Gemini", "gemini-3.5-flash"));

    Path baseDir = Path.of(System.getProperty("user.dir")).resolve("ルートディレクトリを指定");
    Path documentsDir = args.length >= 1 ? Path.of(args[0]) : baseDir.resolve("documents");
    Path summariesDir = args.length >= 2 ? Path.of(args[1]) : baseDir.resolve("summaries");
    Charset documentsCharset = args.length >= 3 ? Charset.forName(args[2]) : Charset.forName("Shift_JIS");
    Charset summariesCharset = args.length >= 4 ? Charset.forName(args[3]) : Charset.forName("UTF-8");

    List<ComparisonPrompts.DocumentInput> documents = loadDocumentsFromDirectory(documentsDir, documentsCharset);
    List<ComparisonPrompts.DocumentSummary> summaries = Files.isDirectory(summariesDir) ? loadSummariesFromDirectory(summariesDir, documents, summariesCharset) : buildFallbackSummaries(documents);

    System.out.printf("Loaded documents: %d%nDocuments charset: %s%nSummaries charset: %s%n", documents.size(), documentsCharset, summariesCharset);

    var singleReports = new LinkedHashMap<ProviderModel, TokenReport>();
    var subReports = new LinkedHashMap<ProviderModel, TokenReport>();
    for (ProviderModel providerModel : providerModels) {
      TokenCounter counter = tokenCounterFor(providerModel.provider());
      TokenReport single = measureSingleAgent(providerModel, documents, counter);
      TokenReport sub = measureSubAgents(providerModel, documents, summaries, counter);
      printComparison(providerModel, single, sub);
      singleReports.put(providerModel, single);
      subReports.put(providerModel, sub);
    }
    printSummaryTable(singleReports, subReports);
  }
}