Skip to main content
Last updated on

Supervisor Agent long-running tasks

This page explains how to handle long-running tasks using task continuation with Supervisor Agent.

When a supervisor agent works on complex tasks that require many tool calls, the task might need more time than a single API request allows. To handle this, the supervisor supports long-running task mode, which automatically breaks long tasks into multiple request/response cycles so the agent can continue working without timing out.

How it works​

  1. The supervisor starts processing your request, calling tools and reasoning as needed.
  2. Before the request times out, the supervisor pauses execution and emits a task_continue_request event in the streaming response.
  3. To resume the task, your application sends a follow-up request that includes both the task_continue_request and a corresponding task_continue_response.
  4. The supervisor picks up where it left off and continues working. This cycle repeats as needed until the task is complete.

Use long-running tasks in Playground​

In AI Playground, the agent pauses when it reaches the limit and a message in the UI asks what you want to do next. Type continue to keep processing or wrap up to end the task.

Handle task continuation in the API​

To enable long-running tasks, include "long_task": true in the databricks_options of your request:

JSON
{
  "input": [{ "role": "user", "content": "Your message here" }],
  "databricks_options": {
    "long_task": true
  },
  "stream": true
}

When using the streaming API directly, your application must detect task_continue_request events and send a follow-up request to continue the task.

Detect the checkpoint event in the streaming response​

The supervisor emits an event like the following when it needs to continue:

JSON
{
  "type": "response.output_item.done",
  "item": {
    "type": "task_continue_request",
    "id": "continue_<unique-id>",
    "step": 16
  },
  "id": "resp_<response-id>"
}

The step field indicates the total number of tool call steps completed so far.

Send a follow-up request to resume​

Include the original task_continue_request and a matching task_continue_response in the messages of your next request:

JSON
{
  "messages": [
    "...previous messages...",
    {
      "type": "task_continue_request",
      "id": "continue_<unique-id>",
      "step": 16
    },
    {
      "type": "task_continue_response",
      "continue_request_id": "continue_<unique-id>"
    }
  ],
  "databricks_options": {
    "long_task": true
  },
  "stream": true
}

The continue_request_id must match the id from the task_continue_request.

Known limitations​

  • If a single tool call or model call runs longer than the API timeout, the request might still time out because the continuation checkpoint can only be triggered between steps.
  • Full long-running agent support, including timeouts during individual tool calls or model calls, is not yet available.
On this page