Agent

packs:agents

An agent is one registered member of the agent plane: it enrols once with a registration token, holds an agent-initiated channel open to the server, and serves its declared capabilities through that tunnel. The rows here are the operator's fleet view — registration identity, manifest facts, liveness, channel and lifecycle state; the agent wire protocol itself is separate and unchanged by these views. An agent is the logical identity — the per-project code its service account, owner, grants and recommendations attach to — and each fleet row is one of its instances: a running process with its own keypair, bound to the release it runs, labelled with the lane that routes work to it. Served by the v2 AgentService: ListAgents / GetAgent read the fleet, ListAgentInstances one agent's instances, SetAgentDraining, ForgetAgent, RevokeAgent, HaltAgent/ResumeAgentHalt, HaltAgentGroup/ResumeAgentGroupHalt and SetAgentOwner operate it, RolloverAgent / AdvanceAgentRollover / GetAgentRollover move a lane between releases, and GetAgentAssignments, GetAgentActivity, GetAgentTrustReview and GetAgentGovernanceDashboard serve the accountability views.

AgentRow

AgentRow is one row of the admin agents view: identity, project scope, manifest facts, liveness, channel and drain state.

Field	Type	Meaning
agent_version	string	The agent software's own version, as its manifest declared it.
capabilities	array of string	The capability names the manifest declares (the five minimum capabilities — healthz, readyz, info, metrics, logs — are mandatory at registration). Undeclared capabilities are never routed.
channel	string	The live channel carriage: stream (bidi stream), poll, or empty when disconnected. Estate-wide — when another replica holds the carriage, its durable channel record names it here.
code	string	The agent's per-project-unique code (lowercase, registration-validated).
drain_requested_at	timestamp	When the agent's drain was requested. Absent when not draining.
draining	boolean	Whether the agent is draining (its own flag or its group's): a draining agent keeps only its minimum-spec surfaces answering.
group	string	The runner-group name the agent registered under.
group_draining	boolean	Whether the agent's group carries a group-wide drain.
group_halted	boolean	Whether the agent's group carries a group halt.
halt_reason	string	The recorded reason for the halt in force (the agent's own, or its group's).
halted	boolean	Whether an emergency halt is in force for this agent (per-agent or via its group): channel and sessions severed, every credential refused until resumed.
halted_at	timestamp	When the per-agent halt was applied.
halted_by	string	Who applied the per-agent halt.
id	string	The fleet member id of this instance — the keypair identity the per-member verbs take.
instance_id	string	The durable instance id this row is: kept across re-enrolment and release restarts, the id ListAgentInstances and the rollover lists carry.
lane	string	The lane this instance serves: stable (the default dispatch target), shadow (receives the same dispatch as stable with every write forced to the advise tier), canary, or an operator label.
last_seen_at	timestamp	When the agent last checked in (handshake or poll); liveness is judged against this.
model_provider_code	string	The model-provider catalog entry the agent's model calls are brokered through, by catalog code (demo-anthropic): the manifest's provider reference, set from OPSCHAIN_MODEL_PROVIDER on the agent host. Exactly one entry, addressed by code and never resolved by kind — several entries of one kind coexist (different keys, regions or data-handling approvals) and the agent uses only the one it names. This is NOT disclosures.model_provider, which is the model vendor the agent discloses. Empty means no brokering (agent-host or vault-to-host custody).
model_provider_kind	string	The referenced catalog entry's kind (anthropic, openai, azure-foundry-anthropic, azure-openai, openai-compatible); empty when the agent references none or the entry is missing.
model_provider_state	string	The referenced catalog entry's standing right now: ok (exists and enabled — gateway calls are served), disabled (exists, disabled — every gateway call refuses until it is re-enabled) or missing (the catalog no longer holds the code — deleted since enrolment, or the composition has no catalog — every gateway call refuses). Resolved against the catalog on every read, never frozen at enrolment. Empty when the agent references no provider.
name	string	Display name, as the manifest declared it.
online	boolean	Whether the agent is live, judged estate-wide: not stopped, and carrying a live channel on some server replica — the replica serving the read, or another one whose durable channel record was refreshed within its two-minute freshness bound (a dropped stream and a stale record both render the agent offline immediately; a silent long-poller keeps the liveness window).
owned_by	string	The agent's owning human or team: a known user or group, manifest-declared and admin-overridable. Accountability and escalation routing only — never a privilege ceiling or floor.
project	string	The project path the agent is scoped under.
release	string	The release this instance enrolled from, as name@version; empty for an instance that declared none.
release_stage	string	The release's promotion stage as cached on the instance at enrolment — what dispatch admission reads.
spec_version	string	The Agent Interface Spec version the manifest declares.
stopped_at	timestamp	When the agent said goodbye (stopped cleanly). Absent while running.
type	string	Declared agent type (renamed class→type in an earlier release): "service" or "ai" ("ai" carries the enrolment hard dependency). Empty is untyped.

AgentDetail

AgentDetail is the admin agent detail view: the list row plus registration identity, manifest extras and host inventory.

Field	Type	Meaning
agent	AgentRow	The embedded list row (identity, scope, liveness, lifecycle state).
disclosures	AgentDisclosures	The manifest disclosure set; absent when the manifest declares none. Frozen-release disclosures render here with from_release set.
endpoint_url	string	The manifest's optional direct-dial URL. Empty when the agent is tunnel-only.
host	AgentHost	The host inventory the agent's handshake declared.
instances	array of AgentInstance	Every instance of the agent (this one included), oldest first — the view the fleet surfaces group by release and lane.
max_concurrent	integer	Concurrent proxied exchanges the agent accepts, from its manifest; 0 means the server default.
observed_remote	string	The remote address the server observed the agent connecting from.
public_key_fingerprint	string	Fingerprint of the agent's registered public key — the key itself is never rendered raw.
registered_at	timestamp	When the agent registered.
release_id	string	The signed AgentRelease the agent enrolled from, verified at registration; empty when the agent enrolled without a release. release_stage is the release's CURRENT promotion stage.
release_name	string	The enrolled release's name.
release_stage	string	The enrolled release's current promotion stage (dev, test or prod) — re-read at render time, not frozen at enrolment.
release_version	string	The enrolled release's version.
service_account_id	string	The agent's durable identity principal (cross-link into the identity surfaces); empty on compositions without an identity backend.
service_account_username	string	The service-account principal's username.
source	string	Declared source provenance from the manifest (git remote+sha or image ref+digest), for the fleet view and audit.

AgentHost

AgentHost is the agent's host inventory, as its handshake declared it.

Field	Type	Meaning
addresses	array of AgentHostAddress	The host's network addresses.
cpu_count	integer	The host's CPU count.
go_version	string	The Go runtime version the agent binary was built with.
hostname	string	The host's name.
max_parallel_steps	integer	The declared parallel-work ceiling of the host process.
pid	integer	The agent process id on its host.
runner_commit	string	The build commit of the running binary.
runner_version	string	The running binary's version.
started_at	timestamp	When the agent process started.
state_dir	string	The agent's local state directory on its host.

AgentHostAddress

AgentHostAddress is one of the agent host's addresses.

Field	Type	Meaning
ip	string	The address's IP.
mac	string	The interface's MAC address.

AgentIdentityRef

AgentIdentityRef links an agent-kind identity row to its enrolled fleet registration: the identity surfaces' pointer back into the fleet views.

Field	Type	Meaning
code	string	The enrolled agent's per-project code.
member_id	string	The fleet registry member id the identity row points at.
project	string	The project path the enrolled agent is scoped under.

AgentDisclosures

AgentDisclosures is the agent's manifest disclosure set: the declared purpose/label (any type) and, for the "ai" type, the model/adapter identification, estate tool surface and model-credential custody mode. When the agent enrolled from a signed AgentRelease whose frozen manifest carries disclosures, these are the release's frozen disclosures and from_release is true.

Field	Type	Meaning
adapter	string	Adapter/SDK identification (ai type), e.g. "opschain-claude-adapter".
adapter_version	string	The adapter/SDK's version.
custody_mode	string	Model-credential custody mode: "agent-host", "vault-to-host" or "brokered". The credential itself never appears in the manifest.
from_release	boolean	True when these are the enrolled release's frozen disclosures (the frozen set is authoritative over the live manifest's).
model_name	string	The model the agent runs against (ai type).
model_provider	string	The model vendor the agent discloses (ai type) — anthropic, openai, … — a free-text attestation of what the agent runs on. It is never the model-provider catalog code and is never resolved against the catalog: which catalog entry the agent's calls go through is AgentRow.model_provider_code.
model_version	string	The declared model version (ai type).
purpose	string	Declared purpose/label (all types): what this agent is for.
tool_surface	array of string	The estate tools the agent wields (ai type), e.g. "request_lane", "docs", "asker_reads".

AgentInstance

AgentInstance is one running process of an agent: the fleet member it holds, the release it runs with the release's stage as cached on the instance, its lane and its connectivity. Instances are enrolled by starting a process from a state directory (a second state directory with the same code is a second instance), re-bound to the same id when they re-enrol or restart from a release, and retired when their member is forgotten, revoked or replaced.

Field	Type	Meaning
code	string	The agent code the instance belongs to.
created_at	timestamp	When the instance first enrolled.
draining	boolean	Whether the instance is draining — in-flight work finishes, nothing new is dispatched (a rollover in progress, or an operator drain).
halted	boolean	Whether an emergency halt is in force for the instance (per-member or via its group, including a release revocation).
id	string	The instance's durable identity; survives re-enrolment.
key_fingerprint	string	The instance's public key fingerprint — never the key material.
lane	string	The lane the instance serves: stable, shadow, canary or an operator label.
last_seen_at	timestamp	When the instance's member last checked in.
member_id	string	The fleet member (keypair identity) the instance currently holds.
online	boolean	Whether the instance is live right now, judged estate-wide like the fleet row.
project	string	The project path the agent is scoped under.
release	string	The release the instance runs, as name@version; empty without one.
release_id	string	The release's identity.
retired_at	timestamp	Set when the instance's tenure ended (forgotten, revoked or replaced); absent while live.
stage	string	The release's promotion stage as cached on the instance at enrolment.

AgentRollover

AgentRollover is the durable state of one rollover of an agent's lane to a release: refused unless the release's stage satisfies every stage floor the agent's scopes require — the estate floor, the release_stage_floor of every environment a trust grant addressing the agent reaches, and those grants' release_stage conditions — and the release is still serving; then every targeted instance is drained, instructed to restart from the release over its own channel, and counted restarted when it re-enrols from it. replace targets every instance of the lane; canary targets canary_count first and holds for continue or abort; blue-green restarts nothing — a green lane (green_lane) is brought up on the target release beside the serving lane (the licence's agents headroom for the overlap checked first), holds green_ready at size, continue flips dispatch to it in one set-based relabel of both lanes (flipped), rollback flips back, finish drains, halts and retires the old lane's instances. On an estate carrying the approval fabric a rollover whose lane serves a governed environment (a reached environment's floor at a governed rung of the ladder; with no floor in reach, the stable lane to the ladder's top rung) lands held in the approval funnel first. Every step is attested on the release (AgentReleaseAttestation) under the rollover's one correlation chain.

Field	Type	Meaning
canaries	array of string	The instance ids rolled first under the canary strategy.
canary_count	integer	How many instances the canary strategy rolls first.
code	string	The agent code.
correlation_id	string	The one correlation chain every step, event and attestation of the rollover joins.
drain_only	boolean	True when the platform only drains and reports: the operator restarts the instances and the rollover completes on their re-enrolment.
finished_at	timestamp	When the rollover reached a terminal state.
from_release	string	The release the lane's instances ran before the rollover (name@version; empty when they ran none or disagreed).
green_lane	string	blue-green only: the lane brought up on the target release beside the serving lane (default <lane>-green). After the flip the serving lane's label names the target release's instances and this label names the old ones, kept for rollback until finish retires them.
id	string	The rollover's identity.
lane	string	The lane being rolled.
project	string	The project path.
reason	string	The requester's stated reason, or the reason the last verb carried.
requested_at	timestamp	When the rollover was requested.
requested_by	string	Who requested it.
restarted	array of string	The instance ids that have re-enrolled from the target release; under blue-green, the green instances that enrolled.
returned	array of string	The instance ids that have re-enrolled from the source release after an abort or rollback.
size	integer	blue-green only: how many green-lane instances on the target release the flip waits for (default: the serving lane's live instance count at the start).
status	string	held (in the approval funnel) | rolling | canary_held | green_ready (blue-green: the green lane is at size, waiting for continue, the flip) | flipped (blue-green: dispatch moved to the green instances; rollback flips back, finish retires the old lane) | completed | aborting | rolling_back | aborted | rolled_back | finished | rejected.
strategy	string	replace, canary or blue-green.
targets	array of string	The instance ids the rollover moves, oldest first; under blue-green, the serving lane's instances at the start — the ones finish retires.
to_release	string	The target release, as name@version.
updated_at	timestamp	When the rollover's state last moved.

AgentFleetPosture

AgentFleetPosture is the live accountability picture from the registry.

Field	Type	Meaning
agents_total	integer/string	Registered, unrevoked agents.
draining	integer/string	Agents currently draining (their own flag or their group's).
halted_now	integer/string	Agents halted now (per-agent or via their group).
online	integer/string	Agents live right now (channel-connected on any replica, per the same estate-wide verdict the fleet rows carry).
without_owner	integer/string	Agents without an owned_by owner — the accountability gap counter.

Related pages

• opschain docs agent-plane — the component page: enrolment, the channel, capabilities and the operator verbs.
• opschain docs resources/agent_release — the signed release an agent may enrol from.
• opschain docs resources/trust — the grants and assignments governing what an agent may do.
• opschain docs ai-agents — the "ai" agent type, adapters and disclosures.
• opschain docs model-providers — the catalog model_provider_code references.