Execution API

The Execution API starts and tracks agent, task, and workflow runs. It also manages conversations and the triggers that start work automatically.

Runs

A run records one execution: its input, status, events, output, and errors. The run ID identifies that execution throughout its lifecycle.

Runs can start child runs. Parent and child IDs link delegated work to its results. Access checks apply to each run.

Look up event types and groups in the run event reference.

Conversations

A conversation stores messages and related agent runs. Branches preserve alternative message paths. Participants and read state support collaboration.

Saving a message does not start a run. Execution requires a separate run request. Project-owned agent runs can execute without a conversation.

An input request asks a person for structured information while execution waits. Input responses and run resumes have separate operations. The resume operation accepts signals supported by the run kind and current waiting reason.

Definitions and triggers

Task and workflow definitions describe work and live in project source. Each execution has its own run history. Agent definitions belong to the Agents API.

A job runtime executes tasks and workflows. Schedules start work at configured times. A webhook stores each delivery as an event. When the webhook targets an agent, task, or workflow, a matching event starts a run. Each run retains its own identity and progress.

A support interaction

A new question can start an agent run associated with a conversation. The runtime reports progress through events, and the conversation stores the resulting messages. The same project can also run a scheduled summary task without a chat thread.

An accepted run may still fail. Read its status and output, and inspect child runs when work was delegated.

Runtime integration

An agent service exposes an invocation endpoint. A worker connects to accept work. They can execute on infrastructure you manage while Cloud records run state and history. Both report progress and completion against the assigned run identity.

Runtime registration, event publication, and completion use the credentials required by their integration contract. Those credentials can be scoped to a service, project, or run. Read access to a run does not imply permission to publish its events or mark it complete.

A disconnected worker or closed client stream does not establish that a run succeeded. Check its recorded status and output.

Explore the execution model

Get started

Run an agent, connect your own runtime, schedule a task, or trigger work from a webhook. Inspect the resulting run to verify its outcome.

API references