paperclip-create-agent

Paperclip エージェントの作成

Paperclip 本来の採用ワークフローを再現して、新しい Paperclip エージェントを作成します。

これはローカル環境に変更を加えるオペレータースキルです。自由に調査できますが、オペレーターが提案内容に明示的に承認するまでは、エージェントの作成、採用リクエストの送信、キーの作成、スキルの割り当て、権限の変更を行わないでください。

参考資料

まず、次の資料を読んでください。

• references/CONTEXT.md
• references/docs/paperclip-operator/control-plane.md
• references/docs/paperclip-operator/workflow.md
• references/docs/paperclip-operator/cli-contract.md
• references/docs/paperclip-operator/integration-matrix.md

Paperclip のドキュメントやソースから見つかった、参考になる上流のエンドポイント：

• GET /api/companies/{companyId}/agents
• GET /api/companies/{companyId}/org
• GET /api/companies/{companyId}/agent-configurations
• GET /api/companies/{companyId}/skills
• GET /llms/agent-configuration.txt
• GET /llms/agent-configuration/{adapterType}.txt
• GET /llms/agent-icons.txt
• POST /api/companies/{companyId}/agent-hires
• POST /api/companies/{companyId}/agents
• POST /api/agents/{agentId}/keys
• POST /api/agents/{agentId}/skills/sync

ワークフロー

1. コンテキストを確認します。

   CLI のコンテキストと現在の会社を読み取ります。ボードへのアクセス権、またはエージェントを作成する権限を確認します。現在の ID でエージェントを作成できない場合は、作成を試みず、採用提案または承認リクエストを準備します。

2. 会社の規約を確認します。

   既存のエージェント、組織図、会社のスキル、エージェント設定を読み取ります。命名規則、アイコン、報告先、アダプターの種類、モデル、環境の割り当て、デフォルト環境、予算の規約、ハートビートのデフォルト設定、必須の Paperclip スキルを確認します。

3. 作成方法を選びます。

   • ガバナンスが必要な場合、リクエストが別のエージェントまたは Issue から来た場合、またはオペレーターがボードで確認できる採用フローを希望する場合は、paperclipai agent hire -C <company-id> --payload-json <json> --json を優先します。インストール済みの CLI にこのコマンドがない場合に限り、POST /api/companies/{companyId}/agent-hires を代わりに使用します。
   • 会社のポリシーで認められており、直接作成が明示的に承認されている場合は、paperclipai agent create -C <company-id> --payload-json <json> --json を優先します。必要な場合に限り、POST /api/companies/{companyId}/agents を代わりに使用します。
   • レコードを安全に作成できる、認証済みの呼び出し可能な手段がない場合は、代替手段として Paperclip UI を使用します。

4. エージェントの内容を作成します。

   name、role、title、icon、reportsTo、capabilities、adapterType、adapterConfig、desiredSkills、管理対象の instructionsBundle、runtimeConfig.heartbeat、defaultEnvironmentId、budgetMonthlyCents、明示的な permissions、および採用のきっかけが Paperclip の作業である場合は sourceIssueId／sourceIssueIds を含めます。

5. 指示を作成します。

   利用可能であれば、役割に特化した、または関連する Paperclip テンプレートを優先します。それ以外の場合は、アイデンティティ、報告先、役割の指針、業務ワークフロー、専門分野の観点、成果物の基準、協業、安全性／権限、完了基準を網羅した簡潔な AGENTS.md を作成します。

   実行中心のエージェントには、次の契約を含めます。実行可能な作業は同じハートビート内で開始すること。計画が依頼された場合を除き、計画だけで終わらせないこと。次のアクションを明確にして、後から確認できる進捗を残すこと。長時間に及ぶ作業や並行して委任する作業には、ポーリングではなく子 Issue を使うこと。ブロックされた作業には、担当者とアクションを明記すること。予算、一時停止／キャンセル、承認ゲート、会社の境界を尊重すること。

6. 承認前に確認します。

   エージェントの重複、マネージャーの未設定、誤った役割、未対応のアダプター／モデル、スキルの不足、平文のシークレット、過剰に広い権限、不要なタイマーベースのハートビート、曖昧な機能、Paperclip の信頼できる情報源に関するルールと矛盾する指示がないか確認します。

7. オペレーターの承認を求めます。

   提案する作成方法、ペイロードの概要、マネージャー、アダプター／モデル、スキル、権限、予算、ハートビートのポリシー、環境、元となる Issue との関連付け、リスクのある設定を提示します。承認を待ちます。

8. 適用して確認します。

   ネイティブ CLI が利用できる場合はそれを使用し、利用できない場合は API／REST の代替手段を使用して、採用またはエージェント作成を行います。作成されたエージェントと承認を読み戻します。ステータスを確認します。

   • ガバナンスが適用される場合は、hire_agent 承認が付いた pending_approval
   • 直接作成に成功した場合は、idle または会社のデフォルトのアクティブ状態

   保存されたフィールドを確認します。name、role、reportsTo、アダプターの種類／設定、希望するスキル、指示バンドルのモード／パス、ハートビート設定、予算、権限、環境、元となる項目との関連付けを確認します。

9. 作成が有効であることを確認してから、ローカル CLI を設定します。

   実行可能なローカルエージェントには、次を使用します。

   paperclipai agent local-cli <agentRef> -C <company-id> --json
   

   有効期間の長い API キーをチャットに出力しないでください。キーを作成したことを要約し、必要に応じてコマンドがエクスポート情報を出力した場所をオペレーターに伝えます。

10. 結果を報告します。

エージェント ID／URL キー、該当する場合は承認 ID、ステータス、マネージャー、アダプター、スキル、ハートビートの状態、予算、次にオペレーターが行うアクションを含めます。

ペイロードに関する注意事項

現在の Paperclip ソースで有効なロールには、ceo、cto、cmo、cfo、security、engineer、designer、pm、qa、devops、researcher、general があります。

既知のアダプタータイプには、process、http、acpx_local、claude_local、codex_local、cursor_cloud、gemini_local、opencode_local、pi_local、cursor、openclaw_gateway があります。

codex_local では、従来のプロンプトフィールドよりも管理対象の指示を優先してください。一般的なアダプター設定には、cwd、model、env、timeoutSec、graceSec、fastMode のほか、明示的に承認されたサンドボックス／承認バイパス設定のみが含まれます。

変更に関するルール

採用者の作成、直接エージェントの作成、必要なスキルの割り当て、API キーの作成、権限の変更、シークレット／環境変数のバインド設定、タイマーハートビートの有効化、または作業の割り当てを行う前に、確認してください。他のエージェントのハートビートを手動で実行してはいけません。Paperclip エージェントは、対象となる作業が割り当てられると、それぞれのハートビートポリシーに従って起動します。