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) 권장