Claude×GitHub Actions マルチエージェントシステム構築【実装手順】

これでできること：複数AIエージェントの協力作業を自動化する

生成AIを1つの単体として使うのではなく、複数のAIエージェント（専門性を持つAI）が協力して目標に向かって動くシステムが注目されています。Claudeと呼ばれるAIと、GitHub Actionsという自動化ツールを組み合わせると、こうした「自律型マルチエージェントシステム」を比較的すぐに構築できます。

実際の活用例としては以下のようなものが報告されています：

SEO記事の自動作成・最適化：複数のエージェントが記事案の検索キーワード調査、本文作成、検索順位の改善といった異なる役割を分担し、全工程を自動で進めることができます。これまで人間が1週間かかっていた記事作成作業が数時間で完了する可能性があります。

ソフトウェア開発の並列実験：16個のClaudeエージェントが同時に異なるアルゴリズムを試し、成功した方法をまとめるといった運用も実現しています。これにより、開発期間の大幅な短縮が期待できます。

交渉・意思決定の自動化：複数のエージェントが異なる立場から協議し、合意に達するプロセスまで自動化する事例もあります。このとき、エージェント同士が互いの視点を知らないままで協議する仕組みにすることで、より客観的な結果が得られると指摘されています。

これらはすべて、従来の単一AIツール（ChatGPTやBardなど）では実現できない働き方です。複数の視点を組み合わせることで、人間では思いつかないアイデアや解法が生まれる確率が高まります。

準備するもの

このシステムを構築するために必要な準備は、意外とシンプルです。

1. Claudeの利用契約：Anthropicという企業が提供するClaudeというAIを使います。API（外部ツールと自動で連携するための接続口）を利用する形で、従量制（使った分だけ支払う）の料金体系です。個人の実験であれば月数百円から数千円の範囲で始められます。

2. GitHubのアカウント：コード（プログラムの命令文）を管理し、自動実行するためのプラットフォームです。無料アカウントで十分です。

3. 基本的なプログラミング知識：Pythonという初心者向けのプログラミング言語が使われることが多いです。ただし、既存のテンプレートやサンプルコードをコピー＆ペーストして少し手直しする程度の知識があれば、本格的なシステムが構築できます。

4. テキストエディタ：コードを書き込むためのシンプルなソフトウェアです。Windows付属の「メモ帳」でも最初は問題ありませんが、プログラミング専用のエディタ（Visual Studio Codeなど、多くは無料）を使うと便利です。

実際のマルチエージェントシステムの構築では、複数のエージェントがそれぞれの役割を明確に持つ設計が重要になります。たとえば、SEOシステムであれば「キーワード調査エージェント」「記事執筆エージェント」「品質チェックエージェント」というように、各エージェントの得意分野を決めておくことで、チーム全体の効率が大きく上がります。

実装の手順（5つのステップ）

ステップ1：GitHub Actionsの基本をセットアップする（目安：20分）

GitHub Actionsとは、GitHubのサーバー上で自動的にプログラムを実行してくれるサービスです。たとえば「毎日午前8時に記事作成を開始する」「ボタンをクリックしたら自動で検査を走らせる」といった指示をあらかじめ書き込んでおくと、その通りに動きます。

まずGitHubのリポジトリ（プロジェクトのフォルダのようなもの）を作成し、.github/workflowsというフォルダを用意します。ここにYAML形式（設定ファイルの標準形式）のテキストファイルを置くことで、実行ルールを定義します。

公開されているサンプルプロジェクトでは、Pythonスクリプトを毎日決まった時間に実行する設定が示されています。これは「スケジューラー」と呼ばれ、Linuxの標準機能を借りて実装されます。

ステップ2：Claudeエージェントの役割分担を設計する（目安：30分）

複数のエージェントが効率よく協力するためには、事前に「誰が何をするか」を明確にしておく必要があります。

たとえばSEO記事作成システムであれば以下のような分担が考えられます：

• エージェントA（調査係）：Google検索など外部データを参照し、キーワード候補とユーザーのニーズをまとめる
• エージェントB（執筆係）：エージェントAの調査結果をふまえて本文を作成する
• エージェントC（チェック係）：完成した記事を読み、SEO最適化や誤字脱字がないか確認する

各エージェントは専門的な「指示」（プロンプト）を受け取ります。この指示は、人間が部下に仕事の詳細を伝えるのと同じように、「あなたの役割は何か」「どんな成果を期待するのか」「どのルールに従うべきか」を明記します。

ステップ3：エージェント間の通信方法を決める（目安：40分）

複数のエージェントが協力するには、エージェント同士が「今、ここまで進んだよ」と知らせ合う必要があります。この仕組みを「通信」と呼びます。

一般的には以下の3つの方法が使われます：

直列実行（順番に実行）：エージェントAが終わったら、その結果をエージェントBに渡す。エージェントBが終わったらエージェントCに渡す。この方法は最もシンプルで、時間がかかります。

並列実行（同時に実行）：複数のエージェントが同時に動きます。Anthropic（Claudeを開発した企業）の報告では、16個のエージェントを同時に動かしてソフトウェアの最適化を試みたといいます。この方法は時間は短いですが、結果をまとめるのに工夫が必要です。

段階実行（グループごとに実行）：エージェントを3～5個のグループに分け、各グループが終わったら次のグループに進むというやり方です。バランスが良く、実務的に採用されることが多いと思われます。

実装では、JSON形式（コンピュータが読みやすいデータの記述方式）やテキストファイルを介して、エージェント間でデータをやり取りします。

ステップ4：実装コードを書き込む（目安：60分）

ここが最も実装的なフェーズです。Pythonを使い、以下の要素を組み合わせます：

1. Claudeのライブラリ導入：Anthropicが提供するPythonコード集を自分のプロジェクトに組み込みます。これにより「Claudeに質問を送る」「Claudeからの返答を受け取る」といった処理が簡単に書けます。

2. エージェント定義：各エージェントが持つべき役割や指示を関数という再利用可能な処理単位として書きます。

3. 実行フロー：エージェント1→エージェント2→エージェント3という順番を制御する処理です。

4. エラーハンドリング：もし途中で失敗したらどうするか（リトライするか、ログを記録するか）を定めます。

実装の具体的な例は、GitHub上の公開プロジェクトから参考にできます。特に「Building an autonomous multi-agent SEO system」というプロジェクトでは、実用的なSEO最適化システムのコード全体が公開されており、これをベースに改造することで、自分たちのニーズに合わせたシステムを作れます。

なお、マルチエージェント実装を進めるうえで注意すべき重要な課題が「Hallucination（幻覚）」です。AIモデルが実際には存在しないライブラリ名や廃止されたAPIメソッドを、あたかも事実のように返答する現象で、複数のエージェントが連携するシステムではこうした誤情報が下流のエージェントにそのまま伝播してしまうリスクがあります。後述する「マルチモデルディスカッション手法」を組み込むことで、このリスクを軽減できます。

ステップ5：テスト実行と本番運用へ（目安：30分）

コードを書き終わったら、実際に動かしてみます。初回は小規模なテストから始め、エージェントが期待どおりに動くか確認します。

この段階で頻繁に起こる失敗には以下のようなものがあります：

• Claudeへのリクエストがうまく送信されていない（多くの場合、APIキーの設定ミス）
• エージェント間でデータの形式がずれている（一方がJSON形式で送ったのに、もう一方がテキストで受け取ろうとしている）
• スケジューラーの時刻設定が違う（「毎日9時に実行」と書いたつもりが、実は夜中に走っていた）

こうした問題は、GitHub Actionsの「ログ」を確認することで原因が分かります。ログとは、実行時の詳細な記録です。

テストで問題がなければ、本番環境（実際に使う環境）に移します。初期段階では「1日1回動かす」程度の保守的な設定から始め、様子を見て「毎時間実行」などに進めることをお勧めします。

つまずきやすいところ

1. APIキーの管理

ClaudeのAPIキーは、銀行口座の暗証番号のようなものです。これが漏れると、他の誰かがあなたのアカウント経由でClaudeを使い、料金が発生します。

GitHub Actionsでコードを実行する際には、APIキーを「環境変数」という隠れた場所に保管し、コードからは「この隠れた場所からAPIキーを取ってきて」と指示する方法を使います。GitHub上に直接「sk-…」のような文字列を書き込むのは、絶対に避けましょう。

2. エージェント間での仕様のずれ

3つ以上のエージェントが協力する場合、「エージェントAは結果をJSON形式で返す」と決めたのに、実装時に「エージェントBはプレーンテキストで結果を受け取る」という食い違いが生じることがあります。

これを防ぐには、プロジェクト全体で「入出力のルール」をドキュメント化（文書にまとめる）しておくことが効果的です。

3. 予算管理

Claudeは従量制なので、エージェントが何回も何回も実行されるシステムでは、思わぬ高額な料金が発生する可能性があります。特に、エージェントが「失敗→リトライ→失敗→リトライ…」というループに陥ると危険です。

GitHub Actionsのログを定期的に確認し、実行回数や処理時間が想定の範囲内かチェックすることをお勧めします。Anthropicのダッシュボードで現在の使用額と予測額を確認できます。

4. 環境依存の問題

GitHub Actionsのサーバーと自分のローカルPC（手元のコンピュータ）では、インストールされているライブラリが異なることがあります。「ローカルではうまく動いたのに、GitHub Actionsでは失敗する」という現象が起きやすいです。

これを防ぐには、プロジェクトにrequirements.txtというファイルを作り、「このバージョンのこのライブラリが必要」と明記しておくことが大切です。

5. Hallucination（AIの誤情報生成）への対処

マルチエージェントシステムで見落とされがちなのが、AIによる「Hallucination」への対策です。これはAIが存在しないライブラリ名を返す、廃止されたAPIメソッドを示す、実装不可能なアルゴリズムを提案するなど、一見すると正確な回答に見えながら実際には動作しないコードを生成してしまう現象です。

複数のエージェントが連携するシステムでは、1つのエージェントが誤った情報を出力すると、それが下流のエージェントにそのまま伝播してしまうリスクがあります。次のセクションで紹介する「マルチモデルディスカッション手法」を取り入れることで、このリスクを大幅に軽減できます。

Hallucinationを軽減するマルチモデルディスカッション手法

仕組みの概要

複数のAIモデルで同じ質問に回答させ、その結果を相互検証する手法です。異なるアーキテクチャ・訓練データを持つモデルであれば、Hallucinationが発生する箇所や内容が異なる傾向があります。複数の回答を比較・議論させることで、矛盾を検出し、より信頼性の高い結論に辿り着けます。

具体的なアプローチは3種類あります：

アプローチ1：複数モデルで並列回答＋一致度判定：同じプロンプトをClaude 3.5 SonnetやGPT-4oなど複数のモデルに送信し、回答の一致度を調べます。複数モデルが同じ内容を返答した場合、その情報の信頼性は大きく高まります。逆に矛盾がある場合は、人間の検証やさらなる調査が必要なシグナルです。

アプローチ2：議論型ディスカッション：1つ目のモデルが回答を生成し、その回答を2つ目のモデルに提示して「この回答は正確ですか？論理矛盾や誤りがないか検証してください」と依頼します。2つ目のモデルが矛盾や問題を指摘した場合、さらに詳しく調査する価値があります。

アプローチ3：投票＋Consensus：3個以上のモデルに回答させ、複数の回答候補が出た場合に「投票」して最も支持される答えを選ぶ手法で、エンタープライズシステムで用いられています。

実装例：議論型マルチモデルディスカッション

以下は、Claude APIを使ってマルチターン会話による自己検証を実装したPythonコード例です。

必要な環境

• Python 3.9以上
• python-dotenv（環境変数管理用）
• anthropicライブラリ（Claude API用）
• openaiライブラリ（GPT-4o用、オプション）

pip install python-dotenv anthropic openai

環境変数設定ファイル（.env）：

CLAUDE_API_KEY=sk-ant-xxxxx
OPENAI_API_KEY=sk-xxxxx

議論型ディスカッションの実装：

import os
from anthropic import Anthropic

def multi_model_discussion(task_description: str, verification_depth: int = 2) -> dict:
    """
    複数モデルディスカッション：Claudeが回答を生成し、
    その内容を自身で検証するマルチターン会話を実行
    
    Args:
        task_description: 検証対象のタスク説明
        verification_depth: 検証ラウンド数（1 or 2推奨）
    
    Returns:
        {
            "original_response": 初期回答,
            "verification_rounds": 検証内容,
            "final_consensus": 最終的な信頼度評価
        }
    """
    
    client = Anthropic()
    conversation_history = []
    
    # ステップ1：初期回答の生成
    initial_prompt = f"""以下のタスクに対して、詳しく、具体的に回答してください：

{task_description}

回答の際は、あなたが使用した情報源・根拠がある場合は明記してください。"""
    
    conversation_history.append({
        "role": "user",
        "content": initial_prompt
    })
    
    response = client.messages.create(
        model="claude-3-5-sonnet-20241022",
        max_tokens=2000,
        system="あなたは正確で信頼できるアシスタントです。わからないことは『不明です』と答えてください。推測であれば『推測ですが』と前置きしてください。",
        messages=conversation_history
    )
    
    initial_response = response.content[0].text
    conversation_history.append({
        "role": "assistant",
        "content": initial_response
    })
    
    # ステップ2：自己検証プロセス
    verification_results = []
    
    for round_num in range(verification_depth):
        verification_prompt = f"""あなたが直前に与えた回答を、以下の観点から厳しく検証してください：

1. 事実の正確性：存在しないAPI、廃止された機能、実装不可能なアルゴリズムを示していないか
2. 論理的一貫性：矛盾や飛躍した論理がないか
3. 完全性：重要な前提条件やエッジケースを見落としていないか
4. 出典：引用している情報が実在するか、または推測であることが明記されているか

特に、コード例やAPI仕様に関して言及した場合は、それらが実際に動作するコードであることを確認してください。

検証の結果、問題点や改善すべき点があれば、具体的に指摘してください。"""
        
        conversation_history.append({
            "role": "user",
            "content": verification_prompt
        })
        
        verification_response = client.messages.create(
            model="claude-3-5-sonnet-20241022",
            max_tokens=2000,
            system="あなたは厳格なコード・事実検証者です。曖昧さや不正確さを徹底的に指摘してください。",
            messages=conversation_history
        )
        
        verification_text = verification_response.content[0].text
        conversation_history.append({
            "role": "assistant",
            "content": verification_text
        })
        
        verification_results.append({
            "round": round_num + 1,
            "verification": verification_text
        })
    
    # ステップ3：最終的な信頼度評価
    final_evaluation_prompt = """上記の検証プロセスを通じて、元の回答がどの程度信頼できるかを評価してください。

以下の形式で答えてください：
- 信頼度（高/中/低）
- 理由
- 利用する場合の注意点"""
    
    conversation_history.append({
        "role": "user",
        "content": final_evaluation_prompt
    })
    
    final_evaluation = client.messages.create(
        model="claude-3-5-sonnet-20241022",
        max_tokens=1000,
        messages=conversation_history
    )
    
    final_consensus = final_evaluation.content[0].text
    
    return {
        "original_response": initial_response,
        "verification_rounds": verification_results,
        "final_consensus": final_consensus,
        "conversation_history_length": len(conversation_history)
    }

複数の異なるAPI（Claude＋GPT-4o）を組み合わせたい場合は、以下のような実装も可能です：

def multi_api_verification(task: str) -> dict:
    """複数の異なるAPI（Claude + GPT-4o）で同じタスクを実行"""
    
    from openai import OpenAI
    
    claude_client = Anthropic()
    claude_response = claude_client.messages.create(
        model="claude-3-5-sonnet-20241022",
        max_tokens=1500,
        messages=[{"role": "user", "content": task}]
    ).content[0].text
    
    openai_client = OpenAI(api_key=os.getenv("OPENAI_API_KEY"))
    gpt_response = openai_client.chat.completions.create(
        model="gpt-4o",
        max_tokens=1500,
        messages=[{"role": "user", "content": task}]
    ).choices[0].message.content
    
    evaluation_prompt = f"""
    以下は同じタスクに対する2つの異なるAIモデルの回答です。
    
    Claude: {claude_response[:300]}...
    GPT-4o: {gpt_response[:300]}...
    
    これら2つの回答は一致しているか、矛盾しているか分析してください。
    """
    
    consensus = claude_client.messages.create(
        model="claude-3-5-sonnet-20241022",
        max_tokens=500,
        messages=[{"role": "user", "content": evaluation_prompt}]
    ).content[0].text
    
    return {
        "claude_response": claude_response,
        "gpt_response": gpt_response,
        "consensus_analysis": consensus
    }

実装時の重要ポイント

Systemプロンプトの使い分け：検証段階では通常と異なるシステムプロンプトを使うことで、AIの検証能力を高められます。初期回答時は「正確で信頼できるアシスタント。わからないことは『不明です』と答える」、検証段階では「厳格なコード検証者。矛盾や不正確さを徹底的に指摘する」というように使い分けます。

検証の深さとコストのバランス：検証ラウンドを増やすほど信頼性は上がりますが、APIコストとレイテンシ（応答時間）が増加します。リアルタイム性が必要なユースケースでは、検証ラウンド数を1〜2に制限することを推奨します。本番環境では、検証スコアの高いキャッシュ結果を活用することも有効です。

Hallucination完全排除の不可能性：この手法はHallucinationのリスクを軽減しますが、完全に排除できるわけではありません。特に新しい技術やニッチなドメインに関しては、最終的には人間の検証が必須です。

慣れてきたら試したいこと

1. エージェント数の段階的な増加

最初は2～3個のエージェントで小さく始めたら、成功を確認してから4個、5個…と増やしていく方法があります。各段階で新しいエージェントを追加する際の課題（通信ルール、役割の定義、コスト管理）に対処する経験が積めます。

2. エージェント間の「交渉」メカニズム

エージェントが単に情報をやり取りするだけでなく、「Aさんはこう言っているけど、Bさんはこう言っている。どう調整する？」という合意形成プロセスを組み込む方法があります。Anthropicの報告では、こうした「交渉エージェント」が商取引の現場で活用されています。

3. 外部データとの統合

現在のシステムが単一のタスク（記事作成など）に特化しているなら、外部のデータベースやAPI（他社のWebサービスと連携する接続口）と組み合わせることで、より実用的なシステムに進化させられます。

たとえば、Google Search ConsoleやSEOツールのAPIと連携させ、リアルタイムの検索データをエージェントに提供すれば、より精度の高い記事作成が実現します。

4. コスト最適化の工夫

複数のエージェントが並列で動くと便利ですが、料金も増えます。以下のような工夫が可能です：

• 「まず1つのエージェントで簡易版を作り、その結果で重要度を判定してから、本格版のエージェントを実行する」という段階的フィルタリング
• エージェントが何度も同じ質問をしないよう、結果をキャッシュ（一時保存）する機能
• 並列実行ではなく、順序を工夫して必要な時だけ並列にする方法

実際のプロジェクト例では、こうした工夫により、ナイーブな実装比で3分の1のコストに削減しながら、同等以上の成果を上げているケースが報告されています。

5. 監視・アラート機能の強化

システムが自動で動くようになると、「今、何が起きているのか」を追跡することが難しくなります。Slack（チャットツール）やメールに通知を送り、「エージェント3の実行が失敗した」「今月の予算の80%を使った」といった情報をリアルタイムで受け取る仕組みを導入すると、トラブル対応が迅速になります。

このシステムは、一度構築してしまえば、非常に汎用性が高く、様々なビジネスシーンに応用できます。最初は小さな実験から始めて、成功パターンを増やしていく。そうすることで、自分のチームの仕事の進め方が大きく変わる可能性があります。

あわせて読みたい

• LangChainでCI/CDパイプラインを自動化する、複数AIエージェント制御ガイド2026
• 本番環境でAIエージェントが暴走するのを防ぐ：料金・間違い・情報漏洩を守る実践ガイド
• Claude APIの使い方入門｜業務自動化に必要な基本設定と初回実行まで