Human-in-Command APIs

This guide documents the APIs used to embed human oversight into Supervity AI agent execution.

Use these APIs when you want to:

• surface approvals outside Supervity
• embed review actions in external applications
• pause, approve, reject, or resume agent execution
• build custom command centers or approval dashboards

These APIs enable both:

• Agent → Human (A2H) interaction
• Human → Agent (H2A) control

Execution Model

Human-in-Command is implemented through interruptible execution.

At runtime:

• an agent may pause execution
• a human decision is required
• execution resumes based on that decision

From an API perspective:

• a paused run exposes a review object
• humans act on that object
• the agent resumes with the submitted payload

Execution is deterministic and auditable at every step.

Human Review Objects

Human review is represented as a User Form.

A user form encapsulates:

• execution context from the agent
• the decision required from a human
• allowed actions (approve, reject, modify, etc.)
• metadata linking back to the paused run

A form exists only while execution is waiting.

Listing Pending Reviews

Endpoint

GET

Query parameters:

• text

• text

• text

  (optional)

Example:

Typical response:

This endpoint is commonly used to:

• power approval dashboards
• build command center queues
• detect pending human actions

Fetching a Review Form

Endpoint

GET

Example:

Typical response:

You may:

• render the provided HTML directly
• build a custom UI using the schema
• embed the form into an external system

Submitting a Review Decision

Endpoint

POST

Request body (JSON):

Example:

What Happens After Submission

Once a review form is submitted:

1. input is validated
2. decision is recorded
3. agent execution resumes
4. decision payload becomes part of run context
5. downstream workflow steps execute accordingly

All actions are:

• logged
• auditable
• traceable to the reviewing user

Execution States & Interrupts

When execution requires human input, the run enters:

You can observe this via:

GET

Execution remains paused until the form is submitted.

Agent → Human (A2H) Events

In streaming or interactive contexts, human review triggers an interrupt event.

Example event payload:

This is how:

• UIs display approval prompts
• external systems detect required intervention
• command centers surface actionable items

Human → Agent (H2A) Resumption

Submitting a form automatically resumes execution.

No explicit “resume” API call is required.

If a decision results in rejection:

• execution may stop
• or branch into an alternate path (based on workflow design)

External Command Centers

These APIs enable enterprise-grade tooling such as:

• centralized approval dashboards
• operational command centers
• compliance and audit portals
• embedded approval widgets

Typical pattern:

1. list pending review forms
2. fetch review context
3. render decision UI
4. submit decision
5. monitor execution resumption

Security & Permissions

Human-in-Command APIs are governed by:

• user roles
• workspace permissions
• token scopes

Only authorized users can:

• view review forms
• submit decisions
• influence execution

All actions are attributed and logged.

Common Use Cases

Manager Approval Outside Supervity

• agent pauses execution
• backend fetches review form
• manager approves in internal app
• agent resumes automatically

Compliance Review Dashboard

• centralized queue of pending reviews
• SLA tracking and escalation
• audit-ready decision history

Human Override

• reviewer modifies values
• agent continues with corrected inputs
• decision becomes part of execution context

Where to Go Next

• agent execution → Agent Execution APIs
• tool registration → Tooling & External Apps
• core endpoints → API Reference

Human-in-Command APIs ensure AI agents operate with autonomy, but never without accountability.