プロトコル

実システムは REST だけではありません。Powerduck は x-protocol 拡張を使い、通常の OpenAPI パス項目に 7 つのプロトコルをモデル化します。ストリーミングや RPC 操作を REST と同じ仕様に含め、別ツールで追跡したり REST に無理に変換したりしません。

各非 HTTP 操作は、HTTP メソッドと responses."200".description を持つ通常のパス項目のままです。

graphql、grpc、mcp, a2a は post を使う。
sse、websocket は通常 get を使う。
http がデフォルトで、x-protocol は省略します。

SSE

HTTP ベースの Server-Sent Events は x-protocol: "sse" を使います。ストリームメディアタイプは text/event-stream で、単一イベントのペイロードは schema ではなく itemSchema で記述します。

paths:
  /events:
    get:
      x-protocol: sse
      responses:
        "200":
          description: Event stream
          content:
            text/event-stream:
              itemSchema:
                type: object
                properties:
                  type:
                    type: string
                  data:
                    type: string

WebSocket

WebSocket は x-protocol: "websocket" を使い、x-websocket ブロックを添えます。URL は ws:// または wss:// で始まる必要があります。

paths:
  /ws:
    get:
      x-protocol: websocket
      x-websocket:
        url: wss://example.com/ws
        subprotocols: []
        headers: {}
      responses:
        "200":
          description: Operation response

subprotocols と headers は任意です。

GraphQL

GraphQL は /graphql/query/fieldName 形のパスで post を使い、x-graphql を添えます。エンドポイントは絶対 HTTP(S) URL で、query は必須です。

paths:
  /graphql/query/product:
    post:
      x-protocol: graphql
      x-graphql:
        endpoint: https://example.com/graphql
        query: query Product($id: ID!) { product(id: ID!) { id name } }
        operationName: Product
        variablesSchema:
          type: object
        variables: {}
      responses:
        "200":
          description: Operation response

operationName、variablesSchema、variables は任意です。

gRPC

gRPC は /grpc/pkg.Service/Method 形のパスで post を使い、x-grpc を添えます。サーバーがリフレクション対応なら reflection: true、そうでなければ protoPaths（と任意の includeDirs）を提供します。

paths:
  /grpc/products.ProductService/GetProduct:
    post:
      x-protocol: grpc
      x-grpc:
        address: host:port
        service: products.ProductService
        method: GetProduct
        kind: unary
        reflection: true
      responses:
        "200":
          description: Operation response

kind は unary、server_streaming、client_streaming、bidi_streaming のいずれかです。

MCP

MCP はデフォルトで Streamable HTTP を使い、/mcp/tools/tool-name 形のパスで post、x-mcp ブロックを添えます。

paths:
  /mcp/tools/create-product:
    post:
      x-protocol: mcp
      x-mcp:
        endpoint: http://127.0.0.1:3000/mcp
        transport: streamable-http
        method: tools/call
        name: create-product
        argumentsSchema:
          type: object
        arguments: {}
      responses:
        "200":
          description: Operation response

method は MCP 操作を選びます。tools/call、tools/list、resources/read、resources/list、resources/templates/list、prompts/get、prompts/list。name、uri、argumentsSchema、arguments はメソッドに応じて使います。

構造ルール

アシスタントが生成するコントラクトでは、requestBody または responses のメディアタイプに schema または $ref を指定します。text/event-stream は OAS 3.2 の itemSchema で個々のイベントを記述します。これは Powerduck の記述規約であり、すべての OpenAPI 文書に共通する必須条件ではありません。
各パラメータには schema（または content）が必要です。
操作を編集するとき、選択プロトコルとその設定は保持されます。RPC やストリーミング操作が REST に黙って変換されることはありません。
上記の正確な拡張形を使い、externalUrl のようなキーを捏造したり ws をプロトコル名に使ったりしないでください。

なぜ重要か

1 つの文書で全 6 プロトコルをモデル化すると、トランスポートに関わらず設計、デバッグ、モック、ドキュメント、MCP が同じ情報源で駆動されます。アシスタントにストリーミングや RPC インターフェースの追加を依頼しても、プロトコル設定が完全に保たれ、REST 専用形に平坦化されません。

関連: アシスタントで設計する、データモデル。

A2A

A2A 1.0 は JSON-RPC、REST、デスクトップ gRPC のデバッグと文書化、およびステートレスなメッセージアダプターサーバーの生成に対応します。永続タスクとプッシュ配信は独自実装が必要です。

x-protocol: a2a と x-a2a でエージェントのメッセージとタスクを設計、デバッグ、文書化できます。1.0 は JSON-RPC、REST、デスクトップ gRPC、0.3 は JSON-RPC に対応します。A2A エージェントで拡張フィールド、署名検証、サーバー生成、実行可能なデモを確認してください。

SSE​

WebSocket​

GraphQL​

gRPC​

MCP​

構造ルール​

なぜ重要か​

A2A​

SSE

WebSocket

GraphQL

gRPC

MCP

構造ルール

なぜ重要か

A2A