Skip to main content
Background tasks let runnables execute asynchronously while the agent continues. When a tool runs in the background, it immediately returns a task_id and status: "running" instead of blocking until completion.

​
Configuring Background Mode

The background_mode parameter controls when a runnable executes asynchronously:
  • "never" (default) — always runs synchronously
  • "always" — always runs in the background
  • "auto" — the LLM decides per call by setting run_in_background=True on the tool input
The built-in Bash tool uses background_mode="auto" by default. The model can run a shell command in the background by passing run_in_background=True.

​
Checking Task Status

Background tools return immediately with a task handle:
Once at least one background task is running, the agent automatically exposes a get_background_task tool. Call it with the task_id to poll status and drain queued events:
Or let the agent poll for you on a follow-up turn — it will see get_background_task in its tool list and can call it with the task_id from the earlier tool result.