---
title: "Start an agent run"
method: POST
path: "/v1/agent-runs"
tags: ["agent-runs"]
---

# Start an agent run

`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.

## Request body

- union
  - object
  - StartAgentRunParams
    - `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

## Response `200`

OK

- StartAgentRunSuccessResponse
  - `code` integer
  - `data` StartAgentRunResponse
    - `agentType` string
    - `conversationId` string
    - `runId` string
  - `message` string
  - `requestId` string

---

[API](https://skmtc.dev/b3os/apis/b3os-workflow-api.md) · [All operations](https://skmtc.dev/b3os/apis/b3os-workflow-api/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/b3os/b3os-workflow-api/revisions/a8c7af3c66a1/schema)