Agent lifecycle

An agent lifecycle has two layers: the registry entry that describes whether an agent is planned, published, deprecated, or removed, and the runtime execution that creates and advances individual runs. Keeping those layers separate prevents a published definition from being mistaken for a healthy run.

Exact user-facing lifecycle controls are not fully verified, and persistence can vary by environment.

Lifecycle review should answer three different questions: Is the agent definition current, is its implementation runnable, and what is the state of the execution being inspected? A definition can be published while implementation remains a stub, and an active implementation can still produce a run that is waiting, rejected, failed, or expired. Keeping those dimensions separate makes retirement, recovery, and approval decisions easier to reason about and avoids inventing transitions for terminal states.

Create

Creation begins with a registry entry and a runtime-eligible implementation. The helper rejects an unknown slug and an implementation marked not_started. The run record can capture trigger type, initiator, input, idempotency key, and parent-run ID. Exact builder controls are not verified, so creation should be documented as a runtime contract rather than a universal UI procedure.

If the same supported idempotency key is presented again, the helper can return the existing run. This behavior belongs to agent runs; it must not be extended to Gateway chat requests.

A run can be created only for a known registry entry whose implementation is not marked not_started.

Creation records the agent slug, trigger, input, initiator, optional parent run, and optional idempotency key.

The helper layer reuses an existing run when the same idempotency key resolves successfully.

Creating an agent means establishing a registry definition with a stable slug and implementation status. The current sources do not prove one universal creation screen, so field-level guidance should be framed as a contract rather than a click path.

Persistence can be durable, local-file, memory-only, or unavailable depending on the environment. Run states include pending, queued, planning, running, waiting for user, approval states, paused, recovering, and terminal outcomes. Retirement and lifecycle guidance should follow declared transitions rather than an assumed administrative interface.

A missing registry entry or a not-started implementation prevents run creation. Invalid lifecycle transitions return explicit errors, and terminal states cannot advance. Agent definition, registry lifecycle, implementation status, tool authority, and run state remain separate dimensions.

Configure

Configuration determines whether the active implementation has enough information and permission to create useful work. The supplied contracts cover agent identity, inputs, tool access, execution controls, and approval context, but they do not establish a universal editing screen. Treat changes to the definition separately from operations on existing runs: updating an agent does not retroactively rewrite the state, evidence, or decisions already recorded for an execution.

Configuration spans more than the agent’s name or instructions. The definition can include workflow steps, evidence requirements, artifact expectations, proposed actions, approval boundaries, demo fixtures, and evaluation cases. Tool definitions add risk, permission, approval, execution state, provider, and allowed scope.

A planned or contract-only tool should remain visible as non-executable configuration. The same rule applies to stub connectors and agent implementations that have not reached active.

Configuration can define model and instructions at the agent contract level, permitted tools, permissions, approval boundaries, and workspace scope.

Registry lifecycle and implementation status should be reviewed together.

A general-purpose visual configuration workflow is not established by the source bundle.

Configuration connects the definition to models, tools, permissions, scopes, approval boundaries, and workflow contracts. A published lifecycle value does not override a not-started or stub implementation.

Moves into approval states require proposal, evidence, or metadata context. A contract-oriented guide can identify required fields without inventing a universal builder or control sequence.

Published registry status does not make a stub implementation runnable, and an active implementation does not guarantee every run succeeds.

Run

The declared states are pending, queued, planning, running, waiting_for_user, awaiting_approval, partially_approved, paused, recovering, completed, failed, rejected, canceled, and expired. Transitions are controlled by the state machine, and terminal states cannot continue.

Approval transitions require relevant proposal, evidence, or metadata context. A tool proposal can start immediately, become blocked, or wait for a signed decision. Rejection may move the containing run to rejected.

Runs begin in declared states and advance through the state machine.

Actions are ordered and can carry tool, risk, status, input, output, proposal, and timestamps.

Invalid transitions are rejected rather than silently accepted.

A run can begin only when the registry entry exists and its implementation passes the helper checks. Once created, the run moves through the exact state vocabulary declared by the runtime.

Idempotency and parent-child relationships describe continuity without proving a universal start-run interface. The run review contract includes the fact that run states include pending, queued, planning, running, waiting for user, approval states, paused, recovering, and terminal outcomes.

Change the agent definition separately from operations on existing runs. Before resuming, approving, rejecting, canceling, or recovering an execution, confirm that the requested transition is allowed from its current state.

Waiting, approval, recovery, failure, rejection, cancellation, and expiry carry different operator obligations.

Observe

Observation combines the current state with actions, evidence, transition logs, child runs, timestamps, output presence, trigger, and persistence mode. A summary can show counts, but counts do not replace the underlying records. For example, one evidence count does not reveal whether the record is a report, diff, log, or audit snapshot.

The verified Agent Runs route renders dynamic platform runs. Filtering, replay, and start-run controls around the index are not fully established.

Run summaries expose trigger, output presence, action count, evidence count, child count, timestamps, and persistence mode.

Transition logs and audit events show how the execution changed state.

Parent and child references allow subagent or related-run inspection where present.

Observation combines state, ordered actions, evidence, transitions, audit events, output, timestamps, child runs, and persistence mode. A dashboard summary should not replace the underlying records when diagnosing a transition or approval issue.

Read request and trace identifiers first, then correlate route, provider attempts, latency, errors, and usage in processing order.

Observation combines the current state with the records that explain it. Action order shows work attempted, transition history shows lifecycle movement, evidence supports proposals or outcomes, and audit events record runtime activity. No single dashboard label should replace those records when reviewing an approval or failure.

Review

Review should distinguish execution outcome from governance outcome. completed describes a terminal run state. partially_approved, awaiting_approval, rejected, failed, and canceled carry different meanings and should not be summarized as merely unfinished.

A receipt may present a concise summary, but transition logs, signed approvals, evidence, action output, audit events, and persistence remain authoritative for detailed review.

Review the final state, actions, evidence, approvals, output, failure details, and persistence result together.

Awaiting approval, partially approved, waiting for user, paused, and recovering are not terminal success states.

Evidence and audit records should be used to support a conclusion rather than substituted for the run output.

Review is especially important at waiting, approval, recovery, and terminal states. Approval transitions require proposal, evidence, or metadata context, while terminal states cannot be resumed through another transition.

Completed, failed, rejected, canceled, and expired states are terminal. The proposal, parameters, risk, evidence, signer, decision, transition, and audit event should remain correlated.

Approval-required and blocked are different states: one requests a decision, while the other may indicate missing authority or policy.

Retire

Retirement changes whether new work should begin; it does not erase the historical record of prior executions. Deprecated and removed registry states should be reflected in selection and launch behavior while existing runs, transitions, evidence, and audit events remain interpretable. Exact archival, retention, and historical filtering controls are not fully verified.

Registry lifecycle supports deprecated and removed, but the supplied sources do not verify a general retirement UI or an automatic migration process. Retirement documentation should avoid inventing delete buttons, replacement mappings, or retention rules.

A terminal run remains terminal even if the underlying agent definition is later deprecated or removed. Definition lifecycle changes and historical run state are separate records.

Registry lifecycle supports deprecated and removed states, but exact retirement controls are not described in the supplied UI evidence.

Do not start new work from an implementation marked not_started or a removed registry entry.

Preserve existing run history according to the actual persistence system rather than promising a retention period.

Retirement belongs to registry lifecycle, not to the state of an existing run. Deprecating or removing a definition does not rewrite completed execution history, and the exact retirement UI remains unverified.

Exact creation, configuration, and retirement controls are not verified as a universal UI; terminal states cannot transition and approval states require context.

Retirement affects the registry definition, not the historical truth of completed runs. Deprecating or removing an entry should prevent new use according to the registry and helper behavior, while existing action, evidence, transition, output, and audit records remain separate records subject to the environment’s persistence mode. The supplied sources do not define a universal deletion or retention policy for those records.

Lifecycle and implementation status must continue to be reported independently. Moving an entry from draft to published does not change not_started code into an active implementation. Similarly, a run that reached completed, failed, rejected, canceled, or expired is terminal and cannot be reopened by changing the registry entry. New recovery or replay behavior must follow exported helpers and the declared state machine rather than rewriting a terminal status.