APIs and execution protocols
Last updated:
Prerequisites: access to a development Server and a valid authenticated identity, such as an API Key or a browser session. Use current OpenAPI and owning-module Contracts for exact fields; this site does not duplicate the complete schema.
Protocol boundaries
| Interface | Purpose and contract |
|---|---|
| Management JSON APIs | Bens.Results ApiResult envelopes, unwrapped by typed client helpers |
/api/hubs/exec | SignalR execution commands, state, and events; mapped by Data Plane and Standalone only and accepts only the WebSocket transport. The official client connects with skipNegotiation: true |
/api/agents/permission-capabilities | Query supported permissions for a target |
/api/auth/oidc/providers | Enabled sign-in providers, used to render the sign-in buttons |
/api/auth/oidc/login | Redirects to the provider; client is web or desktop |
/api/auth/desktop/exchange | Desktop exchanges a one-time code plus its verifier for an API Key |
| A2A | Protocol-specific responses, mapped by Data Plane and Standalone only |
/openapi/* | Contract entry point; served, together with the Scalar API reference, only in the Development environment by Control Plane or Standalone |
Sign-in routes are served by Control Plane and Standalone. An API Key obtained by Desktop behaves like a manually created one and accesses resources as its creator.
Integration sequence
- Use an API Key in the
Authorization: Bearerheader for automation. Browser requests using Cookies to make changes, such as POST, PUT, and DELETE, also need the existing CSRF protection flow to prevent another site from acting through the signed-in session. - Read resources accessible to the current user through management APIs and retain their stable identifiers.
- Query target permission capabilities, then use the existing execution protocol to send commands and subscribe to events.
- Restore conversation/execution state after reconnecting; disconnection is not completion.
New endpoints default to query/body identifiers under repository rules. Consult current OpenAPI and Contracts for each endpoint’s routes and parameters.
Handle results in the client
Management JSON APIs use Bens.Results response envelopes. Reuse the typed helpers in @agw/api to extract business data, and handle request failures and application errors separately.
An execution connection returns a stream of events. Retain conversation and execution IDs, show tool activity and input requests, and recover actual progress after reconnecting. Partial text is not completion, and disconnection is not cancellation. See the execution protocol for message shapes and order.
Agent structured-response fields
responseSchema holds the JSON Schema text configured on an agent. It appears in the full agent response: GET /api/agents/{id}, GET /api/agents/paged, POST /api/agents, PUT /api/agents/{id}, and PUT /api/agents/enabled. The selector endpoint GET /api/agents omits it.
Both response shapes include resultFormat, either markdown or json, derived from whether a schema is configured. Clients use it to decide how to render the final result without parsing the schema themselves.
On update, an absent field keeps the current value, null or a whitespace-only string clears it, and any other string replaces it. The server requires valid JSON whose root is an object and otherwise returns an invalid-parameter error. Pi agents reject any schema with an invalid-parameter error. The schema is stored and forwarded as text only.
Contract changes
Keep DTOs in the owning module’s Contracts. Expected application failures use AgwException and stable seven-digit ErrorCodes, mapped at boundaries. WebSocket, OAuth redirects, A2A, and static files retain their protocols.
After backend contract changes, export the Development OpenAPI document to src/clients/packages/api/openapi.json, run pnpm gen:api from src/clients, and validate callers. gen:api converts only that local file; it does not fetch the latest document from Server. Do not hand-edit generated openapi.d.ts or log actual API Keys.