Agents overview

An Ethen agent is a registered capability that can create a run, plan or execute ordered actions, call eligible tools, collect evidence, and stop at approval or policy boundaries. The registry also contains planned and stub entries, so registration alone does not mean an agent is runnable.

Current evidence spans active runtime primitives, private-beta persistence, demo contracts, stubs, and planned entries rather than one uniformly available agent product.

The runtime should be read as a set of related records with different authority. The registry describes the agent definition, implementation status describes whether code is ready, tool contracts describe allowed operations, and a run records one execution. Actions, proposals, decisions, evidence, transitions, and persistence then explain the execution in detail. Treating those records separately prevents a published registry entry, demo fixture, or exported helper from being mistaken for a generally available agent capability.

What an agent is

Four identities should remain separate during review: the registry entry describes the agent, implementation status indicates whether code is not started, stubbed, or active, the run represents one execution, and each action represents a unit of work inside that execution. Evidence and audit events explain decisions around those actions. Confusing any of these layers can make a planned entry look runnable or make a UI fixture look authoritative.

An agent definition identifies a capability through a registry entry and slug. The registry lifecycle describes the definition’s product state—planned, draft, published, deprecated, or removed. Implementation status is separate and can be not_started, stub, or active. A published entry can therefore remain non-runnable when its implementation has not reached an active state.

A run is one execution of an eligible agent. It carries trigger, input, output, initiator, timestamps, idempotency context, and an optional parent-run relationship. The definition and the run should never be treated as the same record.

An agent is identified by a registry entry and an agent slug used by runs.

Implementation status can be not started, stub, or active and must be checked separately from lifecycle.

An agent definition lives in the registry and is addressed by slug. Lifecycle describes the product definition, while implementation status states whether runtime code exists; both must be checked before a run can be considered possible.

Actions record ordered steps, tools, risk, status, input, output, proposal ID, and timestamps.

Evidence can be source data, screenshots, reports, logs, diffs, exports, or audit snapshots. Implementation status values are not started, stub, and active. Retirement and lifecycle guidance should follow declared transitions rather than an assumed administrative interface.

Agent components

The runtime exports registries, run and action stores, evidence stores, transition logs, persistence detection, recovery helpers, replay helpers, artifact helpers, and subagent relationships. Exported code establishes a contract or utility, not automatic public availability. Demo runs and fixtures must remain labeled as examples.

An action represents one ordered unit of work inside a run. It can identify the tool, step number, risk, status, input, output, proposal, and timestamps. Evidence can point to source data, screenshots, reports, logs, diffs, exports, or audit snapshots. These lower-level records explain the run summary.

A run carries trigger, input, output, initiator, timestamps, and optional parent-run context.

Actions and evidence provide the operational record beneath a run summary.

Agent components include the registry, run and action records, evidence, transition logs, persistence, recovery helpers, and parent-child relationships. These records make one execution inspectable without turning every exported helper into a public product feature.

Tool execution states are available, contract-only, and planned. Agent definition, registry lifecycle, implementation status, tool authority, and run state remain separate dimensions.

Capabilities

Agent capability depends on the definition, implementation state, eligible tools, workspace scope, permissions, credentials, policy, and approval requirements. Tool execution states are available, contract_only, and planned; only the first indicates a current execution path. Permission modes and risk levels then constrain what the tool may do.

A large tool identifier union should not be presented as a list of live integrations. The current definition for each tool must be checked for execution state, provider, allowed agents, workspace archetypes, and approval behavior.

Capabilities are constrained by registered configuration, permitted tools, workspace context, permission mode, and approval requirements.

Tool contracts distinguish available, contract-only, and planned execution states.

A broad ToolId type or demo fixture does not prove that the corresponding operation can execute.

Capabilities are bounded by tool contracts, workspace and agent allow-lists, permission modes, risk, credentials, and approval requirements. A large ToolId union is a catalog of definitions, not a list of tools that are all executable.

Registry lifecycle values are planned, draft, published, deprecated, and removed. Availability can still be narrowed by the selected agent, workspace, credentials, policy, or approval state.

Execution

createAgentRun rejects a missing registry entry and an agent whose implementation is not_started. Submitting a previously accepted idempotency key can resolve to the existing run. During execution, tool actions can be blocked, sent for approval, or started according to policy. Decisions can approve or reject a proposed action, and rejection can move the run into rejected.

Persistence is environment-dependent. The service can report durable, local_file, memory_only, or unavailable. Local-file storage is labeled private-beta durable and is not equivalent to production database persistence.

A run moves through declared states rather than an unrestricted loop.

Risk and policy determine whether an action is denied, held for approval, or allowed to start.

Terminal states prevent additional transitions.

Execution occurs through explicit run states and ordered actions. A tool action can be blocked, proposed for approval, or started; terminal run states prevent later transitions.

Governance

Allowed transitions are explicit, and terminal states reject further movement. Approval-related states require proposal, evidence, or metadata context. Audit events are recorded for creation, cancellation, and failure paths in the supplied helpers.

Governance should be described through these explicit records: registry and implementation status, run state, action status, tool contract, proposal, signed decision, evidence, transition, audit event, and persistence mode. A demo fixture or scaffolded UI card does not carry the authority of those execution records.

Permission modes, risk levels, approval requirements, tool decisions, evidence, and audit events constrain action execution.

Signed decisions from the agent-run approval service are distinct from scaffolded cards on the general Approvals page.

Persistence mode must remain visible because durable, local-file, memory-only, and unavailable states have different operational consequences.

Governance is represented in the same records as execution: risk and permission fields on tools, proposals and decisions on actions, evidence supporting changes, audit events, and persistence mode. These should remain visible during review.

A signed decision tied to an agent run carries authority; a scaffolded card on the general Approvals page does not persist a decision.

A run carries an agent slug, trigger, input, output, timestamps, initiator, and optional parent-run ID. The proposal, parameters, risk, evidence, signer, decision, transition, and audit event should remain correlated.

Where to begin

Read the lifecycle page for state and persistence behavior.

Use capabilities and tools before granting an agent access to side-effecting operations.

Open agent runs when you need to inspect one execution instance rather than the registry definition.

Begin with lifecycle and implementation status, then inspect tool eligibility and approval requirements, and finally use Agent Runs to review a concrete execution. This sequence keeps registry concepts separate from observed behavior.

Registry exports, functional demo contracts, and mock fixtures do not prove general availability; current evidence spans active primitives, stubs, planned entries, and private-beta persistence.

Begin by separating three kinds of state. The registry lifecycle says whether an agent definition is planned, draft, published, deprecated, or removed. Implementation status says whether its code is not started, stubbed, or active. A run state applies only after an executable agent has created a specific execution. A published registry entry can therefore remain unrunnable when implementation is missing, and an active implementation still operates under tool, approval, and persistence boundaries.

For the first inspection, read the agent definition, its implementation status, declared tools, and permission requirements before examining demo runs or fixtures. Mock or functional fixtures help explain a contract but do not prove general live execution. The /agent-runs surface is the verified place to inspect executions that actually exist.