Skip to main content
POST
Requires version 1.1.12 or later of the Archetype platform.
Starting with version 2.0.1, this endpoint is removed from the platform. Use Query Session on a serving session instead. To move existing code, see Migrating from Bundles and Instances.

Overview

This endpoint sends a payload to a running serving agent and returns its answer. The body is whatever the blueprint’s source connector accepts, and the answer is whatever its sink produces — the platform passes both through unchanged and wraps the answer in the fields every serving agent reports the same way. Some failures are final and some are worth retrying:
  • 400 — the agent itself rejected the payload. Its reason is passed through, and resending the same body will not succeed.
  • 409 — the agent was not run in serving mode, is no longer running, or has stopped on its worker. The message says why the run ended where that is known, and resending will not succeed.
  • 429 — the agent is already answering as many queries at once as it will. The same request succeeds once one of them finishes, so retry it with backoff.
  • 503 — the agent cannot be reached or did not answer in time (unavailable), or this node is already answering as many queries as it will (node_at_capacity). Both are worth retrying. An agent that does not answer before this service stops waiting is answered 503.
  • 504 — the agent reports that its time budget ran out before it had an answer (query_timeout). The budget counts from when the agent accepted the query, so it includes time spent waiting behind other queries to it; send less data per query, or fewer queries at once.
  • 501 — serving is not enabled in this environment.
429 responses, and 503 responses with node_at_capacity, carry a Retry-After header giving the number of seconds to wait before sending the query again.

Request

string
required
Serving agent agt_ id to query.
object
required
Whatever the agent’s source connector accepts. The shape belongs to the blueprint, not to this endpoint — see the blueprint’s source connector for what it takes.

Response

string
required
Whether the query produced an answer: completed or failed. Over HTTP the status line already says so, and this is only ever completed; the failed value exists for the /connect frame protocol, where there is no status line.
object
required
The agent’s answer, passed through as it came back. Opaque to the platform — its shape belongs to the blueprint’s connectors.
number
required
Total server-side time, in milliseconds.

Important Notes

  • Start the agent with mode: serving on Run Bundle. A batch run never answers this endpoint.
  • Both the request body and response are opaque to the platform: their shapes are the blueprint’s source and sink connectors, not this endpoint’s.
  • A 404 covers both an unknown id and one belonging to another organization — the two are indistinguishable by design.
  • Retry 429 and 503 with backoff, honoring Retry-After when it is sent. Don’t resend a 400 or 409 unchanged; it will not succeed.
  • Use Connect to Agent when you want one open session for many payloads instead of a request per payload.
  • A 409 means the agent is not a running serving agent. When the agent has stopped, the message says why: agent '<agent_id>' is no longer running: <reason>. A failed run gives its error as the reason. A serving agent that the platform released after going unused for the deployment’s idle window ends completed, and its reason reads released after <idle window> without a query; run the agent again. A released agent does not come back: start a new one with mode: serving on POST /agents/bundles/{bundle_id}/run. v2.0.0+
  • A 504 with code query_timeout means the agent ran out of its time budget before it had an answer. The budget starts when the agent accepts the query, so it includes time spent waiting behind other queries to the same agent. Resending the same query unchanged times out again, and the response carries no Retry-After header. Send less data per query, or fewer queries at once. v2.0.0+
  • A 500 with code agent_failed means the agent processed the query and failed it. The message carries the agent’s reason unchanged, and the response has no Retry-After header. Don’t retry it: the same query fails the same way. Change the query instead. v2.0.1+
  • A 503 means the agent could not be reached or did not answer before the platform stopped waiting. It is worth retrying with backoff.
  • Use GET /agents/instances/{agent_id}/connect when you want one open session for many payloads instead of a request per payload.