カスタムエージェントとサブエージェントオーケストレーション

メモ

          Copilot SDK は現在 テクニカル プレビューです。 機能と可用性は変更される場合があります。

カスタムエージェントは、セッションにアタッチする軽量のエージェント定義です。各エージェントには、独自のシステムプロンプト、ツールの制限、およびオプションの MCP サーバーがあります。ユーザーの要求がエージェントの専門知識と一致すると、 Copilot SDK ランタイムは自動的にそのエージェントにサブエージェントとして委任します。これは、ライフサイクルイベントを親セッションにストリーミングバックしながら、分離されたコンテキストで実行します。委任フローの視覚的な概要については、 github/copilot-sdk リポジトリを参照してください。

概念	説明

          **カスタム エージェント** | 独自のプロンプトとツール セットを含む名前付きエージェント構成 |

カスタムエージェントの定義

セッションの作成時に customAgents 渡します。少なくとも、各エージェントには name と promptが必要です。

import { CopilotClient } from "@github/copilot-sdk";

const client = new CopilotClient();
await client.start();

const session = await client.createSession({
    model: "gpt-4.1",
    customAgents: [
        {
            name: "researcher",
            displayName: "Research Agent",
            description: "Explores codebases and answers questions using read-only tools",
            tools: ["grep", "glob", "view"],
            prompt: "You are a research assistant. Analyze code and answer questions. Do not modify any files.",
        },
        {
            name: "editor",
            displayName: "Editor Agent",
            description: "Makes targeted code changes",
            tools: ["view", "edit", "bash"],
            prompt: "You are a code editor. Make minimal, surgical changes to files as requested.",
        },
    ],
    onPermissionRequest: async () => ({ kind: "approved" }),
});

Python、Go、.NET の例については、 github/copilot-sdk リポジトリを参照してください。

構成参照

財産	タイプ	必須	説明
`name`	`string`	✅	エージェントのユニークID
`displayName`	`string`
イベントに表示される人間が判読できる名前
`description`	`string`
エージェントが実行すること - ランタイムがエージェントを選択するのを支援します
`tools`

          `string[]` または `null` |

ヒント

適切な description は、ランタイムがユーザーの意図を適切なエージェントと照合するのに役立ちます。エージェントの専門知識と機能について具体的に説明します。

エージェントごとの構成に加えて、agentの**** を設定して、セッションの開始時にアクティブなカスタムエージェントを事前に選択できます。

セッション構成プロパティ	タイプ	説明
`agent`	`string`	セッションの作成時に事前に選択するカスタムエージェントの名前。

          `name`の`customAgents`と一致する必要があります。 |

セッション作成時のエージェントの選択

セッション構成で agent を渡して、セッションの開始時にアクティブにするカスタムエージェントを事前に選択できます。この値は、nameで定義されているいずれかのエージェントのcustomAgentsと一致する必要があります。

const session = await client.createSession({
    customAgents: [
        {
            name: "researcher",
            prompt: "You are a research assistant. Analyze code and answer questions.",
        },
        {
            name: "editor",
            prompt: "You are a code editor. Make minimal, surgical changes.",
        },
    ],
    agent: "researcher", // Pre-select the researcher agent
});

Python、Go、.NET の例については、 github/copilot-sdk リポジトリを参照してください。

サブエージェントの委任のしくみ

カスタムエージェントとのセッションにプロンプトを送信すると、ランタイムはサブエージェントに委任するかどうかを評価します。

       **意図の照合** - ランタイムは、ユーザーのプロンプトを各エージェントの`name`および`description`と比較し分析します。

       **エージェントの選択** - 一致するものが見つかり、 `infer` が `false`されていない場合、ランタイムはエージェントを選択します。

       **分離実行** - サブエージェントは、独自のプロンプトと制限付きツール セットを使用して実行されます

       **イベント ストリーミング** - ライフサイクル イベント (`subagent.started`、 `subagent.completed`など) が親セッションにストリームバックされます

       **結果の統合** - サブエージェントの出力が親エージェントの応答に組み込まれます

推論の制御

既定では、すべてのカスタムエージェントを自動選択 (infer: true) で使用できます。 infer: falseを設定して、ランタイムがエージェントを自動選択できないようにします。明示的なユーザー要求によってのみ呼び出すエージェントに役立ちます。

{
    name: "dangerous-cleanup",
    description: "Deletes unused files and dead code",
    tools: ["bash", "edit", "view"],
    prompt: "You clean up codebases by removing dead code and unused files.",
    infer: false, // Only invoked when user explicitly asks for this agent
}

サブエージェントイベントの監視

サブエージェントを実行すると、親セッションはライフサイクルイベントを生成します。これらのイベントをサブスクライブして、エージェントアクティビティを視覚化する UI を構築します。

イベントの種類

イベント	次の場合に生成されます	データ
`subagent.selected`	ランタイムがタスクのエージェントを選択する

          `agentName`、`agentDisplayName`、`tools` |

イベントに登録する

session.on((event) => {
    switch (event.type) {
        case "subagent.started":
            console.log(`▶ Sub-agent started: ${event.data.agentDisplayName}`);
            console.log(`  Description: ${event.data.agentDescription}`);
            console.log(`  Tool call ID: ${event.data.toolCallId}`);
            break;

        case "subagent.completed":
            console.log(`✅ Sub-agent completed: ${event.data.agentDisplayName}`);
            break;

        case "subagent.failed":
            console.log(`❌ Sub-agent failed: ${event.data.agentDisplayName}`);
            console.log(`  Error: ${event.data.error}`);
            break;

        case "subagent.selected":
            console.log(`🎯 Agent selected: ${event.data.agentDisplayName}`);
            console.log(`  Tools: ${event.data.tools?.join(", ") ?? "all"}`);
            break;

        case "subagent.deselected":
            console.log("↩ Agent deselected, returning to parent");
            break;
    }
});

const response = await session.sendAndWait({
    prompt: "Research how authentication works in this codebase",
});

Python、Go、.NET の例については、 github/copilot-sdk リポジトリを参照してください。

エージェントツリー UI の構築

サブエージェントイベントには、実行ツリーを再構築できる toolCallId フィールドが含まれます。エージェントアクティビティを追跡するためのパターンを次に示します。

interface AgentNode {
    toolCallId: string;
    name: string;
    displayName: string;
    status: "running" | "completed" | "failed";
    error?: string;
    startedAt: Date;
    completedAt?: Date;
}

const agentTree = new Map<string, AgentNode>();

session.on((event) => {
    if (event.type === "subagent.started") {
        agentTree.set(event.data.toolCallId, {
            toolCallId: event.data.toolCallId,
            name: event.data.agentName,
            displayName: event.data.agentDisplayName,
            status: "running",
            startedAt: new Date(event.timestamp),
        });
    }

    if (event.type === "subagent.completed") {
        const node = agentTree.get(event.data.toolCallId);
        if (node) {
            node.status = "completed";
            node.completedAt = new Date(event.timestamp);
        }
    }

    if (event.type === "subagent.failed") {
        const node = agentTree.get(event.data.toolCallId);
        if (node) {
            node.status = "failed";
            node.error = event.data.error;
            node.completedAt = new Date(event.timestamp);
        }
    }

    // Render your UI with the updated tree
    renderAgentTree(agentTree);
});

エージェントごとのスコープツール

          `tools` プロパティを使用して、エージェントがアクセスできるツールを制限します。 これは、セキュリティとエージェントの集中を維持するために不可欠です。

const session = await client.createSession({
    customAgents: [
        {
            name: "reader",
            description: "Read-only exploration of the codebase",
            tools: ["grep", "glob", "view"],  // No write access
            prompt: "You explore and analyze code. Never suggest modifications directly.",
        },
        {
            name: "writer",
            description: "Makes code changes",
            tools: ["view", "edit", "bash"],   // Write access
            prompt: "You make precise code changes as instructed.",
        },
        {
            name: "unrestricted",
            description: "Full access agent for complex tasks",
            tools: null,                        // All tools available
            prompt: "You handle complex multi-step tasks using any available tools.",
        },
    ],
});

メモ

          `tools`が`null`または省略されると、エージェントはセッションで構成されているすべてのツールへのアクセスを継承します。 明示的なツール リストを使用して、最小限の特権の原則を適用します。

エージェントへの MCP サーバーのアタッチ

各カスタムエージェントは独自の MCP (モデルコンテキストプロトコル) サーバーを持つ可能性があり、特殊なデータソースにアクセスできます。

const session = await client.createSession({
    customAgents: [
        {
            name: "db-analyst",
            description: "Analyzes database schemas and queries",
            prompt: "You are a database expert. Use the database MCP server to analyze schemas.",
            mcpServers: {
                "database": {
                    command: "npx",
                    args: ["-y", "@modelcontextprotocol/server-postgres", "postgresql://localhost/mydb"],
                },
            },
        },
    ],
});

パターンとベストプラクティス

研究者と編集者のペアリング

一般的なパターンは、読み取り専用の研究者エージェントと書き込み可能なエディターエージェントを定義することです。ランタイムは探索タスクを研究者に委任し、変更タスクをエディターに委任します。

customAgents: [
    {
        name: "researcher",
        description: "Analyzes code structure, finds patterns, and answers questions",
        tools: ["grep", "glob", "view"],
        prompt: "You are a code analyst. Thoroughly explore the codebase to answer questions.",
    },
    {
        name: "implementer",
        description: "Implements code changes based on analysis",
        tools: ["view", "edit", "bash"],
        prompt: "You make minimal, targeted code changes. Always verify changes compile.",
    },
]

エージェントの説明を固有に保つ

ランタイムは、 description を使用してユーザーの意図と一致します。あいまいな説明は、委任が不適切になります。

// ❌ Too vague — runtime can't distinguish from other agents
{ description: "Helps with code" }

// ✅ Specific — runtime knows when to delegate
{ description: "Analyzes Python test coverage and identifies untested code paths" }

エラーを適切に処理する

サブエージェントは失敗する可能性があります。常に subagent.failed イベントをリッスンし、アプリケーションで処理します。

session.on((event) => {
    if (event.type === "subagent.failed") {
        logger.error(`Agent ${event.data.agentName} failed: ${event.data.error}`);
        // Show error in UI, retry, or fall back to parent agent
    }
});

カスタムエージェントとサブエージェントオーケストレーション

この機能を使用できるユーザーについて

この記事で

カスタムエージェントの定義

構成参照

セッション作成時のエージェントの選択

サブエージェントの委任のしくみ

推論の制御

サブエージェントイベントの監視

イベントの種類

イベントに登録する

エージェントツリー UI の構築

エージェントごとのスコープツール

エージェントへの MCP サーバーのアタッチ

パターンとベストプラクティス

研究者と編集者のペアリング

エージェントの説明を固有に保つ

エラーを適切に処理する

カスタム エージェントとサブエージェント オーケストレーション

この機能を使用できるユーザーについて

この記事で

カスタムエージェントとサブエージェントオーケストレーション