Runtime State
Forge treats agent state as part of the runtime contract. A caller should be able to tell whether an agent is starting, ready, doing work, paused, degraded, or stopped without parsing provider-specific logs.
Lifecycle model
The ANVIL lifecycle contract uses six stable states:
| State | Meaning |
|---|---|
Init |
Runtime has been constructed but is not ready to accept work. |
Ready |
Agent can accept a run request. |
Running |
Agent is executing a model call, tool call, workflow, or delegation. |
Paused |
Execution is intentionally suspended and can resume. |
Error |
Runtime reached a recoverable or terminal fault state. |
Terminated |
Runtime has shut down and cannot be reused. |
Language SDKs may expose idiomatic enum names, but they should preserve this state machine and reject invalid transitions.
Health profile
forge-health tracks operational signals around the lifecycle:
- uptime
- latency
- error rate
- tool success rate
- resource usage
- degradation thresholds
Health is not only a dashboard concern. It feeds signed runtime attestations, release-gate checks, and downstream orchestration decisions.
Events and observers
The agent runtime emits typed events so user interfaces and operators can follow execution without scraping text output.
| Surface | Purpose |
|---|---|
AgentEvent |
High-level lifecycle, message, and tool events. |
ToolInvocationRecord |
Tool name, invocation id, status, duration, and result metadata. |
AgentLoopObserver |
Hook point for monitoring, audit trails, UIs, and tests. |
See Agent events and Observers for the event taxonomy and observer API.
What to use it for
Use runtime state when you need:
- a UI progress stream
- a durable workflow checkpoint
- an audit entry tied to an agent DID
- a release-gate assertion that a workflow actually finished
- operational alerts for repeated tool or provider failures
Runtime state is also the place where Forge avoids silent success. A finished agent run should include enough structured status for a caller to distinguish a clean completion from a partial or degraded one.