Zum Hauptinhalt springen

Protokolle

Echte Systeme bestehen nicht nur aus REST. Powerduck modelliert sieben Protokolle in gewöhnlichen OpenAPI-Pfadeinträgen über die x-protocol-Erweiterung. Streaming- und RPC-Operationen leben in derselben Spec wie REST, ohne separates Werkzeug oder erzwungene Umwandlung in REST.

Jede Nicht-HTTP-Operation bleibt ein gewöhnlicher Pfadeintrag mit HTTP-Methode und responses."200".description.

  • graphql, grpc, mcp, a2a nutzen post.
  • sse, websocket nutzen meist get.
  • http ist die Standardeinstellung, und x-protocol wird weggelassen.

SSE​

Server-Sent Events über HTTP nutzen x-protocol: "sse". Der Streaming-Medientyp ist text/event-stream, und die Nutzlast eines Einzel-Ereignisses beschreiben Sie mit itemSchema, nicht schema.

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 nutzt x-protocol: "websocket" mit einem x-websocket-Block. Die URL muss mit ws:// oder wss:// beginnen.

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

subprotocols und headers sind optional.

GraphQL​

GraphQL nutzt post auf einem Pfad der Form /graphql/query/fieldName mit x-graphql. Der Endpunkt ist eine absolute HTTP(S)-URL, und die query ist verpflichtend.

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 und variables sind optional.

gRPC​

gRPC nutzt post auf einem Pfad der Form /grpc/pkg.Service/Method mit x-grpc. Wenn der Server Reflexion unterstützt, setzen Sie reflection: true; sonst liefern Sie protoPaths (und optional 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 ist unary, server_streaming, client_streaming oder bidi_streaming.

MCP​

MCP nutzt standardmäßig Streamable HTTP, post auf einem Pfad der Form /mcp/tools/tool-name, mit einem x-mcp-Block.

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 wählt die MCP-Operation: tools/call, tools/list, resources/read, resources/list, resources/templates/list, prompts/get, prompts/list. name, uri, argumentsSchema und arguments kommen je nach Methode zum Einsatz.

Strukturregeln​

  • Für vom Assistenten erzeugte Verträge geben Sie bei Medientypen unter requestBody oder responses ein schema oder $ref an. text/event-stream beschreibt einzelne Ereignisse mit itemSchema aus OAS 3.2. Dies ist eine Schreibkonvention von Powerduck, keine allgemeine Pflicht für jedes OpenAPI-Dokument.
  • Jeder Parameter braucht schema (oder content).
  • Beim Bearbeiten einer Operation bleiben gewähltes Protokoll und Konfiguration erhalten: RPC- oder Streaming-Operationen werden nicht still zu REST.
  • Nutzen Sie die genauen Erweiterungsformen oben; erfinden Sie keine Schlüssel wie externalUrl und nutzen ws nicht als Protokollnamen.

Warum es zählt​

Wenn sieben Protokolle in einem Dokument modelliert sind, werden Entwurf, Debugging, Mocking, Doku und MCP unabhängig vom Transport von derselben Quelle gesteuert. Bitten Sie den Assistenten, eine Streaming- oder RPC-Schnittstelle hinzuzufügen, und ihre Protokollkonfiguration bleibt statt zu REST abgeflacht erhalten.

Siehe auch: Mit dem Assistenten entwerfen、Datenmodell.

A2A​

A2A 1.0 unterstützt Debugging und Dokumentation über JSON-RPC, REST und Desktop-gRPC sowie die Erzeugung eines zustandslosen Nachrichtenadapter-Servers. Persistente Aufgaben und Push-Zustellung erfordern eine eigene Implementierung.

Mit x-protocol: a2a und x-a2a entwerfen, debuggen und dokumentieren Sie Agentennachrichten und Aufgaben. A2A 1.0 unterstützt JSON-RPC, REST und Desktop-gRPC, 0.3 nur JSON-RPC. A2A-Agenten beschreibt Erweiterungen, Signaturprüfung, Servergenerierung und die ausführbare Demo.