エージェントをAPIでトリガーする
スケジュール実行に加えて、外部ワークフローからSquadbaseのエージェントをオンデマンドで呼び出します
エージェントを作成すると、設定したスケジュールに従って自動実行されます。それに加えて、同じエージェントを Squadbase API 経由でオンデマンド実行することもできます。次のスケジュールを待たずに、外部システムが必要なタイミングでエージェントを起動できます。
こんなときに使う
APIでトリガーすることで、エージェントを外部のワークフロー / 自動化ツール（Zapier、n8n、Make など）や、cron、社内ツール、CI、チャットボットなどに組み込めます。
代表的なのはレポーティングの自動化です。外部ワークフローがイベント（商談の成立、フォーム送信、ビルド完了など）を検知してエージェントを呼び出し、最新データを分析してメール・Slack・Microsoft Teams にレポートを配信する、といった処理を人手を介さずに実行できます。
ユースケース例
- イベント駆動レポート — Zapier / n8n のワークフロー発火時（スプレッドシートへの行追加、プロダクトからのWebhook など）に、エージェントを起動して該当レポートを作成・送信する。
- ツール横断のオーケストレーション — Squadbase の エージェントを大きな自動化パイプラインの1ステップとして組み込み、その結果を後続処理に渡す。
- 自社ツールからの随時実行 — 社内アプリに「レポート生成」ボタンを設置し、エージェントを直接呼び出す。
仕組み
作成済みのエージェント（データソース・指示・通知設定）は、設定どおりにそのまま実行されます。違うのは「何が起動するか」だけで、スケジュールの代わりにAPI呼び出しがエージェントを起動します。
エージェントをトリガーするには次の2つが必要です。
- APIキー — Squadbaseのアカウント設定から作成します。詳細は APIキー認証 を参照してください。
- 実行したいエージェントの エージェントID。
その実行だけに渡す指示として、任意の message を添えることもできます。
トリガーエンドポイントは非同期です。APIは実行開始時点（status: RUNNING）ですぐに応答し、エージェントは完了後に結果を設定済みの通知先へ配信します。
curl -X POST 'https://api.squadbase.dev/v0/agent/<AGENT_ID>/trigger' \
-H 'x-api-key: <YOUR_API_KEY>' \
-H 'Content-Type: application/json' \
-d '{"message":"今週のサインアップ動向を分析して","title":"週次分析"}'レスポンスには executionId が含まれます。通知先への配信に加えて、これを使って実行状態のポーリングや実行結果の取得をプログラムから行えます。
自動化ツールが失敗したリクエストを再送する場合は、Idempotency-Key ヘッダーを付与すると、再送によって実行が重複しません。同じキーは元の実行を返します。任意項目で、省略した場合はリクエストごとに新しい実行が開始されます。詳細は エージェントの実行 を参照してください。
リクエストボディ・状態取得/結果取得エンドポイント・レスポンス・エラーコードの詳細や、Python / Node.js の例を含む完全な仕様は、API概要 を参照してください。