run_agent, CLI execute --wait) as in 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 canawait 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 returnstask_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 — diagrams and
set_toolsexamples. - Webhooks — start +
AgentGraphRunStatusResponsehandler patterns.
asapi package for the exact symbol name.