Agent definitions
An agent definition describes an agent that an automation can run: its instructions, model and tools. List Productmind's standard agents and your own, create, update and delete definitions (deleting a customized standard agent resets it), list the tools an agent may use, and queue a run of one. Creating, changing and running definitions needs automations to be available to your organization. See Definitions.
List agent definitions for a workspace
Returns the custom agents available in this workspace: the system definitions shipped in code (as standard, or customized where this workspace has overridden one) followed by the workspace's own custom definitions. An uncustomized standard carries a synthetic standard:<slug> id and has no stored row.
path Parameters
workspaceIdWorkspace UUID
List agent definitions for a workspace › Responses
List of agent definitions
Create an agent definition
Creates a custom agent. The first save against a standard definition's slug creates the workspace's override row — it is a create, not an update. Requires the automation feature flag.
path Parameters
workspaceIdWorkspace UUID
Create an agent definition › Request Body
slug^[a-z0-9]+(-[a-z0-9]… · requiredUnique per workspace. Immutable after creation — it IS the agent_id.
nameinstructionsThe agent's SYSTEM PROMPT — who it is and how it works. Per-run data arrives as the invocation's input and context, never from here.
enabledtoolsTool registry keys. Validated against the live catalog on write.
toolsRequiringApprovalCreate an agent definition › Responses
Created agent definition
List the tools an agent definition may use
The live tool catalog: the agent server's built-in tools plus every MCP-exposed operation on this API, de-duplicated (a built-in shadows its MCP twin). Each entry says whether it writes (mutating) and whether a definition holding it can still run on the asynchronous queue (asyncEligible).
path Parameters
workspaceIdWorkspace UUID
List the tools an agent definition may use › Responses
Tool catalog
Get an agent definition by slug
Resolves one definition, falling back to the code-defined standard when this workspace has no override row — a standard with no row is a first-class result, not a 404. Returns 404 for an unknown slug, a disabled definition, or an organization without the automation flag.
path Parameters
workspaceIdWorkspace UUID
slugThe definition's slug — its agent_id
Get an agent definition by slug › Responses
Agent definition
Update an agent definition
Edits an override row and bumps its version. Send the version you read: a write carrying a stale version is rejected rather than silently overwriting a concurrent edit. The slug is immutable.
path Parameters
workspaceIdWorkspace UUID
slugThe definition's slug — its agent_id
Update an agent definition › Request Body
nameinstructionsThe agent's SYSTEM PROMPT — who it is and how it works. Per-run data arrives as the invocation's input and context, never from here.
enabledtoolsTool registry keys. Validated against the live catalog on write.
toolsRequiringApprovalversionUpdate an agent definition › Responses
Updated agent definition
Delete an agent definition
Removes the stored row. For a customized standard that IS the reset — the workspace falls back to the code-defined default and the version counter restarts on the next customization. For a custom definition it is an ordinary delete.
path Parameters
workspaceIdWorkspace UUID
slugThe definition's slug — its agent_id
Delete an agent definition › Responses
Deleted
Queue an asynchronous run of an agent definition
Publishes an agent.execute message and returns immediately; the run reports its usage and terminal status through a worker callback. Rejected when the definition holds a tool barred from the asynchronous path (update-*, delete-*, merge-*, bulk-*) or an MCP server with no allowedTools — such a definition can still be run synchronously. The run acts as the calling user.
path Parameters
workspaceIdWorkspace UUID
slugThe definition's slug — its agent_id
Queue an asynchronous run of an agent definition › Request Body
inputThe per-run instruction. Leads the user message. Omit it for an agent whose instructions already describe the whole job.
What caused this run. Rendered after input. Defaults to a by-hand trigger.
Queue an asynchronous run of an agent definition › Responses
Run queued