agent-builder

Agent Builder

1～2 のことを卓越して実行する、焦点を絞ったマイクロエージェントを構築します。

ルーティング (必ず判断してください)

ユーザーがエージェントの作成を依頼した場合、適切なパスを選択してください:

agent_build (単数) — 1 スキル、1 データソース、シンプルな定期的タスク、1～5 回のツール呼び出し。

agent_build + always_on=True — 24 時間 365 日稼働し、5 分ごとに受信箱のメッセージをポーリングするエージェント。デスクに座っている従業員のようなものです。

agent_team (チーム) — 2 つ以上のスキル、並列データ収集、統合が必要、10 回以上のツール呼び出し。

agent_loop (長時間実行) — 自由形式の調査、反復的な蓄積、固定のエンドポイントなし。

agent_message — 任意のエージェントの受信箱にメッセージを送信します。ユーザー→エージェントおよびエージェント→エージェントの両方で機能します。

判断に迷った場合: 単数から始めてください。最も低コストです。後からアップグレードできます。

ツール

ツール	用途
agent_build	エージェントを作成または更新します。デーモンモードには always_on=True を設定します。
agent_task	タスクの追加/更新/完了/削除/一覧表示。set_status で一時停止/アーカイブ/再有効化も可能です。
agent_run	エージェントを 1 回実行します (最も優先度の高い保留中のタスクを選択します)
agent_list	すべてのエージェントをステータス、タスク数とともに一覧表示します。チーム/ステータスでフィルタリングできます。
agent_team	チームを作成して実行します (リーダー + コスト最適化されたモデルを持つワーカー)
agent_loop	エージェントをループモードで実行します — 目標が満たされるか予算が尽きるまで反復します
agent_message	エージェントの受信箱にメッセージを送信します。デーモンが次回のポーリングで取得します。

単数エージェントのワークフロー

1. 作成

agent_build(
  name="market-scout",
  display_name="Market Scout",
  role="Crypto market surveillance specialist",
  goal="Monitor BTC and ETH prices, flag anomalies",
  skills=["coingecko", "chart"],
  template="monitor",
  mode="research",
  schedule="0 8 * * *",
  timezone="Asia/Kuala_Lumpur"
)

テンプレート: default、monitor、researcher

モード:

• default — 自由な思考
• research — ハルシネーション防止ガードレール: 「わかりません」と言うこと、情報源を引用すること、分析前に引用を抽出することが必須

スケジュール: Cron ("0 8 * * *")、インターバル ("every 30 minutes")、遅延 ("in 2 hours")、指定時刻 ("at 2026-05-01 14:00")

2. タスクの追加

agent_task(agent="market-scout", action="add",
  title="Check BTC price",
  priority="high",
  due_date="2026-04-26",
  recurring=True,
  depends_on=["task-id-of-prerequisite"]
)

• 優先度: low (60 秒、2 回呼び出し)、medium (120 秒、5 回呼び出し)、high (180 秒、10 回呼び出し)、critical (300 秒、20 回呼び出し)
• 定期実行: 完了後に保留中にリセットされ、履歴を記録します
• depends_on: タスクの連鎖 — 依存関係が完了するまでブロックされます

3. 実行

agent_run(agent="market-scout")

4. 管理

agent_task(agent="market-scout", action="set_status", status="paused")
agent_list(team="market-sentiment", verbose=True)

チームワークフロー

1. チームの作成

agent_team(action="create",
  name="market-sentiment",
  leader={"name": "analyst", "role": "Synthesize sentiment", "skills": ["chart"]},
  workers=[
    {"name": "btc-fetcher", "role": "Fetch BTC tweets", "skills": ["twitter"]},
    {"name": "eth-fetcher", "role": "Fetch ETH tweets", "skills": ["twitter"]},
  ]
)

リーダー: Sonnet ($3/$15)。ワーカー: Haiku ($1/$5)。約 67% の節約。

2. チームの実行

agent_team(action="run", name="market-sentiment",
  goal="Cross-chain sentiment comparison for BTC and ETH"
)

リーダーがパイプライン全体を担当します: ワーカータスクを作成 → ワーカーを実行 → 待機 (bash ポーリング) → 出力を読み取り → 統合します。

ループモード (長時間実行)

固定のエンドポイントがない自由形式のタスク向け:

agent_loop(agent="uni-scout",
  goal="Find universities with AI programs open to collaboration",
  max_iterations=10,
  output_file="candidates.json",
  timeout=1800
)

エージェントは反復します: 進捗を読み取る → 検索 → 結果を追加 → 評価 → 続行/停止。

予算レジームは反復が進むにつれて戦略を適応させます:

• EXPLORE (初期) → CONVERGE (中期) → FOCUS (後期) → FINALIZE (終盤)

停止条件: エージェントが完了と判断、最大反復回数、または 2 回連続の空振り反復。

常時稼働エージェント (デーモンモード)

24 時間 365 日稼働し、メッセージとタスクをポーリングするエージェントを作成します:

agent_build(name="ai-scout", display_name="AI Scout",
    role="Research AI content creators on Twitter",
    goal="Build a database of high-quality AI creators",
    skills=["twitter"], template="researcher", mode="research",
    always_on=True, team="marketing"
)

次にデーモンを起動します:

scheduled_task(action="activate", job_id="<daemon_job_id from output>")

5 分ごとに、デーモンは以下を実行します:

1. inbox.json をチェック — 新しいメッセージはありますか？ 処理し、応答し、ユーザーにプッシュします。
2. tasks.json をチェック — 保留中のタスクはありますか？ 最も優先度の高いものを実行します。
3. どちらもない場合？ 自律的な作業 — 自身の目標、メモリ、既存の出力を読み取り、目標を前進させるために次に最も価値のあることを能動的に実行します。30 分ごとに実行されます (クールダウンにより毎回のポーリングでトークンを消費するのを防ぎます)。

エージェントに生産的なことが何もない場合 (目標が完全に満たされている場合)、AUTONOMOUS_IDLE を出力し、コストは $0.00 になります。

メッセージング

任意のエージェントにメッセージを送信します — ユーザーからエージェント、またはエージェントからエージェント:

agent_message(agent="ai-scout", message="Focus on creators with 100K+ followers who post about LLMs")
agent_message(agent="marketing-lead", message="5 new creators found", from_agent="ai-scout")

メッセージは inbox.json にキューイングされます。エージェントのデーモンが次回のポーリング (最大約 5 分) で処理します。 応答は outbox.json に表示され、ユーザーにプッシュされます。

エージェントの管理

すべてはいつでも変更可能です：

• 一時停止： agent_task(agent="x", action="set_status", status="paused") — デーモンは一時停止中のエージェントをスキップします
• 再開： agent_task(agent="x", action="set_status", status="active")
• デーモンの停止： scheduled_task(action="cancel", job_id="<id>") — キャンセルは永続的です。以下のデーモンのライフサイクルを参照してください
• 役割／スキル／モードの変更： 新しいパラメータで agent_build を再実行します — 設定が上書きされます
• 新しい指示の送信： agent_message(agent="x", message="change focus to...")
• 調査結果の確認： read_file("agents/team/agent/output/results.json")
• 削除： ディレクトリを削除します — エージェントは単なるファイルです

デーモンのライフサイクル（重要）

キャンセルは永続的です。 scheduled_task(action="cancel") はジョブを削除します。再有効化することはできません。キャンセルされたデーモンを再起動するには：

1. always_on=True を指定して agent_build を再実行します — 新しいスケジュール済みタスクが登録されます
2. 新しいタスクには新しい job_id が付与されます — 古い run.py の JOB_ID は古くなっています
3. agent_build は新しい run.py に正しい JOB_ID を自動的に書き込みます
4. 有効化： scheduled_task(action="activate", job_id="<new_id>")

JOB_ID はアクティブなタスクと一致している必要があります。 run.py 内の JOB_ID は、プッシュ通知を正しいジョブにルーティングするためのものです。run.py を手動でコピーする場合は、JOB_ID 定数を更新してください。そうしないと、プッシュ通知は通知先のないジョブに黙って送信されてしまいます。

エージェントのアクション前推論

すべてのエージェントテンプレートに、ツール呼び出しの前に行う必須の推論フレームワークが含まれるようになりました：

• WHO が影響を受けますか？
• WHAT を正確に実行しますか？
• WHY それがゴールの前進につながりますか？
• RISK — 安全／中程度／破壊的？

破壊的なアクション（削除、上書き、クリア）では、エージェントは実行前に停止してプレビューを生成する必要があります。これにより、偶発的なデータ損失を防ぎます。

出力契約

すべてのエージェントには、プロンプトに組み込まれた必須の出力契約があります：

• 主要な出力は常に JSON ファイルです（output/results.json）
• JSON が先、人間が読める要約が後
• 実行のたびに：既存を読み込み → 新規を追記 → 書き戻す（最初から上書きしない）
• 下流のエージェントやシステムは markdown ではなく JSON を読み取ります

これにより、エージェントが文章を書いても構造化出力を更新しない「美しいレポートだが空のデータベース」という問題を防ぎます。

重複排除

すべてのテンプレートは、項目を追加する前に重複をチェックするようエージェントに指示します：

• 主識別子（名前、ハンドル、URL、または ID）で照合します
• 重複をスキップし、スキップ件数をログに記録します
• 重複排除は後からのクリーンアップ作業ではなく、最初の実行から設計に組み込みます

リソースの所有権

1 つのエージェントが 1 つのリソースを所有します。すべてのテンプレートに組み込まれたルール：

• エージェントは自身の output/、memory/、scripts/ ディレクトリにのみ書き込みます
• 複数のエージェントが同じ送信先にデータを供給する必要がある場合、それぞれが自身の output に書き込み、指定された同期エージェントがマージを処理します
• 2 つのエージェントが同じファイルに書き込んではいけません

ターゲティング基準

リサーチャーエージェントには明示的なターゲティング範囲が含まれます：

• 適合スコア 1〜10、スコア 6 以上の項目のみを含めます
• 到達可能性 — 実際に連絡できる相手を優先します
• 関連性 — 隣接的／周辺的ではなく、ゴールに直接関連している必要があります
• タスクの説明に明示的な上限／下限を設定します（フォロワー数範囲、地域など）

破壊的操作のガード

エージェントは、最初にプレビューを生成しない限り、重要なデータを削除、クリア、上書きできません。アクション前推論フレームワークは、すべてのアクションを安全／中程度／破壊的に分類します。破壊的なアクションには以下が必要です：

1. 何が変更されるかのプレビュー
2. 実行前の明示的な確認

プラットフォームツールの信頼性

プラットフォームツール（send_to_telegram、composio 連携など）は、基盤となるサービスが誤設定されているかセットアップ待ちの場合、黙って失敗することがあります。外部配信に依存するデーモンエージェントの場合：

• デーモンで依存する前に、必ずツールが手動で動作することを確認してください
• 重要な配信経路には直接 API のフォールバックを構築してください
• ツールの出力を確認してください — 黙って失敗した場合は、実際の配信なしで成功が返されます

ループモードの停止シグナル

agent_loop において、「ドライイテレーション」とは、エージェントが検索したものの、出力ファイルに追加すべき新しい項目が 1 件も見つからなかったことを意味します。エージェントはこれを、そのイテレーションの score.json に "new_items": 0 と書き込むことで通知します。ドライイテレーションが 2 回連続すると停止です。

エージェントは、最終メッセージとして LOOP_COMPLETE というテキストを出力することで、完了を通知します。目標を達成した後も実行し続ける場合は、タスクの説明に明示的な停止条件を追加してください。「20 件以上になったら停止する」または「カバレッジに US、UK、Asia が含まれたら停止する」といった具合です。

GUARDRAILS.md

すべてのエージェントには GUARDRAILS.md ファイルが与えられます。これは、学習された制約事項を記録するリビングドキュメントです。エージェントは、失敗パターンを発見するたびにエントリを追記してください。

## Trigger: Writing to output without reading existing content
Instruction: ALWAYS read the output file before writing
Reason: Previous run overwrote 15 valid entries with 3 new ones

ディレクトリ構造

agents/
├── marketing/                     ← team folder
│   ├── team.json                  ← team config (leader, workers, models)
│   ├── analyst/                   ← leader agent
│   │   ├── agent.yaml
│   │   ├── PROMPT.md
│   │   ├── GUARDRAILS.md          ← learned constraints
│   │   ├── tasks.json
│   │   ├── references/
│   │   ├── scripts/
│   │   ├── output/results.json    ← mandatory JSON output
│   │   ├── inbox.json             ← messages (always-on)
│   │   ├── outbox.json
│   │   └── memory/MEMORY.md
│   ├── btc-fetcher/               ← worker
│   └── eth-fetcher/               ← worker
├── btc-watcher/                   ← singular agent (flat)
└── hackathon-scout/               ← singular agent (flat)

設計原則

1. 集中的 — 各エージェントは 1〜2 個のことを行います。スコープの肥大化に抵抗してください。
2. 分離 — 各エージェントは自身のディレクトリを所有します。エージェント間での書き込みは行いません。
3. 観測可能 — タスクにはステータス、優先度、期限、リトライ回数、履歴があります。
4. 組み合わせ可能 — 作成、一時停止、アーカイブ、削除を独立して行えます。
5. 段階的 — コンテキストはレイヤー状に読み込まれます (L1 メタデータ → L2 プロンプト → L3 参照はオンデマンド)。
6. 自己改善 — エージェントは実行のたびに、学習内容をメモリと GUARDRAILS.md に書き込みます。
7. コスト意識 — 優先度がタイムアウト、ツール呼び出しの予算、モデルのヒントを決定します。
8. JSON ファースト — 文章よりも先に構造化出力。ダウンストリームのシステムは JSON を読み取ります。
9. 重複排除ファースト — 挿入する前に確認してください。最初の実行から重複排除を設計に組み込んでください。
10. デフォルトで安全 — 破壊的な操作にはプレビューと確認が必要です。ドライランモードを用意してください。