Skip to main content
GET
Requires version 1.1.13 or later of the Archetype platform.
Starting with version 2.0.1, this endpoint is removed from the platform. Run packages through deployments and sessions instead: deploy a package with Create Deployment, then open a session on it with Create Session. To move existing code, see Migrating from Bundles and Instances.

Overview

This endpoint upgrades the connection to a websocket against an agent that was run with mode: serving. Each text frame the client sends is relayed to the agent and answered with one frame carrying the agent’s answer; what counts as an answer, and when, is the agent’s decision. The agent is checked before the upgrade, so 404, 409, and 503 arrive as ordinary HTTP responses rather than as an accepted socket that closes. Send the bearer token as an Authorization header on the upgrade request.

Request

string
required
Serving agent agt_ id to open a session against.

Frame protocol

The protocol is JSON text. Every frame the server sends is JSON carrying a status, so a client reads that one field to tell any frame from any other:
  • connected — sent once, when the session opens.
  • completed — the answer to one text frame the client sent. It has the same shape as the Query Agent response.
  • failed — a frame the server will not act on (malformed JSON, or a binary frame) is answered with a failed frame, and the session continues; one bad frame is not a broken session. The same frame is sent, and the session then closes, when the agent stops serving or when its state cannot be read for long enough to stop vouching for it.
Frames are capped at the same size as an HTTP body; a larger one closes the socket with a reason rather than a bare disconnect.

Session-open frame

string
required
Always connected.
string
required
The agt_ id of the agent the session is bound to.

Answer frame

string
required
completed.
object
required
The agent’s answer, passed through as it came back. Its shape belongs to the blueprint’s connectors.
number
required
Total server-side time, in milliseconds.

Failure frame

string
required
Always failed.
string
required
Why the frame could not be acted on, or why the session is closing.

Important Notes

  • Start the agent with mode: serving on Run Bundle. A batch run never accepts a session.
  • Use Query Agent for a single request and answer; use this endpoint for one open session over many payloads.
  • A 503 carries a Retry-After header giving the number of seconds to wait before opening a session again.
  • Over a session, status is how you tell an answer from a failure, since there is no HTTP status line per frame.