BLUEPRINT

第六章：呼叫協定

6.1 概述

呼叫協定（Invocation Protocol）定義了技能消費者如何遠端呼叫已發現的技能。協定採用非同步呼叫模型，支援狀態查詢和結果取得。

6.2 呼叫流程

三步呼叫模型

步驟	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-TW"
  },
  "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-TW",
    "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 認證流程

呼叫前，消費者需檢查技能描述符中的 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）