JavaScript
Agents
Publish an agent
The gate between a draft agent and one that can run. Nothing happens until you publish.
POST
JavaScript
Every agent is created
A draft agent cannot take work. Creating an objective against one is a
Both errors name their field, so a setup script can tell “I forgot to publish” apart from “I sent a bad ID.”
No republish was called between creating the variation and running those objectives.
Publishing twice is a no-op and returns
That makes unpublish the kill switch for an agent misbehaving in production. Running objectives are unaffected, since they carry their own snapshot. New work is refused at the door.
Schedules keep their own
So a schedule that never produces runs is usually an unpublished agent, not a broken schedule. Nothing on the schedule says so: its state reads
STATE_DRAFT. A draft agent cannot run an objective, and a schedule pointed at one records a skip instead of firing. Publishing is the single step that turns configuration into something that works.
Two guards, both worth knowing
An agent needs at least one variation. The agent holds a name and a selection mode; every setting that matters (model, prompt, tools, memory) lives on a variation. Publishing without one is a400:
400, not a silent queue:
Publishing is a state, not a snapshot
This is the part that surprises people coming from deploy-style APIs. Publishing does not freeze your configuration. It flips a flag. Edit a published agent, add a variation, change a prompt: the agent staysSTATE_PUBLISHED and the change is live on the next objective. There is no republish step, and no draft-versus-live divergence to reconcile.
Add a second variation to a published agent and it serves traffic at once. Eight objectives against a VARIATION_SELECTION_MODE_RANDOM agent, immediately after the second variation was created:
What is frozen is the objective. Each one copies the agent and its selected variation into
configSnapshot at creation. Change the prompt afterward and running objectives keep the prompt they started with, while new ones pick up the change. Read configSnapshot.agentVariation to see exactly which variation served a given run.200, so a setup script can call it unconditionally.
Unpublish returns to draft
There is no separate “unpublished” state.:unpublish puts the agent back in STATE_DRAFT, where it stops accepting objectives:
STATE_ACTIVE while the agent is a draft, and quietly produce nothing. The same 60-second interval schedule, measured either side of a publish:
STATE_ACTIVE either way, and totalFires does not count the fires it declined.
The lifecycle
archive and unarchive are a separate axis for retiring an agent while keeping its history. delete is permanent and discards the variations’ feedback history, which is why archiving exists.
Related
Create an agent
variationSelectionMode, outputDefinition, and episodic memory.Create a variation
The thing publish requires at least one of.
Create an objective
Where
variationId pins a run to one variation.Schedule an agent
Why an unpublished agent’s schedule records skips.
Authorizations
Bearer authentication header of the form Bearer <token>, where <token> is your auth token.
Path Parameters
Workspace ID.
Example:
"workspace_01HXKD2E5NQM3T9AYWCF133E3Q"
Agent ID. Accepts the canonical agent_… form or the external_id:<value> form.
Example:
"agent_01HXKD2E5NQM3T9AYWCFMGWT9Y"
Body
application/json
Publish agent request
Response
OK
Agent resource
Resource metadata
Agent specification
The current lifecycle state of the agent. Output only. Agents are created in STATE_DRAFT; use the :publish, :unpublish, :archive, and :unarchive actions to transition between states.
Available options:
STATE_UNSPECIFIED, STATE_DRAFT, STATE_PUBLISHED, STATE_ARCHIVED Agent information