Middesk APIAgentsRuns

Create an agent run

Creates a new agent run

Authentication

AuthorizationBearer

Bearer authentication of the form Bearer <token>, where token is your auth token.

Request

This endpoint expects an object.
typestringRequired
The agent type to use for this agent run
business_idstringOptionalformat: "uuid"

Business to use as context for the run. Shorthand for context_type=business. Required when thread_id is not provided (unless context_type and context_id are given).

context_typestringOptional

The type of context resource (e.g., “business”)

context_idstringOptionalformat: "uuid"

The ID of the context resource. Must be provided with context_type.

thread_idstringOptionalformat: "uuid"
Optional agent thread ID in which to execute the agent run

Response

agent run created within existing agent thread
objectstring
Object type identifier.
idstringformat: "uuid"
Unique identifier for the agent run.
created_atdatetime
Timestamp when the agent run record was created.
updated_atdatetime
Timestamp when the agent run record was last updated.
statusenum
Current lifecycle status of the agent run.
Allowed values:
thread_idstringformat: "uuid"
Identifier of the agent thread this run belongs to.
agentstring

Agent type that produced this run (for example, cip_orchestrator).

requesterobject or null

Principal that initiated the run. Populated with the authenticated user’s identity when a session caller initiates the run, and with the account when an API key caller initiates the run. null for system-initiated runs.

started_atdatetime or null
Timestamp when the agent run started.
ended_atdatetime or null
Timestamp when the agent run finished.
outputobject or null

Artifact envelope produced by the agent. Non-null only when status is completed; null for running, interrupted, and error runs.

interruptslist of objects

Pending interrupt requests awaiting input. Empty when the run is not interrupted. To resume a run, POST the interrupt’s id along with the caller-supplied input to POST /v1/runs/{id}/resume.

stepslist of objects

Top-level execution steps for this run. Opt-in: pass ?include=steps on GET /v1/runs/{id} (or POST /v1/runs/{id}/resume) to populate this field. Omitted by default to avoid the cost of fetching step state from the underlying execution backend.

Errors

400
Create Agent Run Request Bad Request Error
404
Create Agent Run Request Not Found Error
422
Create Agent Run Request Unprocessable Entity Error