BLUEPRINT

第6章：呼び出しプロトコル

6.1 概要

Invocation Protocol（呼び出しプロトコル）は、スキル消費者が発見済みのスキルをリモートで呼び出す方法を定義します。プロトコルは非同期呼び出しモデルを採用し、状態クエリと結果取得をサポートします。

6.2 呼び出しフロー

3ステップ呼び出しモデル

ステップ	HTTPメソッド	エンドポイント	説明
1. 呼び出し開始	POST	`{invocation_endpoint}`	呼び出しリクエストを送信、実行IDを返す
2. 状態クエリ	GET	`{status_url}/{execution_id}`	実行状態を照会
3. 結果取得	GET	`{result_url}/{execution_id}`	実行結果を取得

呼び出しシーケンス

消費者                                提供者
  │                                      │
  │── POST /invoke ──────────────────────→│
  │   {caller, skill_id, inputs}         │
  │                                      │
  │←── 202 Accepted ────────────────────│
  │   {execution_id, status: "accepted"} │
  │                                      │
  │── GET /status/{execution_id} ───────→│
  │                                      │
  │←── {status: "running"} ─────────────│
  │                                      │
  │── GET /status/{execution_id} ───────→│
  │                                      │
  │←── {status: "completed"} ───────────│
  │                                      │
  │── GET /result/{execution_id} ───────→│
  │                                      │
  │←── {output: {...}} ─────────────────│
  │                                      │

6.3 呼び出しリクエスト形式

{
  "caller": {
    "id": "ifay-instance-001",
    "type": "ifay",
    "credentials": {
      "api_key": "sk-xxxxx"
    }
  },
  "skill_id": "com.example.translate-v1",
  "inputs": {
    "text": "Hello, world!",
    "target_language": "zh-CN"
  },
  "context": {
    "trace_id": "trace-abc-123",
    "priority": "normal",
    "timeout_ms": 30000
  }
}

リクエストフィールド

フィールド	型	必須	説明
`caller`	object	はい	呼び出し者の身元情報
`caller.id`	string	はい	呼び出し者の一意識別子
`caller.type`	string	はい	呼び出し者タイプ（ifay/service/user）
`caller.credentials`	object	いいえ	認証資格情報
`skill_id`	string	はい	ターゲットスキルID
`inputs`	object	はい	入力パラメータ（キーバリューペア）
`context`	object	いいえ	呼び出しコンテキスト
`context.trace_id`	string	いいえ	トレースID
`context.priority`	string	いいえ	優先度（low/normal/high）
`context.timeout_ms`	number	いいえ	タイムアウト時間（ミリ秒）

6.4 呼び出しレスポンス形式

{
  "execution_id": "exec-789-xyz",
  "status": "completed",
  "skill_id": "com.example.translate-v1",
  "output": {
    "translated_text": "你好，世界！",
    "source_language": "en",
    "target_language": "zh-CN",
    "confidence": 0.98
  },
  "timestamps": {
    "created_at": "2025-03-20T14:30:00Z",
    "updated_at": "2025-03-20T14:30:02Z",
    "completed_at": "2025-03-20T14:30:02Z"
  }
}

レスポンスフィールド

フィールド	型	必須	説明
`execution_id`	string	はい	実行一意識別子
`status`	ExecutionStatus	はい	実行状態
`skill_id`	string	はい	ターゲットスキルID
`output`	any	いいえ	出力データ（completed時）
`error`	object	いいえ	エラー情報（failed/timeout時）
`timestamps`	object	はい	タイムスタンプ情報

実行状態列挙

状態	説明
`accepted`	リクエスト受信済み、実行待ち
`running`	実行中
`completed`	実行正常完了
`failed`	実行失敗
`timeout`	実行タイムアウト

6.5 認証フロー

呼び出し前に、消費者はSkill Descriptorのauthフィールドを確認します：

消費者                                提供者
  │                                      │
  │── descriptor.auth を読み取り ──→      │
  │                                      │
  │   auth.type == "api_key"?            │
  │   → HeaderにAPI Keyを付加            │
  │                                      │
  │   auth.type == "oauth2"?             │
  │   → OAuth 2.0フローでTokenを取得      │
  │                                      │
  │   auth.type == "none"?               │
  │   → 直接呼び出し、資格情報不要         │
  │                                      │
  │── POST /invoke (資格情報付き) ───────→│
  │                                      │

認証失敗レスポンス

有効な資格情報が提供されない場合、401エラーが返されます：

{
  "error": {
    "code": "AUTH_REQUIRED",
    "message": "Authentication is required to invoke this skill",
    "details": {
      "required_auth_type": "oauth2",
      "authorization_url": "https://example.com/oauth/authorize"
    }
  }
}

6.6 タイムアウトとリトライ

タイムアウト処理

スキル実行が設定されたtimeout_msを超過した場合：

{
  "execution_id": "exec-789-xyz",
  "status": "timeout",
  "skill_id": "com.example.translate-v1",
  "error": {
    "code": "EXECUTION_TIMEOUT",
    "message": "Skill execution exceeded the configured timeout of 30000ms",
    "retry": {
      "suggested_delay_ms": 5000,
      "max_attempts": 3
    }
  },
  "timestamps": {
    "created_at": "2025-03-20T14:30:00Z",
    "updated_at": "2025-03-20T14:30:30Z"
  }
}

リトライ戦略

タイムアウトレスポンスには推奨リトライ遅延と最大リトライ回数が含まれる
消費者は指数バックオフリトライ戦略を実装すべき
エンドポイント到達不能時は、指数バックオフ（初期遅延 × 2^n）を推奨