Delegate a task to the Runtype operator agent

POST

/v1/delegate-tasks

POST

/v1/delegate-tasks

curl -X POST https://api.runtype.com/v1/delegate-tasks \
     -H "Authorization: <apiKey>" \
     -H "Content-Type: application/json" \
     -d '{
  "instruction": "Create a new customer support agent with escalation flow, add a tool for ticket lookup, and enable the live chat surface for the production environment."
}'

{
  "apiKeyId": "key_01HQ8ZTXN2F3G4H5J6K7L8M9P0",
  "clientName": "runtype-cli",
  "clientVersion": "2.4.1",
  "completedAt": "2024-11-15T10:35:42Z",
  "createdAt": "2024-11-15T10:34:58Z",
  "error": null,
  "id": "task_01HQ8ZTXN2F3G4H5J6K7L8M9P1",
  "instruction": "Create a new customer support agent with escalation flow, add a tool for ticket lookup, and enable the live chat surface for the production environment.",
  "lastEventSeq": 14,
  "modelRoundCount": 5,
  "organizationId": "org_01HQ8ZTXN2F3G4H5J6K7L8M9P2",
  "question": null,
  "result": {
    "links": [
      {
        "label": "Customer Support Agent",
        "url": "https://app.runtype.com/agents/agt_01HQ8ZTXN2F3G4H5J6K7L8M9P3"
      }
    ],
    "modelRoundCount": 5,
    "summary": "Created a customer support agent with an escalation flow, registered a ticket lookup tool connected to the helpdesk API, and enabled the live chat surface for the production environment.",
    "toolCallCount": 8,
    "touchedEntities": [
      {
        "action": "created",
        "id": "agt_01HQ8ZTXN2F3G4H5J6K7L8M9P3",
        "kind": "agent",
        "name": "Customer Support Agent"
      },
      {
        "action": "created",
        "id": "flow_01HQ8ZTXN2F3G4H5J6K7L8M9P4",
        "kind": "flow",
        "name": "Escalation Flow"
      },
      {
        "action": "created",
        "id": "tool_01HQ8ZTXN2F3G4H5J6K7L8M9P5",
        "kind": "tool",
        "name": "Ticket Lookup"
      }
    ],
    "totalCost": 0.0342,
    "warnings": [
      "Live chat surface requires manual DNS verification before going fully live."
    ]
  },
  "startedAt": "2024-11-15T10:35:01Z",
  "status": "completed",
  "summary": "Successfully created customer support agent, escalation flow, ticket lookup tool, and enabled live chat surface.",
  "toolCallCount": 8,
  "totalCost": 0.0342,
  "touchedEntities": [
    {
      "action": "created",
      "id": "agt_01HQ8ZTXN2F3G4H5J6K7L8M9P3",
      "kind": "agent",
      "name": "Customer Support Agent"
    },
    {
      "action": "created",
      "id": "flow_01HQ8ZTXN2F3G4H5J6K7L8M9P4",
      "kind": "flow",
      "name": "Escalation Flow"
    },
    {
      "action": "created",
      "id": "tool_01HQ8ZTXN2F3G4H5J6K7L8M9P5",
      "kind": "tool",
      "name": "Ticket Lookup"
    }
  ],
  "updatedAt": "2024-11-15T10:35:42Z",
  "userId": "user_01HQ8ZTXN2F3G4H5J6K7L8M9P6",
  "deduplicated": false
}

Start a task the operator agent works through in your organization: it reads and changes agents, flows, records, tools, evals and surfaces with the same authority as the caller. With waitSeconds the response waits up to that long for the task to finish or to stop on a question (input_required) before answering; otherwise it returns the queued task at once. An identical delegation from the same caller that is still running is returned again (200, deduplicated: true) instead of starting a second one. API keys need DELEGATE_TASKS:WRITE.

Authentication

AuthorizationBearer

API key or Clerk session token

Request

This endpoint expects an object.

instructionstringRequired1-20000 characters

allowDestructivebooleanOptional

clientNamestringOptional<=64 characters

clientVersionstringOptional<=64 characters

contextanyOptional

maxToolCallsintegerOptional1-200

waitSecondsintegerOptional0-240

Response

The still-running task this request duplicated

apiKeyIdstring or null

clientNamestring or null

clientVersionstring or null

completedAtstring or null

createdAtstring

errorstring or null

idstring

instructionstring

lastEventSeqinteger>=0

modelRoundCountinteger>=0

organizationIdstring

questionstring or null

resultobject or null

startedAtstring or null

statusenum

summarystring or null

toolCallCountinteger>=0

totalCostdouble or null

touchedEntitieslist of objects

updatedAtstring

userIdstring

contextanyOptional

deduplicatedbooleanOptional

True when an identical delegation from the same caller was still running, so that task was returned instead of starting another.

Errors

400

Bad Request Error

401

Unauthorized Error

403

Forbidden Error

404

Not Found Error

413

Content Too Large Error

503

Service Unavailable Error