Skip to main content
POST
Requires version 1.1.9 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 pauses a running agent and returns the updated agent with status paused. Only a running agent can be paused; anything else returns 409. A serving agent (one run with mode: serving) also returns 409: it holds a worker for the life of its run and refuses queries while paused, so there is nothing to hold it in place for; cancel it instead. If the active runtime cannot hold a run in place, the request returns 501; batch runs, for example, only support cancel. Resume it later with Resume Agent.

Request

string
required
Agent agt_ id.

Response

Returns the paused agent.
string
required
TypeID-encoded agent identifier (agt_ prefix).
string
required
Name of the agent: its bundle’s name, or for a run of a package, the package’s name.
string
required
Organization identifier the agent belongs to.
string
required
The bundle this agent was run from (provenance).
string
required
Human-readable pinned blueprint reference (its key), e.g. osm.
string
required
Immutable blueprint id the bundle pinned.
string
required
Agent lifecycle status; paused after a successful pause.
string
required
How the agent executes: batch, a run that finishes on its own, or serving, an agent that stays up to answer queries. v1.1.13+
string
required
Creation timestamp (date-time).
object
The I/O binding this run was started with; null when none is recorded.
string
External executor’s job id for the current run (a JOS job_ id). Present once the run has been dispatched.
string
When the run started; null before then.
string
When the run finished; null while unfinished.
string
Failure detail; null unless the run failed.

Important Notes

  • Pause is valid only from running. Calling it on a paused or terminal agent returns 409.
  • A serving agent cannot be paused; calling this endpoint on one returns 409. Cancel it instead.
  • A paused agent can be resumed or cancelled.
  • A 501 means the active runtime cannot hold a run in place (batch runs, for example, only support cancel); cancel the agent instead.