JavaScript
Agents
Delete an agent
Remove an agent and its variations. Objectives already running keep going.
DELETE
JavaScript
Deletes an agent and its variations. Unlike a tool set, there is no assignment guard: a
The objective’s
DRAFT or a PUBLISHED agent both delete with a 200.
Running objectives are not affected
This is the guarantee worth knowing before you delete. An objective froze its agent and variation into aconfigSnapshot when it started, so it does not depend on the agent record surviving. Delete the agent mid-run and the objective keeps working. Verified end to end:
configSnapshot.agent still holds the deleted agent, with its original ID. The run reads everything it needs from that snapshot: prompt, model, tools, memory. So deleting an agent is safe for work in flight, the same way unpublishing is: existing objectives finish, only new ones are refused.
What delete takes with it
Deleting the agent clears its variations’ assignments, so a tool set it used is not stranded and stays deletable. The tool sets, sub-agents, and memory layers the variations pointed at are untouched: only the assignment links go.
Delete versus archive
There is no undo. To retire an agent while keeping its variations and feedback history, archive it instead. Archive is reversible and preserves thescore an agent’s variations earned; delete discards it. A subsequent GET on a deleted agent is a 404.
Reach for delete on a throwaway or a mistake. Reach for archive on anything whose variation scores you might want back.
Related
Archive an agent
The reversible retirement that keeps variation scores.
Unpublish an agent
Stop new objectives without deleting anything.
Get an objective
The
configSnapshot that keeps a run alive after its agent is gone.Delete a tool set
Why a tool set is no longer stranded when its agent is deleted.
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"