Agent runs

An agent run is one execution instance, not the agent definition itself. It gathers the trigger, input, ordered actions, state transitions, evidence, output, related runs, timestamps, and persistence mode needed to inspect what happened.

The dynamic Agent Runs route is verified, while a universal public start-run control or API is not.

A run is the unit that ties intent to evidence. It records how execution was triggered, what input it received, which agent definition it used, how actions progressed, what approvals or evidence were created, and what output and persistence remained. Idempotency and parent-child relationships add continuity across retries or delegated work. These features are runtime contracts; they do not establish a universal start-run interface, so procedures should stay focused on the records that can be verified.

Start a run

The helper-level creation path accepts the agent identity, trigger and input context, and optional idempotency information, then returns the created or previously matched execution. A registry entry that is planned, removed, or not implemented cannot be treated as a valid start target. The repository does not verify a universal public launch button or endpoint, so document the runtime contract without inventing surrounding controls.

The runtime helper starts a run only for a known registry entry whose implementation is not not_started. The supplied sources verify a dynamic /agent-runs index, but they do not define one universal UI button or public creation endpoint. Procedures should therefore begin with the runtime requirements rather than invented controls.

Trigger types in the type contract are manual, scheduled, webhook, and event_driven. Their presence defines a field vocabulary; it does not prove that every trigger path is connected in the current product.

The runtime helper creates runs for known registry entries whose implementation is not not_started.

Manual, scheduled, webhook, and event_driven triggers exist at the type-contract level.

Exact UI or external API steps for initiating every trigger type are not verified.

Starting a run requires a valid agent slug and implementation state. The runtime can use an idempotency key to return an existing run, but the sources do not establish a universal user-facing start button or public creation endpoint.

A receipt may summarize the execution history without replacing signed decisions, transition logs, evidence, or audit events.

The runtime stores runs, actions, evidence, transition logs, and dashboard summaries. Persistence mode is environment-dependent and can be durable, local-file, memory-only, or unavailable. Idempotency and parent-child relationships describe continuity without proving a universal start-run interface.

Run inputs

Input should contain task data rather than credentials. An idempotency key can cause the helper to return an existing run, which prevents duplicate creation within that supported path.

Parent and child IDs represent delegated or related execution. They should not be interpreted as automatic concurrency, branching, or compensation behavior. Inspect each run’s own state and actions.

A run can include structured input, initiator identity, trigger type, parent-run ID, and an idempotency key.

Keep secrets out of general input payloads unless a verified credential mechanism requires otherwise.

The run helper reuses an existing execution when the idempotency key matches.

Run inputs should contain task data and context, not secrets. Trigger type, initiator, idempotency key, and optional parent-run relationship belong to the run record and help explain how the execution began.

Trigger types are manual, scheduled, webhook, and event-driven, although type presence does not prove every trigger is live. Waiting, approval, recovery, failure, rejection, cancellation, and expiry carry different operator obligations.

A completed state should not be substituted for partially approved, paused, rejected, failed, or expired outcomes. Audit events are recorded for creation, cancellation, and failure paths. A matching idempotency key can resolve to the existing execution.

Inputs should contain the data required by the agent contract and no embedded credentials. The run record can also identify the initiator and parent run, which helps separate user-launched work from child execution. Trigger values such as scheduled, webhook, or event-driven are type-level possibilities; their presence does not prove that every trigger path is live in the current product.

States

The run state must use the declared vocabulary exactly. Active or waiting states include pending, queued, planning, running, waiting_for_user, awaiting_approval, partially_approved, paused, and recovering. Terminal states are completed, failed, rejected, canceled, and expired.

The state machine rejects invalid transitions and prevents terminal states from changing. Approval states require proposal, evidence, or metadata context; a label alone is not enough.

Verified states include pending, queued, planning, running, waiting_for_user, awaiting_approval, partially_approved, paused, recovering, completed, failed, rejected, canceled, and expired.

Terminal states do not allow further transitions.

States communicate the current operator obligation: wait, provide user input, review an approval, inspect recovery, or review a terminal outcome. Use only the declared state names.

Run state, transition history, actions, decisions, evidence, output, audit events, and persistence are separate authoritative records. Runs can reference a parent run and the store supports parent-child relationships.

Terminal states should not transition again, and approval-related moves require the context declared by the state machine.

Events

Run history is represented through transition logs, action changes, evidence, approval decisions, and audit events. The helper records audit events for creation, cancellation, and failure paths. Actions retain ordered step, tool, risk, status, input, output, proposal, and timestamps.

Use the transition log to explain how the current state was reached. A dashboard summary can show counts and timestamps, but it cannot replace the ordered history.

Transition logs record changes between states. Retain the identifiers and redacted evidence needed to explain those changes without copying secrets into review material.

Audit events are produced for run creation, cancellation, and failure paths in the helper layer.

Actions and evidence add execution detail beyond the high-level event sequence and show whether a failure came from one attempt or from a persistent readiness or policy condition.

Events include transition logs and audit events as well as actions, proposals, decisions, and evidence. They should be correlated by run and action identifiers rather than reconstructed from a dashboard label alone.

Audit events are useful for creation, cancellation, and failure chronology, but they do not replace the action or evidence records. Read the event time together with the transition log and action status. This is especially important for parent and child runs, where events from one execution should not be attributed to another merely because they share an agent slug.

Outputs

Read the output together with final state and action results; a populated field does not override a failed or rejected execution.

A run may contain an output value and can reference evidence or artifacts. Output is the result exposed by the run; evidence supports review; an artifact is a separately addressable deliverable or record. Export readiness is another property and should not be assumed from output presence.

Persistence mode determines what storage claim is safe. durable refers to the configured durable service, local_file is private-beta fallback storage, memory_only survives only within the process, and unavailable indicates that persistence cannot be provided.

A run can carry an output and an output-presence summary.

Actions can produce outputs, while evidence records attach supporting material to the run or action.

Do not treat an evidence item as the final run result unless the contract explicitly uses it that way.

Outputs belong to the run or individual actions and should be reviewed with state, evidence, and persistence mode. Output presence does not automatically mean the run completed or produced a durable artifact.

Evidence may support review without being the final output, and an audit event is not a substitute for the underlying artifact.

Export readiness should be treated as a separate property rather than inferred from the existence of an output value. When an idempotency key matches an accepted request, run creation can return the existing run instead of duplicating it.

Troubleshooting

If a run will not start, confirm the slug, registry entry, implementation status, and persistence environment. If it waits, inspect whether the state is waiting_for_user or approval-related. If an action is blocked, check its execution state, permission, risk, provider, workspace scope, and approval requirement.

For missing history, inspect persistence mode before assuming deletion. A process restart can remove memory-only records, while local-file storage is not equivalent to the durable database path.

Check registry existence and implementation state when creation fails.

Inspect invalid transitions, blocked tools, pending approvals, persistence mode, and failure details when progress stops.

Use the verified Agent Runs surface to correlate child runs, actions, evidence, timestamps, and final state.

Troubleshooting begins with registry and implementation status, then the exact run state and transition error, followed by tool eligibility, credentials, approvals, child runs, and persistence.

Before expanding the integration, preserve identifiers from creation onward, use an idempotency key when the caller needs duplicate protection, and read child actions before judging the final state.

The /agent-runs index is verified, but no universal start-run UI or public endpoint is established by the supplied sources.

Run creation can fail before any action starts. Run creation cannot begin when the registry entry is absent or the implementation is marked not_started; that is a definition problem, not a tool outage. When an idempotency key matches an existing execution, the helper can return that run instead of creating another one, so callers should compare the returned run ID before assuming a new attempt began.

Parent-run IDs represent execution relationships; they do not by themselves prove concurrency or branching. Read child actions in order and correlate each proposal, approval decision, evidence record, and output with the owning run. Persistence mode changes what survives an environment change: durable Supabase, local-file private-beta fallback, memory-only, and unavailable are materially different. A missing history after restart should therefore be diagnosed through persistence mode before it is treated as an execution-state defect.