Agency Agents オープンソースフレームワーク完全ガイド

Agency Agentsは、複数の専門家人格をまとめた設定ファイル群です。自律的な企業向け実行基盤ではないため、導入時には役割の入出力、権限、ブランチ分離、レビュー手順を別途設計する必要があります。本稿では、個人開発者から企業チームまで、どこから使い始めるべきかを整理します。

230以上の役割があっても、最初に入れるのは3つで十分です

公式GitHub READMEには、Agency Agentsのエージェント数が「230以上」と記載されています。これは役割の選択肢が豊富という意味であり、最初から全員を動かすべきという意味ではありません。(GitHub公式README)

判断：Agency Agentsは、個人開発や小規模なAI Agentチームには適しています。ただし、企業の協調実行を自動化する完成済みプラットフォームではありません。 役割設定の集合に加えて、タスクの編成、権限分離、品質門、再試行、安定した実行環境を用意できる場合に導入する価値があります。

このガイドは、Claude CodeやCursorへ役割化Agentを導入したい個人開発者、企画・コンテンツチーム、ソフトウェア開発チーム、そして長時間稼働する自動化基盤を検討する担当者向けです。役割一覧の紹介ではなく、規模ごとの使い方と不足する運用機能を整理します。

Agency Agentsは何を提供し、何を提供しないのか

Agency Agentsの中心は、役割ごとの設定ファイルです。公式の説明では、各Agentに人格、担当ミッション、ワークフロー、成果物、成功指標、コミュニケーション形式などが含まれます。(GitHub公式README)

つまり、同じモデルでも「フロントエンド実装者」「セキュリティ監査担当」「UX設計者」のように、見るべき点や納品形式を変えられます。モデルそのものを増やす仕組みではありません。独立したスケジューラーやジョブキューを内蔵した自治型サービスでもありません。

この区別を曖昧にすると、次の問題が起きます。

• 役割を増やしただけで、同じ調査やコード生成を何度も繰り返す。
• Agent同士の出力形式が違い、後工程が成果物を読み取れない。
• 誰が本番環境へ変更を加えたのか追跡できない。
• APIキーや環境変数を複数の役割が共有し、権限範囲が広がる。
• セッションが止まった際に、どこから再開するか分からない。

Claude CodeにはサブAgentの作成機能がありますが、実際のファイル操作やコマンド実行には権限設定が関係します。Agency Agentsを置くだけで、これらの制御が自動的に整うわけではありません。(Claude Code公式ドキュメント)

個人開発者は少数の高頻度役割から始めます

個人プロジェクトでは、役割数よりも切り替えコストが問題になります。計画担当、実装担当、レビュー担当を入れただけでも、作業の流れは大きく変わります。

最初の構成は、次の3役が扱いやすいです。

• 計画担当：要件を分解し、変更対象、前提条件、完了条件を記録します。
• 実装担当：計画に沿ってコードを変更し、実行した確認手順を残します。
• レビュー担当：差分、テスト結果、例外処理、セキュリティ上の懸念を確認します。

役割ファイルには、単なる口調ではなく、入力と出力を明記します。たとえば計画担当の出力を「目的、変更ファイル、実装手順、未解決リスク」の4項目に固定すると、実装担当がそのまま作業計画として使えます。

導入手順は次の流れです。公式リポジトリのライセンスはMITです。導入前に、ライセンス、現在の役割一覧、対応ツール、インストールスクリプトを確認します。(GitHub公式README)

1. リポジトリを取得し、公式READMEを読む。
2. convert.shで利用ツール向けの形式を生成する。
3. install.shでClaude CodeまたはCursorを対象にする。
4. 全役割ではなく、必要な分野だけを指定する。
5. 役割ごとに入力と出力の契約を追記する。
6. 1つの実案件で、計画からレビューまでを通す。
7. 人間が成果物を確認し、不要な役割を削除する。

Claude Codeでは、プロジェクトの権限設定を確認してから編集やシェル実行を許可します。特に権限を無条件に回避するモードは、隔離されたコンテナや仮想マシン以外では採用しない方が安全です。(Claude Code公式権限ドキュメント)

商品・コンテンツチームは入出力契約で重複を止めます

企画やコンテンツ制作では、役割を増やすほど品質が上がるとは限りません。調査担当、構成担当、執筆担当、編集担当を置く場合、各担当の成果物を次の担当が検証できる形にします。

• 調査担当：根拠、対象読者、競合との差分を提出する。
• 構成担当：見出し、主張、必要な根拠、読者の判断点を提出する。
• 制作担当：指定された構成と表現規則に沿って初稿を作る。
• 品質担当：事実、重複、リンク、禁止表現、未回答の疑問を確認する。

ここで「調査も構成も自由に提案してください」と書くと、4人のAgentが似た記事を作ります。調査担当は結論を書かず、構成担当は新しい事実を追加しない、と境界を決めることが重要です。

評価は、生成物の美しさだけでなく、次の3点で行います。

• 前工程の出力を実際に利用したか。
• 同じ作業を別の役割が重複していないか。
• 人間が短時間で承認または差し戻しできるか。

ソフトウェア開発では並列化より境界設計を優先します

複数の専門家Agentを並列で動かせるのは、作業の依存関係が分離している場合です。たとえば、API仕様の調査、テストケースの作成、脆弱性候補の確認は並列に進めやすい一方、同じ実装ファイルを2つのAgentが同時に書き換えると統合コストが増えます。

実務では、次の順番が安定します。

1. 計画担当が変更範囲と依存関係を決める。
2. 調査、テスト設計、セキュリティ確認を並列で進める。
3. 実装担当が確定した計画をもとに変更する。
4. テスト担当が実装ブランチを検証する。
5. レビュー担当が差分と検証記録を確認する。
6. 人間がマージまたは差し戻しを判断する。

同じリポジトリで複数の作業領域を持つ場合、Gitのworktreeを使うと、1つのリポジトリから複数ブランチを別ディレクトリへ展開できます。共有ファイルの衝突を完全になくすものではありませんが、作業領域を分ける基礎になります。(Git公式ドキュメント)

複数AI Agentの並列開発では、依存関係、ブランチ、レビュー順を先に決めます。Agent数を増やす前に、マージの責任者と失敗時の戻し方を決める方が効果的です。

企業利用で不足するガバナンス機能

Agency Agentsを企業プロジェクトで使う場合、役割ファイルはガバナンスの一部にすぎません。少なくとも次の領域を別に設計する必要があります。

• 権限：読み取り、編集、デプロイ、外部API利用を分けます。
• 秘密情報：APIキー、SSHキー、クラウド認証情報を役割ファイルへ直接書きません。
• ログ：依頼内容、実行コマンド、変更差分、承認者、失敗理由を保存します。
• データ保持：ソースコードや顧客情報をどこへ送るか、いつ削除するかを決めます。
• 人的承認：本番デプロイ、権限変更、データ削除は人間の承認を必須にします。
• 隔離：開発用、検証用、本番用の環境を分離します。

Claude Codeの公式文書でも、権限とサンドボックスは別の防御層として説明されています。サンドボックスはファイルシステムやネットワークを制限しますが、設定を誤れば必要なアクセスを許しすぎる可能性があります。(Claude Code公式サンドボックス文書)

企業の監査では、Agentの人格名だけでは証跡になりません。誰が依頼し、どの環境で、どの権限を使い、どの差分を承認したかを追える記録が必要です。GitHubの監査ログも、組織メンバーの操作を確認するための仕組みとして提供されています。(GitHub公式監査ログ文書)

規模に応じた実行環境の選び方

小規模な検証なら、手元のMacで十分な場合があります。役割を3つ程度に絞り、短いタスクを人間が横で確認する形です。

一方、次の条件が重なる場合は、再現可能なリモート環境を検討します。

• 複数のタスクを長時間実行する。
• 依存パッケージやSDKの導入が毎回必要になる。
• 開発者の端末を止めずにAgentを動かしたい。
• 実行ログと成果物をチームで共有したい。
• 失敗したジョブを同じ環境で再試行したい。

判断基準は、役割の総数ではありません。実際の並列数、依存関係の重さ、1タスクの継続時間、必要な外部接続、隔離レベルで決めます。

macOS専用のビルドやXcode作業を含む場合は、Macクラウドレンタルの選び方を確認し、開発端末と長時間実行環境を分ける構成が現実的です。日本向けの実行拠点を検討する場合は、日本のクラウドMacレンタルも候補になります。

本採用前に確認する項目

Agency Agentsを正式なワークフローへ入れる前に、次の項目を1つずつ確認します。チェックが付かない項目がある場合、役割数を増やすのではなく、契約や実行環境を先に修正します。

• [ ] 各役割に担当範囲と対象外の作業が書かれている。
• [ ] 前工程の入力形式と、後工程へ渡す出力形式が固定されている。
• [ ] 計画、実装、レビューの成果物が互いに重複していない。
• [ ] 失敗した処理を同じ入力から再実行できる。
• [ ] APIキーや秘密ファイルをAgentの作業範囲から除外している。
• [ ] 並列作業ではブランチまたはworktreeを分けている。
• [ ] 本番変更と権限変更に人間の承認を設定している。
• [ ] ログから依頼、実行、差分、承認結果を追跡できる。
• [ ] 3〜5個の重要役割を実案件で検証した。
• [ ] 期待した成果が出ない役割を削除または統合した。

このチェックで重要なのは、成功率を一度測ることではありません。失敗時に原因を特定でき、再試行でき、最終的に人間が責任を持って承認できることです。

よくある疑問を先に整理します

Agency Agentsはマルチエージェント基盤ですか？

厳密には、役割ごとの人格、作業手順、成果物、成功条件をまとめた設定ファイルの集合です。タスクの自動分配、認証、監査、実行環境、失敗時の再試行までを一体化した運用基盤ではありません。実行基盤はClaude Codeなど別のツールが担当します。

どのAIコーディングツールに対応していますか？

公式リポジトリではClaude Codeを中心に、Cursor、Codex、Gemini CLI、GitHub Copilot、Aider、Windsurfなどへの変換・導入スクリプトが案内されています。ただし、各ツールで読み込む場所や書式が異なるため、導入前に公式READMEの対応状況を確認してください。対応内容は更新される可能性があります。

役割はどのように選べばよいですか？

最初から全役割を入れず、実際の作業で頻繁に発生する計画、実装、レビューの3系統から選ぶ方法が安全です。各役割に入力、担当範囲、出力形式、完了条件を与え、同じ内容を繰り返す役割は統合します。

専門家Agentは直列と並列のどちらで動かしますか？

前提条件がある作業は直列、同じ成果物を参照するだけの調査やレビューは並列が基本です。同じコードファイルを複数Agentが編集する場合は、Gitのブランチまたはworktreeで作業領域を分け、最後に人間が統合します。

Agency Agentsは企業プロジェクトで使えますか？

利用は可能ですが、役割設定を配置しただけで企業向け統制が完成するわけではありません。秘密情報、実行権限、ネットワーク、ログ、データ保存期間、承認者を別に定義し、隔離された環境で小規模な実案件から検証する必要があります。

現在の構成とMac環境を比較する

ローカル端末だけでAgency Agentsを動かす構成は、初期検証には向いています。しかし、端末のスリープ、依存環境の差、権限設定のばらつき、複数AgentによるCPU・メモリ競合が起きやすい点は無視できません。

反対に、Mac環境をレンタルして実行環境を分けると、長時間タスク、Xcode系の作業、開発者端末から切り離した検証を組みやすくなります。ただし、物理デバイス接続や長期固定の高負荷処理では、自社保有環境や専用基盤の方が合う場合もあります。

私たちの判断では、まず計画担当、実装担当、レビュー担当の3役を1つの実案件で検証します。役割が互いに補完し、失敗を再試行できることを確認した後、並列実行や長期稼働が必要になった段階で、Macのリモート実行環境のような隔離構成を比較するのが無理のない進め方です。

Agency Agentsだけで十分なのは、短時間の個人作業や、人間が常に確認できる小規模な試行です。複数チームが同じコードや顧客データを扱う場合は、役割設定の追加より先に、権限、ログ、ブランチ、承認、再実行環境を整える必要があります。最初の一歩は、計画・実行・審査の3役を実案件で試し、必要になった時点で実行環境を拡張することです。