12.1 What an agent is; the two kinds

Included from Basic tierpacks:agentspacks:ai-agents

After this you can: explain what an enrolled agent is, tell a Basic Agent from an AI Agent, and name what either may do once enrolled.

Before you start — tick each one:

• Lesson 12.0 — Meet Felix (opschain learn 12.0)

In the GUI: Operations → Agents shows the fleet, one row per running instance; an agent's sheet shows its declared type among the manifest disclosures.

Everything before this module was driven by people. Felix is driven by code. This lesson is the one definition the rest of the module builds on: what an agent is on this platform, the two kinds it comes in, and the rule that governs both — capability is granted, never assumed. You read the fleet with a server target and a superuser login (lesson 0.1); the agents surface itself needs the packs:agents entitlement, and the AI kind additionally packs:agent-governance and packs:ai-agents.

1. What an agent is

An agent is a long-running, customer-authored operator process enrolled with the platform. Four facts define it:

• It has its own identity. Enrolment registers an Ed25519 keypair and mints a durable service-account principal — svc-agent-limebank-felix for Felix — that policy assignments can address like any principal but that can never start an interactive session or mint an API key. The identity screens badge it agent.
• It connects outbound only. The agent holds a channel open to the server and serves its capabilities through that tunnel; it binds no listener and needs one egress and one credential. The server materialises what it serves under /api/projects/limebank/agents/felix/… — the ordinary API, under ordinary caller authorisation, where a denied surface answers 404.
• It acts under the same machinery as a person. Every call it makes to the platform runs under its service account through the same authorisation engine, the same approval funnel and the same audit trail you met in lessons 7.1 and 10.1 — and the server writes the audit event, never the agent.
• It carries one layer people do not: trust. A trust grant is the explicit, bounded statement of how autonomous the agent may be, where. Without a matching grant a request for work is refused.

One agent may run as several instances — each process a fleet member with its own keypair, bound to the release it runs and labelled with a lane. opschain admin agents list prints one row per instance; the code names the agent they all belong to. Lesson 12.4 is where that matters.

2. The two kinds

The manifest an agent declares at enrolment carries a type, and the type is attested, not self-described:

• A Basic Agent — type service — is deterministic automation: a monitor that watches for tickets and acts on business rules, a patcher that runs a known sequence, a process whose behaviour is exactly its code. It implements the subset of the agent specification its job needs — typically no chat surface and no AI disclosures. Enrolling it needs packs:agents, and the licence's agents limit bounds how many instances may be connected at once.
• An AI Agent — type ai — reasons against a language model, so its behaviour is a conversation, not a script. It implements the full specification: the chat surface, the attested disclosures (model, adapter, tool surface, credential custody), and adapter-transit transcripts of every model interaction. Its model credential lives in brokered custody by default — no model key on the agent host; the platform's model gateway injects the stored key server-side (lesson 12.6). Enrolling it additionally needs packs:agent-governance and packs:ai-agents, and the ai type ships with a SUPERVISED trust ceiling: unattended AI mutation of an estate is an explicit, evidenced raise, never a default.

Registration validates the manifest against the declared type: an ai manifest missing a required disclosure refuses by name, and a service manifest declaring AI-only disclosures refuses as a type contradiction — both land the audited warn:agent:type_attestation_refused event. The split is a convention, not a cage: a service agent may declare a chat surface (a deterministic responder answering from fixed rules); chat is simply characteristic of AI Agents.

Read the kind off the fleet:

opschain admin agents list --project limebank
opschain admin agent show felix

The list's rows carry the ID every opschain admin agent verb takes; show prints the TYPE row (service, ai, or - for an instance that declared no type), the OWNED BY row, the SERVICE ACCOUNT row and — for an AI Agent — the PURPOSE, MODEL, ADAPTER, TOOL SURFACE and CUSTODY disclosures a third-party risk review asks for. Felix walks the module as a service agent and takes the ai job in lesson 12.6.

3. What an agent may do

Enrolled is not empowered. A freshly enrolled Felix can serve its own surfaces and nothing else; capability arrives in explicit, audited steps that lesson 12.2 walks:

• An assignment stakes out the subtree the agent manages and confers only the configured floor — advise by default.
• A trust grant is subtree-scoped, action-patterned and tiered: advise (recommend only), supervised (its changes gate in the approval funnel) or autonomous (runs unattended within scope), with rate, budget and token caps.
• Ceilings cap what any grant may say — per type (ai at supervised) and per node classification — so the effective tier is the minimum of grant, type ceiling and every matching node ceiling.
• Lifecycle control is immediate and layered: drain, halt, revoke, forget, and the platform-wide halt of the agent plane. The kill switches are base platform, deliberately not behind any pack (lesson 12.5).

Every action lands in the events feed and audit history under the agent's own identity, and the history outlives the agent: a revoked or forgotten agent's activity timeline still answers by member id, marked departed (lesson 12.3). The platform reference for all of it is opschain docs agent-plane; the entitlement lines are opschain docs packs-agents and opschain docs packs-agent-governance.

Check yourself

• Which kind brokers model credentials through the server, and which entitlements does each kind need to enrol?

What you learned

• An agent is a customer-authored process with its own keypair and service account, connected outbound, acting under the same authorisation, approval and audit as a person — plus trust.
• Two kinds, by attested manifest type: service (deterministic, packs:agents) and ai (model-driven, disclosed, brokered, packs:agent-governance + packs:ai-agents, ceilinged at SUPERVISED).
• Capability is granted, never assumed: assignment, tiered grant, ceilings — and the kill switches are base.
• opschain admin agent show felix is the one command that tells you what Felix is.

Next: lesson 12.2 — Enrol, own, assign, grant, ceiling (opschain learn 12.2), or back to your track (opschain learn).