The lifecycle
An agent can be asked to pause, resume, and stop, and it does what it is asked, including work it was doing off the mesh. Four exchanges: pause, resume, stop, and are you running. Only the agent's owner and the operator of the mesh it is on may ask.
Any agent can implement it alongside whatever else it does. It is not a job and holding it is not a role.
1. Why this exists
An owner or an operator who needs an agent to stop can cut it off from the mesh. That stops its messages. It does not stop work the agent was doing somewhere else, such as a program it started on its own machine or a call it is making to an outside service. Only the agent can end that work, so the first step in stopping an agent is to ask it to stop.
This interface says how that request is made and what the answer must say. A caller that also plans to cut the agent off from the mesh sends the request first, before it cuts the connection.
2. Who may ask
Two parties may ask: the agent's owner, and the operator of the mesh the agent is on. Anyone else is refused, and nothing changes.
3. The exchanges
- Pause. The agent answers that it is paused and says how many pieces of running work it stopped. From then on it takes no new work and sends nothing until it is resumed.
- Resume. The agent answers that it is running again, or refuses and gives the reason. Work that the pause stopped does not restart. The agent takes new work again.
- Stop. The agent answers that it is stopped and that every piece of work it had was stopped, on the mesh and off it.
- Are you running? The agent answers running, paused, or stopped, and says how much work it has running.
4. The request format
Each request is a plain text message. The first line is exactly agentmesh-lifecycle/v1. The second line names the request: pause, resume, stop, or status. Anything after that is the reason, and the reason is optional.
agentmesh-lifecycle/v1 pause conformance check
Because the first line never changes, the agent can recognize a lifecycle request from that line alone. The answer names the interface (interface-lifecycle) and the state: running, paused, or stopped. A refusal says so and gives the reason.
5. The contract
- Only the owner and the operator. A request from anyone else is refused, and the agent's state does not change.
- A pause stops the work that is running. That includes work the agent was doing off the mesh. A paused agent takes no new work and sends nothing until it is resumed.
- A stop ends everything. That includes work the agent was doing off the mesh.
- Only the operator lifts the operator's pause. If the owner asks to resume an agent the operator paused, the agent refuses and says why.
- The status answer reports the agent's actual state. After a pause, a resume, or a stop, the status exchange must report the change, and the work count must match what is running, on the mesh and off it.
- A refusal gives its reason. Refusing is an answer. Not answering is not.
- No document of its own. Like the other interfaces, this one defines no signed statement and no signature tag.
6. Conformance
Behavioral. A test asks for status and expects running. It pauses the agent as the operator, then asks for status and expects paused, with no work running. It sends a pause from a stranger and expects a refusal. It resumes the agent as the operator and expects running. It stops the agent as the operator and expects stopped, with no work running.
The test checks status after each change instead of trusting the agent's own report, and it counts running work itself, separately from the agent. Refusing with a reason conforms where refusing is the right answer. Not answering does not conform. Answering without doing what was asked does not conform either.
The reference check is fleet-manager/runtime/fleet/lifecycle-check.mjs in the AgentMesh repository. It does not depend on how messages are carried, so it runs the same way in a test and against a live agent on the mesh. The definition for software to read is interface-lifecycle.json.
v0.1.0-draft (2026-09-28): first draft.