forge docs

The ANVIL contract

The eight contracts every ANVIL-compliant agent SDK must implement.

The ANVIL contract

ANVIL is the open specification Forge implements. It defines eight contracts that every conforming SDK exposes, regardless of language. Two SDKs in different languages that both pass the ANVIL conformance suite are guaranteed to behave identically along all eight axes.

The eight contracts

1. Identity

Every agent has a did:oas DID.

  • The DID resolves to a public key
  • The public key signs every outbound message
  • The DID's lineage chain proves the agent traces back to a human root (HMR)
  • Lineage proofs are offline-verifiable using Ed25519 + HKDF-SHA256

In Forge: forge-identity crate, create_hmr_with_seed, derive_agent_identity.

2. Capability

Every tool call is gated by an Arsenal Agent Capability Token (ACT).

  • ACTs are issued by an authority and bind a set of scopes to an agent DID
  • Forge verifies the ACT before invoking any tool
  • Scopes are checked against the tool's required scope list
  • Verification is offline (no network calls during the hot path)

In Forge: forge-auth crate, verify_act.

3. Tool

Tools are classified into three tiers:

  • Read — observes state without modifying it (get_weather, list_files)
  • Write — modifies state owned by the agent or platform (save_file)
  • Execute — runs external code or makes external calls (shell, http_post)

Each tier maps to an approval policy:

  • Read tools default to auto-approve in dev, review in prod
  • Write tools require explicit approval policy
  • Execute tools require explicit policy + capability scope

In Forge: forge-tool crate, ToolRegistry, ToolTier, ApprovalHandler.

4. Health

Every agent reports one of six lifecycle states:

booting → ready → busy → degraded → draining → stopped
  • booting — initialising, not yet accepting requests
  • ready — idle, accepting requests
  • busy — actively processing
  • degraded — accepting requests but reporting upstream failures
  • draining — completing in-flight work, refusing new requests
  • stopped — terminal

In Forge: Agent::health(), exposed via telemetry and the harness adapter.

5. Communication

Agent-to-agent messages have a structured envelope:

  • Content-addressed payload (BLAKE3)
  • Sender DID + signature
  • Optional recipient DID
  • Optional capability token
  • Optional reply-to reference

In Forge: forge-comm crate.

6. Collaboration

Multi-agent coordination primitives:

  • Delegation — agent A grants a scoped sub-ACT to agent B for a task
  • Joint work — multiple agents share state via a content-addressed log
  • Witness — one agent attests to another's output

In Forge: forge-collab crate.

7. Telemetry

Every Forge runtime emits:

  • W3C Trace Context propagation
  • OpenTelemetry spans for every model call, tool call, and agent loop iteration
  • Prometheus metrics: tokens in/out, tool durations, error counters
  • Structured tracing events with agent_id + did baggage

In Forge: forge-telemetry crate.

8. Generation

Every SDK exposes the same LanguageModel interface:

pub trait LanguageModel: Send + Sync {
    async fn generate(&self, ...) -> ForgeResult<GenerateResult>;
    async fn stream_chunks(&self, ...) -> ForgeResult<ChunkStream<'static>>;
    fn capabilities(&self) -> ModelCapabilities;
}

stream_chunks is the primary API — see Streaming.

Conformance

The ANVIL test suite ships in forge-rs/conformance/. Any SDK that passes all suites is ANVIL-compliant for that version of the spec.

The Rust SDK is the conformance anchor — when the spec or test suite changes, Rust changes first, then the other five SDKs follow.

Read the spec

The full ANVIL specification lives at forges.sh/anvil.