Paperclip Multi-Agent Workflow入門

症状：Agentは動いているのに、誰が何を担当し、どこで止まったのか追えない。
最短解決：PaperclipをモデルやAgent本体の代わりではなく、役割・タスク・承認・予算を束ねる制御層として導入し、最初は人が確認できる1本の小さなフローだけを動かします。

Paperclip Multi-Agent Workflowが向いているのは、すでに実行可能なAgent、モデルの認証情報、検証したい業務目標があり、それらを組織構造と状態管理で運用したい場合です。インストールだけで自動化が完成する製品ではありません。

この記事は、複数の既存Agentを追跡可能な流れに組み立てたい開発者、委譲と承認が必要な自動化チーム、長時間タスクを常駐環境で回したい技術責任者向けです。

最終更新：2026年8月14日。公式README、公式ドキュメントのインストール、Agent実行、承認、予算、デプロイ資料を確認しています。APIやアダプターの仕様は更新後に再確認してください。 (github.com)

まずPaperclipの担当範囲を切り分けます

Paperclipの中心は、AIモデルを推論させる部分でも、Agentの人格やツールを設計する部分でもありません。公式の製品定義では、会社の目標、Agentの上下関係、タスク、ハートビート、予算、承認を扱う「制御層」として説明されています。Agentは別の実行環境で動き、Paperclipへ状態や結果を返します。 (paperclip.inc)

この境界を先に理解しないと、次のような問題が起きます。

• Paperclipを入れればモデルやAPIキーも用意されると思い込み、Agentが起動しない。
• 組織図だけを大きくし、実際の成果物や完了条件が曖昧になる。
• 1つのAgentに広いファイル権限や本番用の認証情報を渡し、委譲経路から越権操作が可能になる。
• 失敗したタスクを自動再実行するだけで、同じ通知、同じ課題作成、同じファイル変更を繰り返す。
• ローカル画面では動いても、端末を閉じるとハートビート、作業ディレクトリ、セッションが失われる。

Paperclipの公式ドキュメントでは、Agentの実行はトリガー、アダプター呼び出し、Agentプロセス、タスク更新、結果保存、実行記録という流れで整理されています。つまり、AI Agent編成の成否はAgent数よりも、各段階で責任と復旧方法を定義できているかで決まります。 (paperclip.inc)

初日に作るのは「小さな会社」ではなく検証可能な1本です

第一段階：役割を3つ以内に絞ります

最初から大量のAgentテンプレートを読み込んで全員を起動するのは避けてください。最初の構成は、例えば「責任者」「実行担当」「確認担当」の3役で十分です。

責任者は目標を分解し、実行担当へ子タスクを渡します。実行担当はファイル作成や調査などの作業を行い、確認担当は完了条件を確認します。役割が重なると、同じタスクを複数Agentが取り合ったり、誰も最終判断をしなかったりします。

Paperclipの会社は目標、Agent、タスク、予算をまとめる単位です。会社を複数作る場合は、プロジェクトの目的だけでなく、Agent、タスク、予算を分離したい明確な理由があるときに限定してください。公式の初回セットアップ資料でも、まず1つの会社と少数のAgentから始める流れが案内されています。

第二段階：目標を成果物の言葉へ変換します

「マーケティングを自動化する」では検証できません。「指定した資料を読み、根拠付きの下書きを作り、人間の確認待ちにする」のように、入力、出力、完了条件、禁止操作を分けます。

Paperclipを使ったAgentタスク管理では、タスクを細かくすること自体が目的ではありません。1回のハートビートで判断でき、失敗時に再開位置を特定できる粒度へ分けることが重要です。

最初のワークフローで状態遷移を検証します

Paperclipの基本的な流れは、目標を親タスクへ置き、責任者が子タスクを作成し、担当Agentが作業し、結果をコメントや成果物として返し、上位Agentまたは人間が次の状態へ進める形です。ルーティンやWebhookなどのトリガーからタスクを作成し、担当Agentを起動する構成も公式資料に示されています。 (docs.paperclip.ing)

最初のテストでは、成功ケースだけでなく次の3つを意図的に確認してください。

1. 実行担当がタスクを取得し、in_progressへ進められるか。
2. 途中で失敗したとき、同じタスクを再開できるか。
3. 人間が停止、再割り当て、承認、修正要求を行えるか。

注意：自動再試行の前に、タスクの重複実行を防ぐ条件を置いてください。外部APIへの送信、課金処理、公開操作は「再実行しても同じ結果になる」設計か、承認待ちで止める設計にします。

初日の接続で確認する4つの境界

Paperclipが接続できるAgentは、特定の1製品に限られません。公式のアダプター資料では、ローカルCLI型、Process型、HTTP型、外部プラグイン型が示されており、Agentの実行方式に応じて接続方法を選びます。CLI型は、実行ホストに対応するCLIと認証済みセッションが必要です。 (github.com)

接続時は、次の順番で確認します。

1. 実行場所：AgentがPaperclipと同じ端末、SSH先、サンドボックスのどこで動くかを決めます。
2. 認証情報：APIキーやセッションを環境変数またはシークレットとして渡し、タスク本文へ直接書きません。
3. 作業ディレクトリ：読み書き可能な範囲をプロジェクト単位で分け、ホーム全体や本番サーバーを安易に公開しません。
4. 外部操作：HTTP、シェル、Git、データベースなどの権限を用途別に分け、責任者Agentにも不要な実行権限を与えません。
5. 終了条件：Agentが完了、失敗、確認待ち、停止のどれを返すのかを決め、無制限のループを許可しません。

PaperclipとCrewAIの違いを検討する場合も、機能数ではなく層で比較してください。CrewAIはAgent、Crew、Flowをコードで設計し、順次処理やイベント駆動の自動化を組み立てるフレームワークです。Paperclipは、すでにあるAgentを組織、課題、承認、予算、監査ログで運用する側に重心があります。両者は置き換えではなく、併用できる関係です。 (docs.crewai.com)

1週間目に治理と観測を追加します

人工承認は「重要そうな場面」ではなく不可逆操作の前に置きます

多 Agent プラットフォームで人間が確認すべきなのは、すべての小さな推論ではありません。Agentの追加、戦略の確定、本番データ変更、外部公開、予算上限の変更など、後から戻しにくい操作です。

Paperclipの承認機能では、Agentの追加要求や戦略提案を保留し、承認、却下、修正要求を選択できます。承認待ちで止まるタスクを作る場合は、「誰が」「何を見て」「どの条件なら承認するか」をタスク説明に書いてください。 (docs.paperclip.ing)

ログは成功確認ではなく失敗原因の特定に使います

画面が開き、Agentが1回動いたことだけでは運用開始と判断できません。実際のタスクを使い、次の異常を探します。

• 同じ子タスクが複数回作られる。
• 上位Agentが完了通知を受けても再度同じ担当へ委譲する。
• コメントは増えるが、タスク状態が進まない。
• 認証情報の不足で毎回同じハートビートが失敗する。
• コンテキストが切れ、前回の成果物や判断理由を再取得できない。
• 予算上限に近づいても担当者へ通知されない。

Activity Logでは、タスク状態の変更、Agentの起動、承認、予算イベントなどを時系列で確認できます。障害時はAgentの発言だけでなく、誰がどの状態変更を行ったかをログで照合してください。 (docs.paperclip.ing)

サーバーへ移すときは永続性を先に決めます

個人の試用や短いデモなら、ローカル環境のlocal_trustedで始められます。ただし、複数人が利用する場合、外部端末から接続する場合、端末を閉じても実行を継続したい場合は、認証付きの常駐環境へ移行してください。公式資料では、ローカル専用、認証付きプライベート、認証付き公開という運用区分が案内されています。 (docs.paperclip.ing)

公式のサーバー導入手順では、専用ユーザー、認証付き公開モード、永続ボリューム、外部データベース、TLSを組み合わせます。小規模なLinux VPSの例もありますが、必要なCPUやメモリは接続するAgent、同時実行数、データベース、ログ量によって変わるため、記事の目安をそのまま本番要件にしないでください。 (docs.paperclip.ing)

実際の移行手順は次の順番です。

1. ローカルで1本のフローを完了させ、成果物と失敗時の復旧方法を記録します。
2. Paperclipのデータ、シークレット、設定、作業ディレクトリを分けてバックアップします。
3. サーバー上へ専用ユーザーを作り、AgentのCLIと認証状態を個別に確認します。
4. 認証付きの非公開環境で接続し、外部公開前にログインと権限を検証します。
5. TLS、永続ストレージ、データベース、再起動後のハートビート継続を確認します。
6. APIキー、Agentトークン、外部サービスの鍵を定期的に交換できる手順へ落とします。
7. 本番相当のタスクを1件だけ実行し、停止、再開、再割り当て、バックアップ復元を試します。

Paperclipの予算管理は、会社単位、Agent単位、プロジェクト単位で支出上限を設ける考え方です。警告しきい値を超えたときの通知や、上限到達時の自動停止を想定し、予算を後から設定するのではなく、初回の実行前に低い上限で始め、実際の消費を見ながら調整してください。

Agentを増やす前に完了条件を通過させます

次の項目をすべて確認できるまでは、既成のAgent企業テンプレートを大量に追加したり、並列実行数を増やしたりしないでください。

• [ ] 1つの目標から親タスクと子タスクを追跡できる
• [ ] 各Agentの役割、入力、出力、禁止操作が重複していない
• [ ] Agentが担当外のプロジェクトや作業ディレクトリへアクセスできない
• [ ] タスクの完了、失敗、確認待ち、停止を状態として区別できる
• [ ] 同じタスクを再試行しても二重登録や二重送信が起きない
• [ ] 承認前に公開、本番変更、Agent追加が実行されない
• [ ] 実行ログから失敗したハートビートと原因を特定できる
• [ ] 予算超過時に自動停止し、担当者が再開条件を判断できる
• [ ] サーバー再起動後も設定、シークレット、タスク履歴を復元できる
• [ ] 人間が介入する箇所と、介入後に誰が処理を再開するか決まっている

結果品質、タスク完了率、人工介入点、権限隔離、故障復旧を確認してから、Agentの役割を増やしてください。Agentの数は生産性の指標ではありません。少ないAgentで責任境界と復旧経路が明確なほうが、運用上は強いケースが多くあります。

常駐環境では現在の構成とMac構成を比較します

自宅やオフィスの個人端末でPaperclipを動かす方法は、初期検証には向いています。しかし、スリープやOS更新でセッションが切れやすく、担当者が変わると認証情報や作業ディレクトリの再現が難しく、複数Agentを同時に走らせるほど権限とログの分離も複雑になります。

LinuxサーバーはCLI中心のAgentには合理的ですが、macOS専用ツール、Xcode、Apple関連のビルドやGUI操作を含む場合は別の実行環境が必要です。長時間稼働、遠隔協業、複数プロジェクトの隔離が目的なら、Paperclipの制御層と、用途ごとに分けたMac環境を組み合わせたほうが、端末依存や担当者依存を減らしやすくなります。

短期の検証や一時的なAgent実行であれば、MacstripeのMac環境の設定方法を確認し、必要な作業ディレクトリと接続方式を先に決めてください。運用前に困った場合は、ヘルプセンターで接続、継続稼働、引き渡し条件を確認しておくと、Paperclip側の障害と実行環境側の問題を切り分けやすくなります。

Paperclipを長期運用するなら、現在の個人端末構成よりも、常時接続、遠隔協業、Agentごとの隔離、再起動後の復旧を設計しやすいMac環境を選ぶ価値があります。ただし、物理機器への直接アクセスが必要な処理や、毎月安定して高負荷をかけ続ける用途では、専用の自社設備を購入したほうが適する場合もあります。短期間の試験環境、チームの検証、複数Agentの安全な切り分けが目的なら、Macstripeのレンタル環境を使って現在の構成と比較し、常駐化する前に実際の引き渡しと復旧手順まで確認するのが現実的です。