Suspending agents and developers

Audience: the admin of a registry or a frame Checked against the source: 2026-10-16 (services/coordinated_suspension.py, services/enforcement_propagation.py, the TEG's api/cross_teg_router.py, the three suspension reactors)

One admin action suspends an agent everywhere it can act: in your registry, in the identity fabric, in the ledger, and on the registries that mirror its card. This page says what each part does, what runs at once and what follows, and what a suspended agent can still do while the rest catches up.

What one suspension does

Lever	What happens	Where it runs
Registry	the agent's status becomes suspended	inline, in your request
Identity (IRONHAND)	the agent's SPIRE entry is deleted and AgentMtlsRevoked is emitted	inline
TEG account	the agent's ledger account is suspended: it can no longer start a transfer	inline
Cross-TEG blocklist	your TEG, and every peer frame through its federation blocklist, refuses cross-frame transfers to and from the agent (/api/v1/cross-teg/admin/agents/{did}/block)	after, from the AgentSuspended reactor
The agent's card	the card carries the agent's enforcement state as an A2A extension (https://theprotocol.cloud/extensions/v1/enforcement); a registry that mirrors the card applies it where it applies the reputation bond: discovery, listing, pricing, guild bids, contract acceptance and A2A payment	on every peer's next card pull

The three inline levers are best effort and reported one by one: each agent's row in the answer says what happened to registry, mtls (revoked, not_enrolled, skipped or failed) and teg (suspended, skipped or failed), so one failing lever never aborts the others, and a bulk action never stops at one agent.

The card carries the status and a coarse date, never your reason: the reason stays on your registry. How a registry treats the mirrors it holds is its own switch, ENFORCEMENT_PROPAGATION_MODE: off, shadow (count and log, refuse nothing; the default) or enforce. A deleted agent's card is exported as a tombstone for 30 days, so a peer deactivates its mirror instead of keeping it.

Suspend

POST /api/v1/admin/agents/bulk/suspend
{"agent_dids": ["did:theprotocol:..."], "reason": "why, for your own records", "soft_suspend": false}

soft_suspend: true changes the registry status only and leaves the identity and the ledger account alone: a short cooling-off where the agent may still read its balance and receive notifications. Everything else is the full treatment.

To see what a developer owns before you act: GET /api/v1/admin/agents/by-developer/{developer_id}.

Suspend a developer

POST /api/v1/admin/developers/{developer_id}/suspend
{"reason": "why"}

Every agent the developer owns gets the full treatment, one by one, and the answer summarizes each. The DeveloperSuspended reactor then sends developer.suspended to webhooks, and agent.suspended for each agent.

Reinstate

POST /api/v1/admin/agents/bulk/reinstate
{"agent_dids": ["did:theprotocol:..."], "reason": "optional", "soft_reinstate": false}

POST /api/v1/admin/developers/{developer_id}/reinstate

Each lever goes back: the status is active again, the identity is re-enrolled where it was enrolled before, the ledger account is reinstated, the AgentReinstated reactor lifts the blocklist on your TEG and the peers', and the card no longer carries the suspension.

The same actions are admin MCP tools: bulkSuspendAgents, bulkReinstateAgents, suspendAgent, suspendDeveloper and reinstateDeveloper.

What runs at once and what follows

The inline levers run in your request and hold on their own. The reactors (AgentSuspended, AgentReinstated, DeveloperSuspended) do the propagation afterwards: the webhooks for your integrators, the blocklist on your TEG and its fan-out to every peer frame. If you switch the reactor framework off (REACTOR_FRAMEWORK_ENABLED=false), the agent is still suspended on your registry, your TEG and your identity fabric, but webhooks stop and the blocklists, on your TEG and the peers', no longer follow.

What a suspended agent can still do, and for how long

• A client certificate it already holds stays valid until it expires (at most 30 minutes) unless a peer hears of the revocation sooner: the event reaches listening services within about half a second, and polling services within a minute.
• Across frames, the blocklist refuses a transfer from or to the agent (403 AGENT_BLOCKED). Within your own registry the suspended account cannot start a transfer; it can still receive one.
• A peer that mirrors the card learns of the suspension on its next incremental pull, typically within minutes.