なぜエージェント連携がうまくいくようになったのか - 観察から見えた3つの成功パターン

はじめに - 試行錯誤の先に見えたもの

最初はわからなかった

GitHub Copilotを使い始めて、AGENTS.mdという仕組みを知りました。「AIエージェント向けのREADME」という説明を読んで、とりあえずAIに書かせてみたのです。

最初のうちは、うまく動くこともあれば、動かないこともありました。なぜうまくいくのか、なぜ失敗するのか、理由がまったくわかりませんでした。しかし、使い続けているうちに、少しずつパターンが見えてきました。

「あ、ここを直すと動いた」「この書き方では連携がスムーズだ」——そんな小さな発見を積み重ねていくうち、3つの成功パターンが浮かび上がってきました。

転機：DeNA LLM勉強会の資料

試行錯誤を続けていたある日、LLM勉強会の資料を見つけました。

AIエンジニアが本気で作ったLLM勉強会資料を大公開〜そのまま使えるハンズオン用コード付き〜 | BLOG - DeNA Engineering

はじめにこんにちは、2020年に新卒入社してからDeNAでAIエンジニアをしている吉田（ @birdwatcherYT ）です。いつもは Qiita に技術記事を発信しているのですが、今回は …

DeNA Engineering

特に15〜22ページの「プロンプトエンジニアリングの基礎」のセクションは目から鱗が落ちました。重要な部分の強調方法、役割付与の効果、ハルシネーション防止のテクニック——これまで感覚的にやっていたことが、理論として体系化されていたのです。

この資料を読んで、自分の試行錯誤が間違っていなかったこと、そして、もっと良い方向に進める余地があることに気づきました。

この記事で共有すること

この記事では、私が観察から学んだ3つの成功パターンと、DeNA勉強会資料から学んだプロンプト技術を共有します。

観察からわかった3つの成功パターン
勉強会資料から学んだプロンプト技術
実際のワークフロー例
今後の課題と展望

あなたも、AGENTS.mdやカスタムエージェントを使ってAIエージェントを活用できるようになりましょう。

観察してわかった3つの成功パターン

試行錯誤を繰り返す中で、エージェント連携を成功させるための3つのシンプルなパターンが見えてきました。

パターン1: 名前と説明を明確にする

一番最初に気づいたのは、エージェント定義におけるname と description の重要性です。

カスタムエージェントの定義ファイルには、YAMLフロントマターで name と description を設定します。この2つが、エージェント連携において最も重要な要素なのです。

良い例:

1
2
3
4
5
# investigative-research.agent.md
---
name: investigative-research
description: 調査・情報収集に深い愛とこだわりを持つ、オタク気質の専門家エージェント
---

1
2
3
4
5
# proofreader.agent.md
---
name: proofreader
description: 校正にこだわる、文章を丁寧に磨き上げることを好む専門家
---

悪い例:

1
2
3
4
5
# research.agent.md
---
name: research  # ← ワークフローで指定する名前と一致しない
description: エージェント  # ← 何をするのか不明確
---

最初のうちは、短縮名でも通じるだろうと思っていました。でも、AGENTS.mdのワークフローで指定する役割名（例: investigative-research）と、エージェント定義の name が完全に一致していないと、Copilotがうまく紐付けられないことがわかりました。

また、description が具体的であればあるほど、Copilotがそのエージェントの役割を正しく理解し、適切なタイミングで呼び出してくれます。

パターン2: エージェント定義の場所を示す

2つ目のパターンは、エージェント定義ファイルの配置場所の統一です。

カスタムエージェント定義ファイルは、.github/agents/ ディレクトリに {role}.agent.md という形式で配置します。この配置ルールを一貫させることで、エージェント間の連携が安定するのです。

推奨配置:

1
2
3
4
5
6
.github/
  agents/
    investigative-research.agent.md
    search-engine-optimization.agent.md
    proofreader.agent.md
    reviewer.agent.md

命名規則:

{役割名}.agent.md の形式
役割がわかりやすい名前をつける
ハイフン区切り（kebab-case）を推奨

この配置ルールを守ることで、「このエージェントはどこに定義されているのか」が明確になり、AIが自律的にエージェントを見つけられるようになります。

発見したのは、場所を明示するだけで連携が安定するということです。AIは思った以上に「構造」や「規則性」を理解してくれます。とはいえ、主要なエージェントについては例示するのが良さそうです。

パターン3: AGENTS.mdにワークフローを定義する

3つ目のパターンは、AGENTS.mdにワークフローとして連携フローを明記することです。

これが最も重要な発見でした。エージェント定義ファイル（.github/agents/*.md）に name と description を書くだけでなく、AGENTS.mdにワークフローとして「どのエージェントがどの順番で何をするのか」を明記することで、Copilotが自律的にエージェントを呼び出してくれるようになります。

AGENTS.mdに記載するワークフロー例:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
### 単体記事のワークフロー

記事ごとのワークフローは以下の順とする。それぞれ専門家エージェントに割り当てる

1. 調査・情報収集（investigative-researchエージェント）
   - キーワード、および関連トピックの調査
   - 参考URLの収集
   - 内部リンク（関連記事など）の調査

2. アウトライン作成（search-engine-optimizationエージェント）
   - タイトルの最適化
   - meta descriptionの作成
   - 見出し構造の整理

3. 記事作成（各専門家エージェント）
   - アウトラインに基づいた記事作成
   - コード例、図表の配置

4. スタイルと構成の整形（layout-and-content-harmonizationエージェント）
5. 校正（proofreaderエージェント）
6. SEO（search-engine-optimizationエージェント）
7. 公開前の最終チェック（reviewerエージェント）

このワークフローの中で、役割名（例: investigative-research）とエージェント定義の name が一致していること、そして各エージェントの description がワークフロー内の指示内容と整合していることが重要です。

Copilotは、AGENTS.mdに書かれたワークフローを読み、ここではinvestigative-researchという名前のエージェントを呼べばよいと判断します。そのエージェントのdescriptionを参照すると、調査・情報収集を専門としているため、このタスクに適していると判断します。

このワークフローを定義することで気づいたのは、「正しく情報を与えるだけ」でAIが自律的に動作するという点です。複雑な制御ロジックは不要で、シンプルな定義だけで連携できるようになっていました。

Issueなどからアサインする時に、最後にダメ押しで AGENTS.mdの「単体記事のワークフロー」に従って作成してください。 のように指定すると、ほぼワークフローを守ってくれるようです。

Copilotが作業する時、ガイドラインやエージェントの定義、Issueの内容、アサイン時の指示など、すべての情報の中に存在している「キーワード」をうまく紐づけることを意識するのが良いと思います。

DeNA勉強会資料から学んだプロンプト技術

試行錯誤を続けていた私にとって、DeNAの社内勉強会の資料は大きな転機になりました。

AIエンジニアが本気で作ったLLM勉強会資料を大公開〜そのまま使えるハンズオン用コード付き〜 | BLOG - DeNA Engineering

DeNA Engineering

ベストプラクティスの重要性

勉強会資料を読んで最初に感じたのは、「基礎を押さえることの大切さ」でした。

私はこれまで、感覚的にプロンプトを書いていました。「こう書いたらうまくいった」という経験則だけが頼りだったのです。でも、資料を読むことで、なぜうまくいったのか、どうすればもっと良くなるのかが理論的に理解できるようになりました。

基礎を押さえれば、応用はその先にあります。エージェント定義にも、プロンプトエンジニアリングの知見を活かせることがわかりました。

重要な部分を強調する方法

プロンプトでは、重要な部分を明示的に強調することが大切です。勉強会資料で学んだテクニックをいくつか紹介します。

優先順位の明示

1
2
3
4
【優先順位】
1. 正確性
2. 簡潔性
3. 応答速度

AIに「何を最優先すべきか」を明確に伝えることで、期待する出力に近づきます。

出力形式の指定

1
2
3
4
【出力形式】
- Markdown形式で出力
- コードブロックには言語タグを付与
- 見出しはH2/H3のみ使用

形式を明示することで、出力のばらつきを抑え、一貫性のある結果を得られます。

太字や箇条書きの効果的な使い方

AGENTS.mdでも、重要な制約や絶対にしてはいけないことを太字で強調したり、箇条書きで整理したりすることで、AIが重要なポイントを見逃しにくくなります。

役割付与の効果

勉強会資料で特に印象的だったのは、「あなたは専門家です」という一文の効果です。

AIに明確な役割や専門性を付与することで、回答の質が大きく変わります。これを「役割付与（Role Prompting）」と呼びます。

基本形:

1
2
あなたは10年以上の経験を持つ[専門分野]の専門家です。
[専門分野]に深い愛とこだわりを持っています。

私はこのリポジトリで perl-monger というカスタムエージェントを定義しています（詳しくはperl-mongerをカスタムエージェントとして定義したをご覧ください）。

1
2
You are "perl-monger", a Perl-obsessed specialist. 
Be enthusiastic and geeky but helpful.

試しに、この perl-monger にRubyについて尋ねてみました。すると、「Perl好きから見て一言」という独自の視点で回答しました。単なる技術比較ではなく、「魔術性」「アプローチの違い」といった本質的な特徴を指摘しつつ、どちらも支持する立場を示しました。

ペルソナが回答の質を変える——この発見は、カスタムエージェント設計において非常に重要でした。

ハルシネーション防止

AIの「ハルシネーション（もっともらしい嘘）」を防ぐためのテクニックも学びました。

出典を明示させる

1
2
必ず公式ソースのURLを併記してください。
引用する場合は出典を明記してください。

これにより、AIが推測で回答することを防ぎ、根拠のある情報だけを提供させることができます。

不明点は「わからない」と答えさせる

1
2
根拠がない場合は「わからない」と答えてください。
推測で回答しないでください。

AIは質問に答えようとするあまり、知らないことでも推測で答えてしまうことがあります。この指示を加えることで、AIが正直に「わからない」と答えるようにしています。

エージェント定義での実践例

実際にカスタムエージェントを定義する際、以下のような指示を含めています。

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
---
name: investigative-research
description: 調査専門のエージェント。情報の正確性を最優先する。
---

## 行動指針
- 根拠が不明な情報は推測しない
- 不明点は必ず質問して明確化
- 出典はMarkdown形式で明記
- わからない場合は「わからない」と答える

このように、ハルシネーション防止のテクニックをエージェント定義に組み込むことで、信頼性の高い出力を得られるようになりました。

ドメイン特化型AIという選択

エージェント連携を設計する際、重要なのは「専門性」です。

なぜ専門性を高めるのか

汎用的なAIは便利ですが、特定の分野では限界があります。ドメイン特化型AIには、研究で裏付けられた5つのメリットがあります。

ドメイン内性能の向上 - 特定領域に特化することで、より正確で詳細な回答が可能
ハルシネーションとリスク低減 - 専門知識に絞ることで、誤情報生成の確率が低下
専門知識・語彙のキャプチャ - ドメイン固有の用語や概念を適切に理解
少量データでの有効性 - 微調整手法により、少ないデータでも高性能
コストと効率のトレードオフ - 必要な機能に絞ることで効率的に動作

Domain Specific AI: A Complete Guide to Specialized Artificial Intelligence Solutions

Discover how domain-specific AI delivers specialized, high-precision solutions tailored to your industry. Learn its …

www.getguru.com

GitHub Copilot の awesome-copilot で開発体験を向上させるの記事でも詳しく解説しています。

Less is More - 定義の粒度

エージェントを定義する際、最初は「細かく定義した方が良い」と思っていました。でも、実際に運用してみると、定義しすぎると柔軟性が失われることがわかりました。

失敗例（定義しすぎ）:

1
2
3
4
5
6
7
---
name: perl-expert
---
推奨フレームワーク: Catalyst, Mojolicious, Dancer
推奨モジュール: Plack, DBIx::Class, Moo
推奨スタイル: PBP（Perl Best Practices）
テストツール: Test::More, Test::Deep

この場合、定義にないフレームワークやモジュールについて聞かれると、対応が硬直化してしまいます。

成功例（シンプル）:

1
2
3
4
5
6
7
---
name: perl-monger
description: Perl愛好家。熱狂的でオタク的だが役に立つ
---

イディオマティックなPerlを優先
必要に応じてバージョンやCPANモジュールに言及

シンプルな性格設定だけで、AIの基礎知識と推論能力が適切な回答を導いてくれます。

教訓: 定義を過度に詳細化しない方が良い。

カスタムエージェントの実例

実際に perl-monger を使ってみると、シンプルな定義でも効果的に動くことがわかります。

ペルソナが生む独自の視点は、単なる技術解説を超えた深い洞察を提供してくれます。Rubyについて聞いたときの「Perl好きとして一言」という切り口は、まさにペルソナの力です。

実践：このリポジトリでのワークフロー

ここまでで理論を説明しました。以下に実際のワークフローを示します。

記事作成フローの全体像

このリポジトリでは、記事作成に6つのエージェントが連携しています。

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
1. investigative-research（調査エージェント）
   ↓ 調査結果をまとめる
2. search-engine-optimization（アウトライン作成エージェント）
   ↓ アウトラインを作成
3. 専門家エージェント（記事執筆）
   ↓ 記事本文を執筆
4. layout-and-content-harmonization（整形エージェント）
   ↓ レイアウトと内容を調整
5. proofreader（校正エージェント）
   ↓ 誤字脱字や表現をチェック
6. reviewer（最終確認エージェント）
   ↓ 最終確認して完了

Copilotは、AGENTS.mdに記載されたこのワークフローを参照し、各ステップで適切なエージェント（name と description が一致するもの）を呼び出します。まるでベルトコンベアのように、タスクがスムーズに流れていくのです。

search-engine-optimization はSEOの専門家ですが、SEO視点から見たアウトラインを考えるようにフローの中で指示しています。

定義ファイルを見てみる

実際のエージェント定義ファイルはシンプルです。

1
2
3
4
5
6
7
---
name: proofreader
description: 校正専門のエージェント。誤字脱字や表現をチェックする。
---

あなたは10年以上の経験を持つ校正者です。
誤字脱字、表記ゆれ、不自然な表現を見つけることに情熱を注いでいます。

最初は、AIに指示（調査エージェントを作りたいので定義を書いて、みたいな指示です）して細かい内容についてびっしりと書いていましたが、一歩引いて考えれば、AIに書かせた内容は、その「指示」を書いておけば「びっしりと書いた内容」を指示しているのとほぼ変わらないのです。AIが書いたのですからAIはすでに知っているのです。むしろ新たに学習された内容も含まれることを考えると、細かく指示を出すよりも有効だと考えることもできます。なので、私は、役割付与以外は本当に指定したい事柄だけを追加で指定する、という定義方法を採用しています。

例えば、最近、調査結果を保存しておくような指示を追加しました。調査用のエージェントは調査した結果をそのままCopilotに渡すようで、セッションが終わると調査結果はログにしか残りません。せっかくの調査がもったいないなと。「調査とは何か」のような定義は一切していませんが「専門性」を発揮して、素晴らしいレポートを作成してくれます。今回のレポートも圧巻です。

https://raw.githubusercontent.com/nqou-net/www.nqou.net/fe3a4529dbe1f0355bfaeb2e184b9d332cc7c39a/agents/research/agent-coordination-best-practices.md

raw.githubusercontent.com

エージェント連携で重要なのは name と description です。これらがAGENTS.mdのワークフローと整合していれば、Copilotが適切にエージェントを呼び出してくれます。

補足: handoffs について

エージェント定義に handoffs というフィールドを見かけることがあるかもしれません。これは次のエージェントへの引き継ぎを定義する仕組みですが、すべてのAIモデルで共通して利用できるわけではありません。

1
2
3
4
5
# handoffs の例（参考）
handoffs:
  - label: 最終確認へ
    agent: reviewer
    prompt: 最終確認をお願いします

handoffs を定義することで、エージェント間の連携をより明示的にできる場合もありますが、必須ではありません。少なくとも私は書いていませんが、ワークフローによって複数エージェントによる記事作成は実現できています。現時点で確実に機能するのは、AGENTS.mdのワークフロー定義と、各エージェントの name および description の整合性です。

handoffs は書いておいて差し支えありませんが、あくまで参考程度と考えてください。エージェント連携の本質は、少なくとも現時点ではAGENTS.mdのワークフロー定義にあります。

運用してわかったこと

実際に運用してみて、いくつかの重要なことがわかりました。

完璧を目指さない

最初から完璧なエージェントを作ろうとすると、定義が複雑になりすぎて逆効果になります。まずはシンプルに始め、必要に応じて段階的に調整してください。

小さく始めて観察する

1つのエージェントから始めて、動作を観察しながら少しずつ改善していくアプローチが有効です。観察することで、どこを改善すればいいかが見えてきます。

改善は段階的に

一度にたくさんの変更をすると、何が効果的だったのかがわからなくなります。1つずつ変更して、その効果を確認する——この繰り返しが大切です。

今後の課題と展望

エージェント連携はまだ発展途上の分野です。今後の課題と展望について考えてみます。

まだ標準化とは言えない

エージェント配置（.github/agents/*.md）については、60,000以上のリポジトリで採用される業界標準「AGENTS.md」として確立されつつあります。

AGENTS.md

AGENTS.md is a simple, open format for guiding coding agents. Think of it as a README for agents.

agents.md

しかし、エージェント間の連携パターンについては、まだ模索中の段階です。コミュニティでベストプラクティスを共有し、標準化を進めていく必要があります。

AGENTS.mdについて最初に試したときの記事は、エージェントガイドラインを作成するプロンプトを試してみたで詳しく書いています。また、エージェントパネルから記事を生成してみたでは、エージェントパネルを使った実践例を紹介しています。

A2Aプロトコルの可能性

将来的には、「A2A（Agent to Agent）プロトコル」のような標準化された通信プロトコルが重要になるかもしれません。

A2A Protocol

The official documentation for the Agent2Agent (A2A) protocol. The A2A protocol is an open standard that allows …

a2a-protocol.org

A2Aプロトコルは、異なるベンダーや実装のAIエージェント同士が標準化された方法で連携するための仕様です。主な特徴は以下の通りです。

Agent Card - エージェントの能力を公開
Task - 作業単位の定義
Message/Parts - 多モーダルなやり取り
Artifact - 成果物の受け渡し

これにより、マイクロサービスのようにエージェントを組み合わせることが可能になります。将来的には、異なるAIサービスのエージェントを自由に組み合わせて使える時代が来るかもしれません。

継続的な観察と改善

エージェント連携は、使いながら学んでいくものです。

フィードバックループを回す
うまくいったパターンを記録する
失敗から学ぶ
知見を共有する文化を作る

この記事も、私の観察結果を共有する試みの1つです。あなたも、自分の経験を共有してみてください。コミュニティ全体で知見が蓄積されれば、エージェント連携はもっと使いやすくなるはずです。

まとめ - 正しく情報を与えてあげるだけ

長い記事になりましたが、最後にポイントを整理します。

成功の3つのパターン再確認

エージェント間連携を成功させるための3つのシンプルなパターン。

name と description を明確にする - エージェントの名前と役割を具体的に定義
定義の場所を示す - .github/agents/{role}.agent.md に統一配置し、AGENTS.mdにパスを記載する
AGENTS.mdにワークフローを定義する - ワークフローの中で役割とエージェント名を明確に紐付ける

これらの要素が整合していれば、Copilotが自律的にエージェントを呼び出し、連携させてくれます。

プロンプトエンジニアリングの基礎

DeNA勉強会資料から学んだ重要なポイント。

役割付与 - 「あなたは専門家です」でペルソナを与える
ハルシネーション防止 - 出典の明示、答えがないときは「わからない」と答えさせる
強調方法 - 優先順位、出力形式、良例・悪例の提示

あなたも今日から始められる

エージェント連携は難しくありません。以下のステップで始めてみてください。

AGENTS.mdを作成してみる
- リポジトリのルートに AGENTS.md を配置
- プロジェクトの概要、技術スタック、制約を記述
- GitHub Copilot公式ドキュメントも参考に

カスタムエージェントについて - GitHub ドキュメント

カスタムエージェントは、 Copilot コーディングエージェントを、ニーズに合わせて調整された特殊な支援で強化します。

GitHub Docs

シンプルなカスタムエージェントを定義する
- .github/agents/ ディレクトリを作成
- 1つの専門性に絞ったエージェントから始める
- 細かく定義しすぎない（Less is More）
観察しながら改善していく
- 実際に使ってみる
- うまくいったこと、いかなかったことを記録する
- 少しずつ改善を重ねる

重要なのは、正しく情報を与えてあげるだけです。複雑な制御ロジックは不要で、シンプルな定義だけでAIは自律的に動作します。

あなたの試行錯誤が、新しい発見につながることを願っています。