Start an agent run

Spawns a first-party containerized agent (e.g. the workflow-builder deep-agent) on the runtime worker. The org + user are taken from the authenticated request; the server mints the worker session.

POST /v1/agent-runs
Spawns a first-party containerized agent (e.g. the workflow-builder deep-agent) on the runtime worker. The org + user are taken from the authenticated request; the server mints the worker session.

Authentication

API Key (header: Authorization)

Request Body required

Agent run request

application/json
One of:
Option 1
Option 2
agentType string REQUIRED
AgentType selects which registered first-party agent to run. Required — the caller picks one from GET /v1/agent-runs/agents (the worker's enabled-agent discovery list). There is no default: routing an empty type to a fixed agent risks dispatching to a disabled one (an opaque 403).
conversationId string
Optional. Threads the run into an existing agent conversation; when empty the server generates a fresh conversation id (an independent thread).
parentProject string
ParentProject is the Braintrust project the parent span lives in (span nesting is project-scoped). Only meaningful together with ParentSpan.
parentSpan string
ParentSpan is an opaque Braintrust span slug (span.export()) of the calling conversation's current span. Passed through verbatim to the runtime worker so the deep-agent run's trace attaches under the parent Caddie chat's Braintrust trace. Optional; observability only — never affects run behavior.
payload object
Payload is agent-type-specific input passed opaquely to the runtime (e.g. app-builder build params: workflowId, manifest, archetypeHint, parentBuildId, recentBuilds). workflow-builder ignores it.
prompt string REQUIRED

Responses

200 OK
application/json
code integer
data object
agentType string
conversationId string
runId string
message string
requestId string 
curl -X POST 'https://api.example.com/v1/agent-runs' \  -H 'Authorization: Bearer YOUR_API_TOKEN' \  -H 'Content-Type: application/json' \  -d '{}'
const response = await fetch('https://api.example.com/v1/agent-runs', {  method: 'POST',  headers: {      "Authorization": "Bearer YOUR_API_TOKEN",      "Content-Type": "application/json"  },  body: JSON.stringify({})});const data = await response.json();console.log(data);
import requestsheaders = {    'Authorization': 'Bearer YOUR_API_TOKEN'}response = requests.post('https://api.example.com/v1/agent-runs', headers=headers, json={})print(response.json())
package mainimport (	"fmt"	"io"	"net/http"	"strings")func main() {	body := strings.NewReader(`{}`)	req, _ := http.NewRequest("POST", "https://api.example.com/v1/agent-runs", body)	req.Header.Set("Authorization", "Bearer YOUR_API_TOKEN")	req.Header.Set("Content-Type", "application/json")	resp, _ := http.DefaultClient.Do(req)	defer resp.Body.Close()	result, _ := io.ReadAll(resp.Body)	fmt.Println(string(result))}
200 Response 
{  "code": 200,  "data": {    "agentType": "<string>",    "conversationId": "<string>",    "runId": "<string>"  },  "message": "success",  "requestId": "abc-123"}
Previous Stream org activity events
Next List available agent types