オーケストレーションを手放す — GitHub Copilot SDK でツールを足すだけの文書レビューエージェントを作る

messages = [systemPrompt, userRequest]
loop:
    response = llm.call(messages, tools)        # モデルに問い合わせ
    if response.tool_calls:                      # ツールを呼びたいと言ってきたら
        for call in response.tool_calls:
            result = dispatch(call)              # 自前でツールを実行
            messages.append(toolResult(result))  # 結果を会話に戻す
    else:
        return response.content                  # ツール不要なら完了

import { CopilotClient } from "@github/copilot-sdk";
 
const client = new CopilotClient();
await client.start();
const session = await client.createSession({ model: "gpt-5" });
 
const response = await session.sendAndWait({ prompt: "2 + 2 は？" });
console.log(response?.data.content);
 
await client.stop();

// Azure OpenAI を自前モデルとして使う
const session = await client.createSession({
    model: "gpt-5",                 // カスタムプロバイダ使用時は必須
    provider: {
        type: "azure",              // *.openai.azure.com のエンドポイントは "azure"
        baseUrl: "https://my-resource.openai.azure.com", // リソースのホスト（/openai/... のパスは付けない）
        apiKey: process.env.AZURE_OPENAI_KEY,
        azure: { apiVersion: "2024-10-21" },
    },
});
 
// または Ollama でローカルモデルを使う（API キー不要）
const local = await client.createSession({
    model: "deepseek-coder-v2:16b",
    provider: { type: "openai", baseUrl: "http://localhost:11434/v1" },
});

copilot-doc-reviewer/
├── package.json
├── tsconfig.json
├── .env.example
├── glossary.json            # 用語統一チェック用の正規表記辞書
├── docs/                    # レビュー対象のドキュメント置き場
├── reviews/                 # レビュー結果の出力先
├── src/
│   ├── server.ts            # Express + SSE サーバ
│   ├── tools.ts             # 5 つのカスタムツール
│   ├── permissions.ts       # 権限ハンドラ（サンドボックス）
│   └── prompts.ts           # レビュー指示のシステムメッセージ
└── public/
    └── index.html           # ブラウザ UI（バニラ JS）

npm install @github/copilot-sdk express zod
npm install -D typescript tsx @types/express @types/node

// src/tools.ts
import { defineTool } from "@github/copilot-sdk";
import { z } from "zod";
import { promises as fs } from "node:fs";
import path from "node:path";
 
// docs/ と reviews/ をルートに固定し、外に出られないようにする
const DOCS_ROOT = path.resolve("docs");
const REVIEWS_ROOT = path.resolve("reviews");
 
// パストラバーサル対策: 解決後のパスがルート配下にあることを保証する
function resolveWithin(root: string, target: string): string {
  const resolved = path.resolve(root, target);
  const rel = path.relative(root, resolved);
  if (rel.startsWith("..") || path.isAbsolute(rel)) {
    throw new Error(`許可されていないパスです: ${target}`);
  }
  return resolved;
}
 
type Emit = (event: { tool: string; detail: string }) => void;
 
export function createReviewTools(emit: Emit) {
  return [
    defineTool("list_documents", {
      description: "レビュー対象の docs/ 配下にあるドキュメントの一覧を返す",
      parameters: z.object({}),
      handler: async () => {
        const entries = await fs.readdir(DOCS_ROOT, { recursive: true });
        const files = entries.filter((f) => f.endsWith(".md") || f.endsWith(".mdx"));
        emit({ tool: "list_documents", detail: `${files.length} 件のドキュメントを検出` });
        return { files };
      },
    }),
 
    defineTool("read_document", {
      description: "指定したドキュメントの本文を読み込んで返す",
      parameters: z.object({
        filePath: z.string().describe("docs/ からの相対パス"),
      }),
      handler: async ({ filePath }) => {
        const abs = resolveWithin(DOCS_ROOT, filePath);
        const content = await fs.readFile(abs, "utf8");
        emit({ tool: "read_document", detail: `${filePath} を読み込み（${content.length} 文字）` });
        return { filePath, content };
      },
    }),
 
    defineTool("check_links", {
      description: "本文中の HTTP(S) リンクが生きているかを確認し、到達不能なものを返す",
      parameters: z.object({
        content: z.string().describe("チェック対象の本文"),
      }),
      handler: async ({ content }) => {
        const urls = [...new Set([...content.matchAll(/https?:\/\/[^\s)\]]+/g)].map((m) => m[0]))];
        const broken: { url: string; status: string }[] = [];
        for (const url of urls) {
          try {
            const controller = new AbortController();
            const timer = setTimeout(() => controller.abort(), 5000);
            const res = await fetch(url, { method: "HEAD", signal: controller.signal });
            clearTimeout(timer);
            if (!res.ok) broken.push({ url, status: String(res.status) });
          } catch {
            broken.push({ url, status: "unreachable" });
          }
        }
        emit({ tool: "check_links", detail: `${urls.length} 件中 ${broken.length} 件が到達不能` });
        return { checked: urls.length, broken };
      },
    }),
 
    defineTool("check_terminology", {
      description: "glossary.json の正規表記に照らして表記ゆれを検出する",
      parameters: z.object({
        content: z.string().describe("チェック対象の本文"),
      }),
      handler: async ({ content }) => {
        const glossary: Record<string, string[]> = JSON.parse(
          await fs.readFile("glossary.json", "utf8"),
        );
        const hits: { canonical: string; found: string }[] = [];
        for (const [canonical, variants] of Object.entries(glossary)) {
          for (const variant of variants) {
            if (content.includes(variant)) hits.push({ canonical, found: variant });
          }
        }
        emit({ tool: "check_terminology", detail: `${hits.length} 件の表記ゆれ候補` });
        return { issues: hits };
      },
    }),
 
    defineTool("save_review", {
      description: "完成したレビュー結果を reviews/ に Markdown として保存する",
      parameters: z.object({
        fileName: z.string().describe("保存するファイル名（例: report-2026-06-11.md）"),
        markdown: z.string().describe("レビュー結果の Markdown 本文"),
      }),
      handler: async ({ fileName, markdown }) => {
        const abs = resolveWithin(REVIEWS_ROOT, fileName);
        await fs.mkdir(path.dirname(abs), { recursive: true });
        await fs.writeFile(abs, markdown, "utf8");
        emit({ tool: "save_review", detail: `${fileName} に保存` });
        return { saved: fileName };
      },
    }),
  ];
}

// src/permissions.ts
import type { PermissionRequest, PermissionRequestResult } from "@github/copilot-sdk";
 
export function reviewPermissionHandler(
  request: PermissionRequest,
): PermissionRequestResult {
  switch (request.kind) {
    case "custom-tool":
      // 自分で定義した安全なツールだけを許可する
      return { kind: "approve-once" };
    default:
      // シェル・読み取り・書き込み・URL 取得・MCP など、組み込みツールはすべて拒否
      return {
        kind: "reject",
        feedback: `この操作（${request.kind}）はレビューエージェントでは許可されていません。`,
      };
  }
}

// src/server.ts
import express from "express";
import { CopilotClient } from "@github/copilot-sdk";
import { createReviewTools } from "./tools.js";
import { reviewPermissionHandler } from "./permissions.js";
import { REVIEW_SYSTEM_MESSAGE } from "./prompts.js";
 
const app = express();
app.use(express.json());
app.use(express.static("public"));
 
// クライアントは起動時に 1 つだけ生成する
const client = new CopilotClient();
await client.start();
 
app.post("/api/review", async (req, res) => {
  const { instruction } = req.body as { instruction: string };
 
  // SSE ヘッダ
  res.setHeader("Content-Type", "text/event-stream");
  res.setHeader("Cache-Control", "no-cache");
  res.setHeader("Connection", "keep-alive");
 
  const send = (type: string, data: unknown) =>
    res.write(`data: ${JSON.stringify({ type, data })}\n\n`);
 
  // このリクエスト専用の emit を閉じ込めたツールを生成
  const tools = createReviewTools((event) => send("tool", event));
 
  const session = await client.createSession({
    model: "gpt-5",
    streaming: true,
    tools,
    systemMessage: { content: REVIEW_SYSTEM_MESSAGE },
    onPermissionRequest: reviewPermissionHandler,
  });
 
  // レビュー報告をストリーミング
  session.on("assistant.message_delta", (event) => {
    send("delta", { text: event.data.deltaContent });
  });
  // 権限拒否などのエラーを通知
  session.on("session.error", (event) => {
    send("error", { message: event.data.message });
  });
 
  try {
    await session.sendAndWait({ prompt: instruction });
    send("done", {});
  } catch (err) {
    send("error", { message: err instanceof Error ? err.message : String(err) });
  } finally {
    await session.disconnect();
    res.end();
  }
});
 
app.listen(3000, () => console.log("http://localhost:3000 で待機中"));

// src/prompts.ts
export const REVIEW_SYSTEM_MESSAGE = `
あなたは技術文書のレビュアーです。与えられたツールを使ってドキュメントをレビューしてください。
 
レビューの観点:
- リンク切れ（check_links を使う）
- 用語の表記ゆれ（check_terminology を使う）
- 文章の明確さ・構成・誤りの可能性
 
進め方:
1. 必要なドキュメントを list_documents / read_document で把握する
2. 各観点をツールで検証する
3. 最後に save_review でレビュー結果を Markdown として保存する
 
報告は次の構成で、簡潔に日本語で書くこと:
## 要約
## 重大な問題
## 軽微な指摘
## 確認した項目
`;

<!-- public/index.html -->
<!DOCTYPE html>
<html lang="ja">
  <head>
    <meta charset="utf-8" />
    <title>文書レビューエージェント</title>
    <style>
      body { font-family: system-ui, sans-serif; max-width: 760px; margin: 2rem auto; }
      #timeline div { padding: 4px 8px; border-left: 3px solid #6366f1; margin: 4px 0; }
      #report { white-space: pre-wrap; background: #f6f8fa; padding: 1rem; border-radius: 8px; }
    </style>
  </head>
  <body>
    <h1>文書レビューエージェント</h1>
    <input id="instruction" size="60" value="docs 配下をレビューして report.md に保存して" />
    <button id="run">レビュー実行</button>
    <h2>ツールの実行</h2>
    <div id="timeline"></div>
    <h2>レビュー報告</h2>
    <div id="report"></div>
    <script>
      const $ = (id) => document.getElementById(id);
      $("run").onclick = async () => {
        $("timeline").innerHTML = "";
        $("report").textContent = "";
        const res = await fetch("/api/review", {
          method: "POST",
          headers: { "Content-Type": "application/json" },
          body: JSON.stringify({ instruction: $("instruction").value }),
        });
        const reader = res.body.getReader();
        const decoder = new TextDecoder();
        let buffer = "";
        while (true) {
          const { value, done } = await reader.read();
          if (done) break;
          buffer += decoder.decode(value, { stream: true });
          const parts = buffer.split("\n\n");
          buffer = parts.pop() ?? "";
          for (const part of parts) {
            if (!part.startsWith("data: ")) continue;
            const evt = JSON.parse(part.slice(6));
            if (evt.type === "tool") {
              const div = document.createElement("div");
              div.textContent = `🔧 ${evt.data.tool}: ${evt.data.detail}`;
              $("timeline").appendChild(div);
            } else if (evt.type === "delta") {
              $("report").textContent += evt.data.text;
            } else if (evt.type === "error") {
              $("report").textContent += `\n[エラー] ${evt.data.message}`;
            }
          }
        }
      };
    </script>
  </body>
</html>

{
  "type": "module",
  "scripts": { "dev": "tsx src/server.ts" }
}

{
  "GitHub": ["Github", "GITHUB"],
  "TypeScript": ["Typescript", "type script"],
  "JavaScript": ["Javascript", "java script"]
}

npm install
npm run dev   # → http://localhost:3000 を開く