Agent Group 非同期実行API (ベータ版)

このドキュメントは、エージェントグループの非同期実行についてのAPI仕様を説明します。

概要

Agent Group非同期実行APIを使用することで、複数のエージェントを組み合わせたグループを作成し、バックグラウンドで協調的にタスクを実行できます。処理完了時にはWebhook通知で結果を受け取ることができます。

エンドポイント

POST /agent-groups/start

認証

APIキー認証のみをサポートします：

X-API-Key: <admin-api-key>

miiboの管理画面から発行できる「エージェント管理者」用のAPIキーを利用します。

リクエスト仕様

Content-Type

Content-Type: application/json

リクエストボディ

{
  "utterance": "ユーザーの最初の発話内容",
  "uid": "your-uid",
  "agentIds": [
    {
      "agentId": "agent-001",
      "apiKey": "agent-api-key-001"
    },
    {
      "agentId": "agent-002",
      "apiKey": "agent-api-key-002"
    }
  ],
  "groupName": "グループ名",
  "groupPrompt": "チーム全体の行動指針（オプション）",
  "groupMission": "グループのミッション",
  "groupDescription": "グループの説明",
  "resultWebhookUrl": "https://your-webhook-url.com/callback",
  "customParameters": {
    "key1": "value1",
    "key2": "value2"
  }
}

パラメータ詳細

フィールド	型	必須	説明
`utterance`	string	✓	ユーザーの発話内容（最大5000文字）
`uid`	string	✓	管理者のユーザーID
`agentIds`	AgentIdRequest[]	✓	管理者のエージェントIDとAPIキーの配列（最大5体）
`groupName`	string	✓	グループ名
`groupMission`	string	✓	グループのミッション
`groupDescription`	string	✓	グループの説明
`resultWebhookUrl`	string		結果通知用Webhook URL
`webhookHeaders`	object		Webhookリクエストに含めるカスタムヘッダー
`sendResultEmail`	boolean		メールで結果を送信するかどうか
`resultEmails`	string[]		結果送信先メールアドレス（最大5件、sendResultEmail=trueの場合必須）
`resultEmailTitle`	string		メール件名
`conclusionOnlyMode`	boolean		会話履歴を除いて最終結論のみを返すかどうか
`customWebhookBodyTmpl`	string		Webhookボディの内容
`customParameters`	object		任意のJSONパラメータ。Webhook通知時に何らかのパラメータを送信したいときに利用します。
`isSyncMode`	boolean		同期で実行をするかどうか(default: false) 非同期実行の場合、実行直後にresponseが返され、webhookで結果が通知されます。

AgentIdのRequest構造

{
  "agentId": "エージェントID",
  "apiKey": "エージェント用APIキー"
}

レスポンス仕様

成功レスポンス (200 OK)

{
  "status": "started",
  "groupId": "group-456",
  "result_url": "https://api.example.com/agent-groups/group-456/result"
}

APIの実行が正常に開始されると、miibo Agent Hub上で進捗を確認することができます。

レスポンスフィールド

フィールド	型	説明
`status`	string	処理ステータス（"started", "completed", "error"）
`groupId`	string	作成されたグループのID
`result_url`	string	結果取得用URL（オプション）

cURLサンプル

基本的な使用例

curl -X POST "https://your-api-host.com/agent-groups/start" \
  -H "Content-Type: application/json" \
  -H "X-API-Key: admin-api-key-123456789" \
  -d '{
    "utterance": "新商品のマーケティング戦略を考えてください",
    "uid": "user-uid-789",
    "agentIds": [
      {
        "agentId": "agent-marketing-001",
        "apiKey": "agent-api-key-marketing-001"
      },
      {
        "agentId": "agent-analytics-002",
        "apiKey": "agent-api-key-analytics-002"
      }
    ],
    "groupName": "マーケティング戦略チーム",
    "groupMission": "効果的なマーケティング戦略を立案し、実行計画を提案する",
    "groupDescription": "マーケティングと分析の専門エージェントチーム"
  }'

Webhook通知付きの例

curl -X POST "https://your-api-host.com/agent-groups/start" \
  -H "Content-Type: application/json" \
  -H "X-API-Key: admin-api-key-123456789" \
  -d '{
    "utterance": "顧客満足度向上のための施策を検討してください",
    "uid": "user-uid-789",
    "agentIds": [
      {
        "agentId": "agent-customer-service-001",
        "apiKey": "agent-api-key-cs-001"
      },
      {
        "agentId": "agent-data-analyst-002",
        "apiKey": "agent-api-key-da-002"
      }
    ],
    "groupName": "顧客満足度改善チーム",
    "groupMission": "顧客満足度を向上させるための具体的な施策を提案する",
    "groupDescription": "カスタマーサービスとデータ分析の専門チーム",
    "resultWebhookUrl": "https://your-webhook-endpoint.com/agent-group-results",
    "customParameters": {
      "projectId": "cs-improvement-2024",
      "priority": "high",
      "department": "customer-success"
    }
  }'

複数エージェントの例

curl -X POST "https://your-api-host.com/agent-groups/start" \
  -H "Content-Type: application/json" \
  -H "X-API-Key: admin-api-key-123456789" \
  -d '{
    "utterance": "新規事業計画の立案をお願いします",
    "uid": "user-uid-789",
    "agentIds": [
      {
        "agentId": "agent-business-planner-001",
        "apiKey": "agent-api-key-bp-001"
      },
      {
        "agentId": "agent-market-researcher-002",
        "apiKey": "agent-api-key-mr-002"
      },
      {
        "agentId": "agent-financial-analyst-003",
        "apiKey": "agent-api-key-fa-003"
      },
      {
        "agentId": "agent-legal-advisor-004",
        "apiKey": "agent-api-key-la-004"
      },
      {
        "agentId": "agent-tech-consultant-005",
        "apiKey": "agent-api-key-tc-005"
      }
    ],
    "groupName": "新規事業立案チーム",
    "groupPrompt": "チーム全体で協力し、実現可能性の高い新規事業計画を策定してください",
    "groupMission": "市場調査、財務分析、法的検討、技術的実現性を総合的に評価した新規事業計画を立案する",
    "groupDescription": "事業企画、市場調査、財務、法務、技術の各専門分野のエキスパートチーム",
    "resultWebhookUrl": "https://your-webhook-endpoint.com/business-plan-results",
    "customParameters": {
      "projectType": "new-business-planning",
      "budgetRange": "10M-50M",
      "timeline": "6months",
      "targetMarket": "B2B-SaaS"
    }
  }'

Webhook通知

処理完了時に指定されたWebhook URLに結果が通知されます。

Webhook通知ペイロード

{
  "groupId": "group-456",
  "status": "completed",
  "result": {
    "orchestrationResponse": {
      "finalResponse": "エージェントグループからの最終的な回答...",
      "interactions": [
        {
          "agentId": "agent-001",
          "response": "エージェント1の回答...",
          "timestamp": "2024-01-15T10:30:00Z"
        },
        {
          "agentId": "agent-002",
          "response": "エージェント2の回答...",
          "timestamp": "2024-01-15T10:32:00Z"
        }
      ]
    }
  },
  "customParameters": {
    "projectId": "your-project-id",
    "priority": "high"
  },
  "completedAt": "2024-01-15T10:35:00Z"
}

Webhookエラー時の通知

{
  "groupId": "group-456",
  "status": "error",
  "error": "エラーの詳細メッセージ",
  "customParameters": {
    "projectId": "your-project-id"
  },
  "errorAt": "2024-01-15T10:33:00Z"
}

制限事項

発話内容: 最大5,000文字
エージェント数: 1グループあたり最大5体
同時実行: ユーザーあたり最大5グループ
処理時間: 最大30分（タイムアウト）

APIキーの取得方法

Admin APIキー: miibo.dev でアカウント設定から取得
Agent APIキー: 各エージェントの管理者から発行を依頼

ベストプラクティス

miibo Agent Hubのエージェントグループのテンプレートを作成すると、API接続情報をスピーディに作成できます。