Running agents

Most integrations should start with streaming runs (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 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

​

Where to read next

• Interactive runs and local tools — diagrams and set_tools examples.
• 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.