Run Lifecycle¶

A run represents a single invocation of an agent -- from the initial request to completion. RunAgents tracks every run through a defined state machine, logs events, and manages approval workflows when the agent encounters a restricted tool.

Creating a Run¶

Runs are created when an agent is invoked, either through:

• A client application sending a request to the agent's endpoint
• An API call to the agent's invoke URL
• A background trigger or scheduled invocation

Each run is assigned a unique ID and begins in the RUNNING state.

Run States¶

State Transitions¶

                 ┌──────────────────────────────────┐
                 |                                  |
                 v                                  |
RUNNING ───> PAUSED_APPROVAL ───(approved)───> RUNNING
   |                |
   v                v
COMPLETED       FAILED

RUNNING ───> FAILED
RUNNING ───> COMPLETED

Events¶

Every run has an ordered event log that records what happened during execution. Events are automatically sequenced -- each event gets a monotonically increasing sequence number.

Events provide a complete audit trail of agent behavior. Use them for debugging, compliance, and understanding agent decision-making.

Viewing Events¶

# List events for a run
curl https://your-platform/runs/{run_id}/events

Blocked Actions and Approval Workflow¶

When an agent calls a tool that requires approval, the following sequence occurs:

1. Request Blocked¶

The platform intercepts the tool call and determines that the agent does not have an active policy binding, and the tool requires approval.

2. Blocked Action Created¶

A blocked action is created with:

3. Run Paused¶

The run transitions to PAUSED_APPROVAL. An APPROVAL_REQUIRED event is logged with the details of the blocked action.

4. Admin Reviews¶

Administrators can see pending approvals in the console (Approvals page) or via the API. Each approval request shows:

• Which agent is requesting access
• Which tool and operation
• The payload hash (for integrity verification)
• When the request was created

5. Approval or Rejection¶

6. Automatic Resumption¶

After approval, a background worker detects the approved action and automatically:

1. Invokes the agent to resume execution
2. Marks the blocked action as EXECUTED
3. Transitions the run back to RUNNING
4. Logs an APPROVAL_GRANTED event

The agent retries the tool call, which now succeeds because the policy binding exists.

Payload Hash Integrity¶

Blocked actions include a cryptographic hash of the original request payload. This serves as a tamper-detection mechanism:

• When the admin approves the action, the hash is recorded
• When the agent resumes and retries the tool call, the platform verifies the payload hash matches
• If the payload has changed (e.g., the agent modified the request), the call is rejected with a 409 Conflict

This prevents a scenario where an agent modifies its request after receiving approval for a different payload.

Run Correlation¶

When a tool call is blocked and an approval is needed, RunAgents correlates the access request with the run:

• The run_id is attached to the access request
• The blocked action is linked to both the run and the access request
• Events reference the action ID for traceability

This allows you to trace from a run event back to the approval decision, and from an approval back to the specific run that triggered it.

Viewing Runs¶

# List all runs
curl https://your-platform/runs

# Get a specific run
curl https://your-platform/runs/{run_id}

# List events for a run
curl https://your-platform/runs/{run_id}/events

# Get a blocked action
curl https://your-platform/runs/{run_id}/actions/{action_id}

Summary¶

Next Steps¶

• Policy Model -- Understand how access control modes trigger the approval workflow
• Troubleshooting -- Common run issues and how to resolve them