> ## Documentation Index
> Fetch the complete documentation index at: https://docs.sudoiq.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Running agents

> Default streaming runs and optional webhook delivery for long jobs

Most integrations should start with **streaming** runs (`run_agent`, CLI `execute --wait`) as in [Getting started](/quickstart/getting-started). When you **cannot** hold a long-lived connection, the API can deliver the **same run state machine** via **HTTPS callbacks** instead.

## Streaming (long-lived connection)

After you start a run, the client keeps **one HTTP connection open** while the server **pushes** status updates (using **server-sent events**, or **SSE**, under the hood). Your process can `await` completion in a single call (`run_agent` / `execute_agent` in Python, or `agentservice execute ... --wait` in the CLI, which prefers streaming when available).

**Best for:** scripts, app servers that can hold a connection open for minutes, and workflows where you want **in-process tool handlers**.

## Webhooks (push to your URL)

You start the run with a **normal request** that returns **`task_id`**, then your **HTTPS endpoint** receives **POST** callbacks with run status until the run finishes. You respond to **tool-call** pauses by posting results back to the API.

**Best for:** runs that may last **hours or days**, serverless or queue-driven systems, or anywhere you **do not** want to keep a streaming connection open.

## Comparison

|                             | **Streaming (interactive)**                                             | **Webhooks**                                                                                                   |
| --------------------------- | ----------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------- |
| **How progress arrives**    | Long-lived connection; server pushes JSON events.                       | Your HTTP endpoint receives **push** payloads.                                                                 |
| **Where tool handlers run** | Same process that started the run (Python) or CLI tool-handler scripts. | Webhook handler or worker you dispatch to.                                                                     |
| **Typical use**             | CLIs, demos, long-lived services.                                       | Async backends, very long runs, multi-tenant SaaS.                                                             |
| **Starting the run**        | `execute_agent` / `run_agent` starts and consumes the stream.           | A **start-only** call returns `task_id`; configure the product to POST to your URL. Do **not** poll in a loop. |

## Where to read next

* [Interactive runs and local tools](/agents/sse-and-local-tools) — diagrams and `set_tools` examples.
* [Webhooks](/agents/webhooks) — start + `AgentGraphRunStatusResponse` handler patterns.

Use whichever **start** method your SDK exposes for webhook mode (often a “polling” or “start only” execute variant that does **not** open the event stream). See the installed **`agentsapi`** package for the exact symbol name.