Skip to content

Declare the error contract, streaming endpoints, and chat pagination #51

Description

@ExtraToast

What to build

agents-api's contract gains its missing error codes, its four undeclared real-time endpoints, and a pagination convention for its unbounded collections.

agents-api is the best of the three today — 8 error responses across 52 operations, and it already emits ProblemDetail/FieldError — but four endpoints that agents-ui depends on in production appear nowhere in the spec: two EventSource streams, one fetch-reader stream, and a WebSocket. Nothing gates changes to their payload shapes.

Acceptance criteria

  • Universal error responses declared, plus the domain-specific codes this service actually returns
  • The three HTTP streaming endpoints appear in the spec; the WebSocket is documented where OpenAPI cannot express it
  • Chat sessions and messages paginate using the estate cursor convention
  • oasdiff breaking changes are intentional and called out, not incidental

Blocked by

  • Declare ProblemDetail responses on every operation (kotlin-spring-commons tracker)

Activity

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    area: agentsAgent runtime, agent APIs, tools, prompts, or UI.component: apiHTTP API, OpenAPI contract, or API client concern.priority: P2Medium; normal planned work.type: featureNew user-facing or operator-facing capability.

    Type

    No type

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions