@bluefly/openstandardagents 0.2.9 → 0.3.0

package/openapi/agent-communication.yaml

@@ -0,0 +1,1113 @@
+openapi: 3.1.0
+jsonSchemaDialect: https://spec.openapis.org/oas/3.1/dialect/base
+info:
+  title: OSSA Agent Communication API
+  version: 0.3.0
+  description: |
+    # OSSA Agent-to-Agent Communication Standards
+
+    Agent-to-Agent (A2A) messaging protocol for OSSA v0.3.0+, enabling coordinated
+    multi-agent systems with direct messaging, pub/sub channels, and async patterns.
+
+    ## Key Capabilities
+    - **Direct Messaging**: Point-to-point message delivery between agents
+    - **Pub/Sub Channels**: Topic-based message broadcasting
+    - **Async Patterns**: Webhooks and Server-Sent Events (SSE) for streaming
+    - **Message Types**: Structured task coordination (assign, complete, query)
+    - **Delivery Guarantees**: At-least-once delivery with message acknowledgment
+
+    ## Message Flow Patterns
+    1. **Task Assignment**: Orchestrator → Worker (TaskAssigned)
+    2. **Task Completion**: Worker → Orchestrator (TaskCompleted)
+    3. **Query/Response**: Agent A ↔ Agent B (QueryRequest/QueryResponse)
+    4. **Broadcast**: Publisher → Channel → Subscribers
+
+  contact:
+    name: Bluefly.io LLM Platform Team
+    url: https://github.com/blueflyio/openstandardagents
+  license:
+    name: MIT
+    url: https://opensource.org/licenses/MIT
+
+servers:
+  - url: https://a2a.llm.bluefly.io/v1
+    description: Production A2A server
+  - url: https://a2a-dev.llm.bluefly.io/v1
+    description: Development A2A server
+  - url: http://localhost:3100
+    description: Local development
+
+security:
+  - ApiKeyAuth: []
+  - BearerAuth: []
+  - AgentMTLS: []
+
+paths:
+  # Direct Messaging
+  /messages:
+    post:
+      summary: Send message to agent
+      description: |
+        Send a message to a target agent. Supports both synchronous (request/reply)
+        and asynchronous (fire-and-forget) patterns.
+
+        For async delivery, use webhookUrl in the request. The response will be
+        delivered to the webhook endpoint when available.
+      tags: [Messaging]
+      operationId: sendMessage
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: '#/components/schemas/SendMessageRequest'
+            examples:
+              taskAssignment:
+                summary: Assign task to worker
+                value:
+                  to: agent://worker-001
+                  from: agent://orchestrator-main
+                  type: TaskAssigned
+                  payload:
+                    taskId: task-123
+                    action: analyze_document
+                    input:
+                      documentUrl: https://example.com/doc.pdf
+                    priority: high
+                  webhookUrl: https://orchestrator.example.com/webhooks/task-123
+              queryRequest:
+                summary: Query another agent
+                value:
+                  to: agent://specialist-nlp
+                  from: agent://worker-002
+                  type: QueryRequest
+                  payload:
+                    query: "Extract entities from text"
+                    context:
+                      text: "Apple Inc. is headquartered in Cupertino, California."
+                  timeout: 30000
+      responses:
+        '202':
+          description: Message accepted for delivery
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/MessageResponse'
+        '400':
+          $ref: '#/components/responses/ValidationError'
+        '401':
+          $ref: '#/components/responses/Unauthorized'
+        '404':
+          description: Target agent not found
+          content:
+            application/problem+json:
+              schema:
+                $ref: '#/components/schemas/Problem'
+        '500':
+          $ref: '#/components/responses/InternalServerError'
+
+  /messages/{messageId}:
+    get:
+      summary: Get message status
+      description: |
+        Retrieve the delivery status and metadata for a previously sent message.
+        Includes delivery timestamps, acknowledgment status, and any errors.
+      tags: [Messaging]
+      operationId: getMessageStatus
+      parameters:
+        - name: messageId
+          in: path
+          required: true
+          description: Unique message identifier
+          schema:
+            type: string
+            format: uuid
+      responses:
+        '200':
+          description: Message status
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/Message'
+        '404':
+          $ref: '#/components/responses/NotFound'
+        '500':
+          $ref: '#/components/responses/InternalServerError'
+
+  /messages/{messageId}/acknowledge:
+    post:
+      summary: Acknowledge message receipt
+      description: |
+        Acknowledge successful processing of a received message. Required for
+        at-least-once delivery guarantee. Unacknowledged messages may be redelivered.
+      tags: [Messaging]
+      operationId: acknowledgeMessage
+      parameters:
+        - name: messageId
+          in: path
+          required: true
+          schema:
+            type: string
+            format: uuid
+      requestBody:
+        content:
+          application/json:
+            schema:
+              type: object
+              properties:
+                result:
+                  type: string
+                  enum: [success, failure]
+                  default: success
+                error:
+                  type: string
+                  description: Error message if result is failure
+      responses:
+        '204':
+          description: Message acknowledged
+        '404':
+          $ref: '#/components/responses/NotFound'
+        '500':
+          $ref: '#/components/responses/InternalServerError'
+
+  # Pub/Sub Channels
+  /channels:
+    get:
+      summary: List available channels
+      description: List all communication channels the authenticated agent has access to
+      tags: [Channels]
+      operationId: listChannels
+      parameters:
+        - name: filter
+          in: query
+          description: Filter channels by type or topic
+          schema:
+            type: string
+        - $ref: '#/components/parameters/Limit'
+        - $ref: '#/components/parameters/Offset'
+      responses:
+        '200':
+          description: List of channels
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/ChannelsList'
+        '500':
+          $ref: '#/components/responses/InternalServerError'
+
+    post:
+      summary: Create communication channel
+      description: |
+        Create a new pub/sub channel for message broadcasting. Channels enable
+        many-to-many communication between agents.
+      tags: [Channels]
+      operationId: createChannel
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: '#/components/schemas/CreateChannelRequest'
+            examples:
+              taskUpdates:
+                summary: Task updates channel
+                value:
+                  name: task-updates
+                  topic: tasks.status.updates
+                  description: Real-time task status updates
+                  retentionPolicy:
+                    retentionDays: 7
+                    maxMessages: 10000
+              agentEvents:
+                summary: Agent lifecycle events
+                value:
+                  name: agent-events
+                  topic: agents.lifecycle.*
+                  description: Agent started, stopped, error events
+                  retentionPolicy:
+                    retentionDays: 30
+      responses:
+        '201':
+          description: Channel created
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/Channel'
+        '400':
+          $ref: '#/components/responses/ValidationError'
+        '409':
+          description: Channel already exists
+          content:
+            application/problem+json:
+              schema:
+                $ref: '#/components/schemas/Problem'
+        '500':
+          $ref: '#/components/responses/InternalServerError'
+
+  /channels/{channelId}:
+    get:
+      summary: Get channel details
+      description: Retrieve channel metadata, subscriber count, and configuration
+      tags: [Channels]
+      operationId: getChannel
+      parameters:
+        - $ref: '#/components/parameters/ChannelId'
+      responses:
+        '200':
+          description: Channel details
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/Channel'
+        '404':
+          $ref: '#/components/responses/NotFound'
+
+    delete:
+      summary: Delete channel
+      description: |
+        Delete a communication channel. All subscriptions will be removed.
+        Messages in the channel will be deleted according to retention policy.
+      tags: [Channels]
+      operationId: deleteChannel
+      parameters:
+        - $ref: '#/components/parameters/ChannelId'
+      responses:
+        '204':
+          description: Channel deleted
+        '404':
+          $ref: '#/components/responses/NotFound'
+        '500':
+          $ref: '#/components/responses/InternalServerError'
+
+  /channels/{channelId}/subscribe:
+    post:
+      summary: Subscribe to channel
+      description: |
+        Subscribe to a channel to receive published messages. Supports both
+        push (webhook) and pull (polling) delivery modes.
+      tags: [Channels]
+      operationId: subscribeToChannel
+      parameters:
+        - $ref: '#/components/parameters/ChannelId'
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: '#/components/schemas/SubscribeRequest'
+            examples:
+              webhookSubscription:
+                summary: Webhook-based subscription
+                value:
+                  agentId: agent://worker-003
+                  deliveryMode: push
+                  webhookUrl: https://worker-003.example.com/channels/task-updates
+                  filter:
+                    messageTypes: [TaskAssigned, TaskCompleted]
+              pollingSubscription:
+                summary: Polling-based subscription
+                value:
+                  agentId: agent://monitor-001
+                  deliveryMode: pull
+                  filter:
+                    messageTypes: [TaskCompleted]
+      responses:
+        '201':
+          description: Subscription created
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/Subscription'
+        '400':
+          $ref: '#/components/responses/ValidationError'
+        '404':
+          description: Channel not found
+          content:
+            application/problem+json:
+              schema:
+                $ref: '#/components/schemas/Problem'
+        '500':
+          $ref: '#/components/responses/InternalServerError'
+
+  /channels/{channelId}/unsubscribe:
+    post:
+      summary: Unsubscribe from channel
+      description: Remove subscription from a channel
+      tags: [Channels]
+      operationId: unsubscribeFromChannel
+      parameters:
+        - $ref: '#/components/parameters/ChannelId'
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              type: object
+              required: [subscriptionId]
+              properties:
+                subscriptionId:
+                  type: string
+                  format: uuid
+      responses:
+        '204':
+          description: Unsubscribed successfully
+        '404':
+          $ref: '#/components/responses/NotFound'
+
+  /channels/{channelId}/publish:
+    post:
+      summary: Publish message to channel
+      description: |
+        Broadcast a message to all channel subscribers. Message will be delivered
+        according to each subscriber's delivery mode (push/pull).
+      tags: [Channels]
+      operationId: publishToChannel
+      parameters:
+        - $ref: '#/components/parameters/ChannelId'
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: '#/components/schemas/PublishMessageRequest'
+            examples:
+              taskCompleted:
+                summary: Broadcast task completion
+                value:
+                  type: TaskCompleted
+                  payload:
+                    taskId: task-123
+                    status: completed
+                    result:
+                      entities: ["Apple Inc.", "Cupertino", "California"]
+                    completedAt: "2025-12-18T14:30:00Z"
+              agentStarted:
+                summary: Agent lifecycle event
+                value:
+                  type: AgentStarted
+                  payload:
+                    agentId: agent://worker-005
+                    version: 1.2.0
+                    capabilities: [text_analysis, entity_extraction]
+                    startedAt: "2025-12-18T14:25:00Z"
+      responses:
+        '202':
+          description: Message published
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/PublishResponse'
+        '400':
+          $ref: '#/components/responses/ValidationError'
+        '404':
+          description: Channel not found
+          content:
+            application/problem+json:
+              schema:
+                $ref: '#/components/schemas/Problem'
+        '500':
+          $ref: '#/components/responses/InternalServerError'
+
+  /channels/{channelId}/messages:
+    get:
+      summary: Pull messages from channel
+      description: |
+        Poll for messages from a channel (pull-based delivery). Only available
+        for subscriptions with deliveryMode: pull.
+      tags: [Channels]
+      operationId: pullChannelMessages
+      parameters:
+        - $ref: '#/components/parameters/ChannelId'
+        - name: subscriptionId
+          in: query
+          required: true
+          schema:
+            type: string
+            format: uuid
+        - name: maxMessages
+          in: query
+          description: Maximum number of messages to return
+          schema:
+            type: integer
+            minimum: 1
+            maximum: 100
+            default: 10
+        - name: ackMode
+          in: query
+          description: Acknowledgment mode
+          schema:
+            type: string
+            enum: [auto, manual]
+            default: manual
+      responses:
+        '200':
+          description: Messages retrieved
+          content:
+            application/json:
+              schema:
+                type: object
+                properties:
+                  messages:
+                    type: array
+                    items:
+                      $ref: '#/components/schemas/Message'
+                  hasMore:
+                    type: boolean
+        '404':
+          $ref: '#/components/responses/NotFound'
+
+  # Streaming (Server-Sent Events)
+  /stream:
+    get:
+      summary: Stream messages via SSE
+      description: |
+        Open a Server-Sent Events stream to receive real-time messages.
+        Client maintains persistent connection for streaming updates.
+      tags: [Streaming]
+      operationId: streamMessages
+      parameters:
+        - name: agentId
+          in: query
+          required: true
+          description: Agent identifier to stream messages for
+          schema:
+            type: string
+        - name: filter
+          in: query
+          description: Filter messages by type (comma-separated)
+          schema:
+            type: string
+            example: "TaskAssigned,TaskCompleted"
+      responses:
+        '200':
+          description: SSE stream
+          content:
+            text/event-stream:
+              schema:
+                type: string
+                description: |
+                  Server-Sent Events stream. Each event contains:
+                  - event: message type (e.g., "TaskAssigned")
+                  - data: JSON-encoded message payload
+                  - id: message ID for resumption
+              examples:
+                taskAssignedEvent:
+                  summary: Task assignment event
+                  value: |
+                    event: TaskAssigned
+                    id: msg-123
+                    data: {"taskId":"task-456","action":"analyze_document","input":{"documentUrl":"https://example.com/doc.pdf"}}
+
+                    event: TaskCompleted
+                    id: msg-124
+                    data: {"taskId":"task-456","status":"completed","result":{"summary":"Document analyzed"}}
+        '401':
+          $ref: '#/components/responses/Unauthorized'
+
+  # Webhooks (for async callbacks)
+  /webhooks:
+    post:
+      summary: Register webhook endpoint
+      description: |
+        Register a webhook endpoint to receive async message delivery.
+        The A2A platform will POST messages to the registered URL.
+      tags: [Webhooks]
+      operationId: registerWebhook
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: '#/components/schemas/WebhookRegistration'
+      responses:
+        '201':
+          description: Webhook registered
+          content:
+            application/json:
+              schema:
+                type: object
+                properties:
+                  webhookId:
+                    type: string
+                    format: uuid
+                  url:
+                    type: string
+                    format: uri
+                  secret:
+                    type: string
+                    description: HMAC secret for verifying webhook authenticity
+        '400':
+          $ref: '#/components/responses/ValidationError'
+
+  /webhooks/{webhookId}:
+    delete:
+      summary: Unregister webhook
+      description: Remove a webhook endpoint registration
+      tags: [Webhooks]
+      operationId: unregisterWebhook
+      parameters:
+        - name: webhookId
+          in: path
+          required: true
+          schema:
+            type: string
+            format: uuid
+      responses:
+        '204':
+          description: Webhook unregistered
+        '404':
+          $ref: '#/components/responses/NotFound'
+
+  # Health
+  /health:
+    get:
+      summary: Health check
+      tags: [Health]
+      operationId: healthCheck
+      security: []
+      responses:
+        '200':
+          $ref: '#/components/responses/HealthCheck'
+        '503':
+          $ref: '#/components/responses/ServiceUnavailable'
+
+components:
+  securitySchemes:
+    ApiKeyAuth:
+      type: apiKey
+      in: header
+      name: X-API-Key
+      description: API key authentication for agent services
+    BearerAuth:
+      type: http
+      scheme: bearer
+      bearerFormat: JWT
+      description: JWT bearer token authentication
+    AgentMTLS:
+      type: mutualTLS
+      description: Mutual TLS authentication for agent-to-agent trust
+
+  parameters:
+    ChannelId:
+      name: channelId
+      in: path
+      required: true
+      description: Channel identifier
+      schema:
+        type: string
+        format: uuid
+    Limit:
+      name: limit
+      in: query
+      description: Number of items to return
+      schema:
+        type: integer
+        minimum: 1
+        maximum: 100
+        default: 20
+    Offset:
+      name: offset
+      in: query
+      description: Number of items to skip
+      schema:
+        type: integer
+        minimum: 0
+        default: 0
+
+  schemas:
+    # Message Schemas
+    SendMessageRequest:
+      type: object
+      required:
+        - to
+        - from
+        - type
+        - payload
+      properties:
+        to:
+          type: string
+          format: uri
+          description: Target agent URI (e.g., agent://worker-001)
+          pattern: '^agent://[a-z0-9]([-a-z0-9]*[a-z0-9])?$'
+        from:
+          type: string
+          format: uri
+          description: Source agent URI
+          pattern: '^agent://[a-z0-9]([-a-z0-9]*[a-z0-9])?$'
+        type:
+          $ref: '#/components/schemas/MessageType'
+        payload:
+          $ref: '#/components/schemas/MessagePayload'
+        correlationId:
+          type: string
+          description: Correlation ID for request/reply pattern
+        timeout:
+          type: integer
+          description: Message timeout in milliseconds
+          minimum: 1000
+          maximum: 300000
+          default: 30000
+        priority:
+          type: string
+          enum: [low, normal, high, critical]
+          default: normal
+        webhookUrl:
+          type: string
+          format: uri
+          description: URL for async response delivery
+
+    MessageType:
+      type: string
+      enum:
+        - TaskAssigned
+        - TaskCompleted
+        - TaskFailed
+        - QueryRequest
+        - QueryResponse
+        - AgentStarted
+        - AgentStopped
+        - AgentError
+        - Custom
+      description: |
+        Standard message types for A2A communication:
+        - TaskAssigned: Assign a task to an agent
+        - TaskCompleted: Notify task completion
+        - TaskFailed: Notify task failure
+        - QueryRequest: Request information from an agent
+        - QueryResponse: Response to a query request
+        - AgentStarted: Agent lifecycle event (started)
+        - AgentStopped: Agent lifecycle event (stopped)
+        - AgentError: Agent error notification
+        - Custom: Custom application-specific message type
+
+    MessagePayload:
+      type: object
+      description: |
+        Message payload structure varies by message type. See schemas for each type.
+      additionalProperties: true
+
+    Message:
+      type: object
+      required:
+        - id
+        - to
+        - from
+        - type
+        - payload
+        - status
+        - createdAt
+      properties:
+        id:
+          type: string
+          format: uuid
+          description: Unique message identifier
+        to:
+          type: string
+          format: uri
+          description: Target agent URI
+        from:
+          type: string
+          format: uri
+          description: Source agent URI
+        type:
+          $ref: '#/components/schemas/MessageType'
+        payload:
+          $ref: '#/components/schemas/MessagePayload'
+        correlationId:
+          type: string
+          description: Correlation ID for request/reply pattern
+        status:
+          type: string
+          enum: [pending, delivered, acknowledged, failed]
+          description: Message delivery status
+        priority:
+          type: string
+          enum: [low, normal, high, critical]
+        createdAt:
+          type: string
+          format: date-time
+          description: Message creation timestamp
+        deliveredAt:
+          type: string
+          format: date-time
+          description: Message delivery timestamp
+        acknowledgedAt:
+          type: string
+          format: date-time
+          description: Message acknowledgment timestamp
+        error:
+          type: string
+          description: Error message if status is failed
+
+    MessageResponse:
+      type: object
+      required:
+        - messageId
+        - status
+      properties:
+        messageId:
+          type: string
+          format: uuid
+          description: Unique message identifier
+        status:
+          type: string
+          enum: [accepted, queued]
+          description: Initial message status
+        estimatedDelivery:
+          type: string
+          format: date-time
+          description: Estimated delivery time
+
+    # Channel Schemas
+    CreateChannelRequest:
+      type: object
+      required:
+        - name
+        - topic
+      properties:
+        name:
+          type: string
+          pattern: '^[a-z0-9]([-a-z0-9]*[a-z0-9])?$'
+          description: Channel name (lowercase, hyphen-separated)
+        topic:
+          type: string
+          description: Topic pattern (supports wildcards, e.g., tasks.*.updates)
+        description:
+          type: string
+        retentionPolicy:
+          $ref: '#/components/schemas/RetentionPolicy'
+        accessControl:
+          $ref: '#/components/schemas/AccessControl'
+
+    Channel:
+      type: object
+      required:
+        - id
+        - name
+        - topic
+        - createdAt
+      properties:
+        id:
+          type: string
+          format: uuid
+        name:
+          type: string
+        topic:
+          type: string
+        description:
+          type: string
+        subscriberCount:
+          type: integer
+          minimum: 0
+        messageCount:
+          type: integer
+          minimum: 0
+        retentionPolicy:
+          $ref: '#/components/schemas/RetentionPolicy'
+        accessControl:
+          $ref: '#/components/schemas/AccessControl'
+        createdAt:
+          type: string
+          format: date-time
+        updatedAt:
+          type: string
+          format: date-time
+
+    ChannelsList:
+      type: object
+      properties:
+        channels:
+          type: array
+          items:
+            $ref: '#/components/schemas/Channel'
+        total:
+          type: integer
+        limit:
+          type: integer
+        offset:
+          type: integer
+
+    RetentionPolicy:
+      type: object
+      properties:
+        retentionDays:
+          type: integer
+          minimum: 1
+          maximum: 365
+          default: 7
+          description: Number of days to retain messages
+        maxMessages:
+          type: integer
+          minimum: 100
+          default: 10000
+          description: Maximum number of messages to retain
+
+    AccessControl:
+      type: object
+      properties:
+        public:
+          type: boolean
+          default: false
+          description: Whether channel is publicly accessible
+        allowedAgents:
+          type: array
+          items:
+            type: string
+          description: List of agent URIs allowed to access channel
+
+    # Subscription Schemas
+    SubscribeRequest:
+      type: object
+      required:
+        - agentId
+        - deliveryMode
+      properties:
+        agentId:
+          type: string
+          format: uri
+          pattern: '^agent://[a-z0-9]([-a-z0-9]*[a-z0-9])?$'
+          description: Subscribing agent URI
+        deliveryMode:
+          type: string
+          enum: [push, pull]
+          description: Message delivery mode (push=webhook, pull=polling)
+        webhookUrl:
+          type: string
+          format: uri
+          description: Webhook URL (required if deliveryMode=push)
+        filter:
+          $ref: '#/components/schemas/SubscriptionFilter'
+
+    SubscriptionFilter:
+      type: object
+      properties:
+        messageTypes:
+          type: array
+          items:
+            $ref: '#/components/schemas/MessageType'
+          description: Filter by message types
+        agentFilter:
+          type: string
+          description: Filter by source agent pattern (supports wildcards)
+
+    Subscription:
+      type: object
+      required:
+        - id
+        - channelId
+        - agentId
+        - deliveryMode
+        - createdAt
+      properties:
+        id:
+          type: string
+          format: uuid
+        channelId:
+          type: string
+          format: uuid
+        agentId:
+          type: string
+          format: uri
+        deliveryMode:
+          type: string
+          enum: [push, pull]
+        webhookUrl:
+          type: string
+          format: uri
+        filter:
+          $ref: '#/components/schemas/SubscriptionFilter'
+        status:
+          type: string
+          enum: [active, paused, failed]
+        createdAt:
+          type: string
+          format: date-time
+        lastDeliveryAt:
+          type: string
+          format: date-time
+
+    # Publish Schemas
+    PublishMessageRequest:
+      type: object
+      required:
+        - type
+        - payload
+      properties:
+        type:
+          $ref: '#/components/schemas/MessageType'
+        payload:
+          $ref: '#/components/schemas/MessagePayload'
+        attributes:
+          type: object
+          additionalProperties:
+            type: string
+          description: Custom message attributes
+
+    PublishResponse:
+      type: object
+      properties:
+        messageId:
+          type: string
+          format: uuid
+        publishedAt:
+          type: string
+          format: date-time
+        subscriberCount:
+          type: integer
+          description: Number of subscribers message was delivered to
+
+    # Webhook Schemas
+    WebhookRegistration:
+      type: object
+      required:
+        - url
+        - agentId
+      properties:
+        url:
+          type: string
+          format: uri
+          description: Webhook endpoint URL
+        agentId:
+          type: string
+          format: uri
+          pattern: '^agent://[a-z0-9]([-a-z0-9]*[a-z0-9])?$'
+        description:
+          type: string
+        events:
+          type: array
+          items:
+            $ref: '#/components/schemas/MessageType'
+          description: Event types to deliver to this webhook
+
+    # Health Schema
+    HealthStatus:
+      type: object
+      properties:
+        status:
+          type: string
+          enum: [healthy, degraded, unhealthy]
+        version:
+          type: string
+        uptime:
+          type: integer
+        timestamp:
+          type: string
+          format: date-time
+        checks:
+          type: object
+          additionalProperties:
+            type: object
+            properties:
+              status:
+                type: string
+                enum: [pass, fail]
+              message:
+                type: string
+
+    # Error Schema (RFC7807)
+    Problem:
+      type: object
+      description: RFC7807 Problem Details
+      required:
+        - type
+        - title
+        - status
+        - traceId
+      properties:
+        type:
+          type: string
+          format: uri
+          default: about:blank
+        title:
+          type: string
+        status:
+          type: integer
+          format: int32
+        detail:
+          type: string
+        instance:
+          type: string
+          format: uri
+        traceId:
+          type: string
+        errors:
+          type: object
+          additionalProperties:
+            type: array
+            items:
+              type: string
+
+  responses:
+    HealthCheck:
+      description: Service health status
+      content:
+        application/json:
+          schema:
+            $ref: '#/components/schemas/HealthStatus'
+
+    ValidationError:
+      description: Validation error
+      content:
+        application/problem+json:
+          schema:
+            $ref: '#/components/schemas/Problem'
+
+    Unauthorized:
+      description: Unauthorized
+      content:
+        application/problem+json:
+          schema:
+            $ref: '#/components/schemas/Problem'
+
+    NotFound:
+      description: Resource not found
+      content:
+        application/problem+json:
+          schema:
+            $ref: '#/components/schemas/Problem'
+
+    ServiceUnavailable:
+      description: Service unavailable
+      content:
+        application/problem+json:
+          schema:
+            $ref: '#/components/schemas/Problem'
+
+    InternalServerError:
+      description: Internal server error
+      content:
+        application/problem+json:
+          schema:
+            $ref: '#/components/schemas/Problem'
+
+tags:
+  - name: Messaging
+    description: Direct agent-to-agent messaging
+  - name: Channels
+    description: Pub/sub channel management
+  - name: Streaming
+    description: Server-Sent Events streaming
+  - name: Webhooks
+    description: Webhook registration and management
+  - name: Health
+    description: Service health and status
+
+x-ossa-metadata:
+  version: 0.3.0
+  specification: OSSA Agent Communication Standards
+  compliance:
+    level: standard
+    frameworks:
+      - OSSA v0.3.0
+      - OpenAPI 3.1
+      - RFC7807
+  patterns:
+    - Point-to-point messaging
+    - Pub/sub channels
+    - Request/reply
+    - Server-Sent Events
+    - Webhooks
+  deliveryGuarantees:
+    - At-least-once delivery
+    - Message acknowledgment
+    - Retry with exponential backoff