Agent Execution APIs

Execute and interact with Supervity AI agents programmatically

This guide explains how to execute Supervity AI agents programmatically using APIs.

Use these APIs when you want to:

trigger agents from external systems
pass structured inputs to agents
monitor execution state and outputs
embed Supervity agents into your product or backend

If you are coming from API Reference, this document explains the agent execution model in practice.

Execution Model (Important)

Before calling the APIs, it’s important to understand how execution works in Supervity.

Core Concepts

Agent
An AI operator that reasons, plans, and governs execution
Workflow
The deterministic execution graph generated by an agent
Run (Job)
A single execution instance of a workflow

From an API Perspective

you trigger execution
supervity creates a run
the run executes the agent-backed workflow
you observe state, logs, and outputs

You never execute an agent “directly” — you always create a run.

Executing an Agent

Agent execution is performed using the workflow execution endpoint.

Endpoint

POST

text

Although the endpoint references a workflow ID, all executions are:

agent-backed
governed by policies
subject to approvals and permissions

Request Format

Required Fields

text
(string)
The ID of the workflow generated by an agent.

Inputs & Payloads

Inputs are sent using

text

.

Supported input types:

strings
numbers
booleans
files
arrays
structured objects (json-encoded)

Example: Simple Inputs

bash

File Inputs

bash

Files are scoped to the run and are not persisted beyond execution unless explicitly stored by a workflow step.

Execution Behavior

When a run is created:

inputs are validated
workflow definition is loaded
agent governance rules are applied
execution begins step-by-step
execution may pause for human review
execution completes or fails safely

Execution never bypasses:

approval steps
role permissions
integration access controls
policy constraints

Execution Responses

Immediate Response

The execute endpoint is asynchronous.

A successful request returns metadata indicating the run has started.

json

This does not mean execution has completed.

Run States

A run can transition through the following states:

text
text
text
(human review or input)
text
text
text

Run state is queryable at any time.

Retrieving Run Status & Outputs

Get Run Details

bash

Typical response:

json

Outputs reflect the final workflow state.

Monitoring Execution Programmatically

Polling (Simple)

You can poll until the run reaches a terminal state:

text

Recommended for:

background jobs
batch execution
simple backend integrations

Streaming (Recommended for Interactive Use)

For real-time visibility, use chat-based streaming APIs.

Streaming supports:

execution progress
step-level updates
planner events
human review interrupts
resume signals

→ see: Chat & Streaming APIs

Human Review & Interrupts

If a workflow includes human review steps:

execution transitions to
text
the run pauses safely
a human action is required
execution resumes after action

API-triggered runs behave exactly like UI-triggered runs.

→ see: Human-in-Command APIs

Error Handling

If execution fails, the run object includes:

failure reason
step where the failure occurred
error message
retry eligibility

Failures:

do not corrupt workflows
do not affect future runs
are fully logged and auditable

Permissions & Authentication

Execution is governed by:

token scopes
workspace role permissions
integration access
policy rules

If execution fails due to permissions, the response clearly indicates the violation.

Common Integration Patterns

Agent as a Backend Service

backend triggers agent execution
agent performs reasoning and orchestration
outputs returned to backend
approvals and governance still apply

Event-Driven Execution

external system emits event
backend or webhook triggers run
agent processes event payload
results stored or forwarded

Batch or Scheduled Execution

combine scheduling with api-triggered runs
treat agents as reliable jobs
monitor execution programmatically

Where to Go Next

approvals & interrupts → Human-in-Command APIs
streaming execution → API Reference
tool registration → Tooling & External APIs

Agent execution APIs allow you to treat Supervity agents as governed, observable services — not opaque ai calls.

text