Skip to content

Create Agent Run

POST
/agent/runs

Start a durable agent run.

“Run” is the public noun; the stored row is a work item and every internal name says so. The same translation app_pages_router makes for dashboards, and for the same reason: the public contract should read the way a builder thinks, not the way the table is named.

workflow_started: false is a NORMAL outcome, not an error. The row is persisted either way; a false means the Temporal worker did not pick it up on this attempt and the reason is carried alongside it.

Authorizations

Parameters

Header Parameters

X-Target-Org-Id
Any of:
string

Request Body required

Start a durable agent run. See the module docstring for what is omitted.

object
agent_id
required

Which agent drives the loop: ‘onboarding’, ‘dialer_setup’, ‘sequencer_setup’, ‘campaign_run’, ‘voice_setup’, ‘marketplace’, ‘dev_setup’, or a free-form value for an ad-hoc session.

string
entry_point
Any of:
string
goal
required

Free text the planner works from.

string
>= 1 characters
seed_message
Any of:
string
session_title
Any of:
string
skill_mode
Any of:
string
subject_account_id
Any of:
string
subject_campaign_id
Any of:
string
title
required
string
>= 1 characters <= 500 characters
visibility

‘private’ (default) keeps the run yours. ‘shared’ lets the organization see it, though only you can cancel it.

string
default: private /^(shared|private)$/

Responses

201

Successful Response

object
data
required
object
session_id
required
string
work_item_id
required
string
workflow_started
required

False is NORMAL, not an error: the run is stored either way and no worker picked it up on this attempt. Poll the run rather than retrying the create, which would start a second one.

boolean
workflow_started_reason
Any of:
string
pagination
Any of:
object
has_next
required

Whether there are more pages

boolean
limit
required

Items per page

integer
next_cursor
Any of:
string
page
required

Current page number (1-indexed)

integer
total
required

Total number of items

integer

422

Validation Error

object
detail
Array<object>
object
loc
required
Array
msg
required
string
type
required
string