What is an Agent Manifest? Specification + 5 Sample Manifests (2026)

Why a manifest at all

Agent ecosystems in 2026 are starting to look like API ecosystems in 2010 before OpenAPI: lots of capabilities, no shared way to introspect them. The hard problems are not technical (we know how to call functions); they are trust. When a delivery agent books a ride, what side-effects am I authorising? When a payment agent pushes a transfer, what is the maximum it can move without human review?

The Agent Manifest answers those questions in a structured, machine-readable way. It is to AI agents what robots.txt is to crawlers: a small file, predictable location, declarative semantics, easy to audit.

The minimum viable schema

Five top-level keys. Everything else is optional.

• agent — id, name, version, publisher. Identity.
• capabilities — array of action verbs. What the agent CAN do.
• side_effects — string label describing what permanent state changes. writes-bookings-table, append-only-write, stripe-connect-transfer, read-only.
• escalation — when does a human need to approve? Trigger thresholds and review endpoint.
• audit — where do action records go? What integrity guarantee?

Two optional but commonly used keys:

• money — does the agent move funds? Rails, max per transaction, settlement window.
• auth — is the manifest's consumer required to authenticate? With what methods?

Sample 1 — Booking agent

Books a doctor consultation on GeraClinic. Writes to a database; routes refunds and unverified-doctor cases to the GeraWitness human-in-loop reviewer.

{
  "$schema": "https://gera.os/schema/agent-manifest-v1.json",
  "agent": {
    "id": "gera-clinic-booking-agent",
    "name": "GeraClinic Booking Agent",
    "version": "1.4.0",
    "publisher": "Gera Systems Ltd"
  },
  "capabilities": [
    "book_consultation",
    "reschedule_consultation",
    "cancel_consultation"
  ],
  "side_effects": "writes-bookings-table",
  "escalation": {
    "human_in_loop_for": ["refund > 100", "consultation_with_unverified_doctor"],
    "review_endpoint": "https://gerawitness.com/api/escalation"
  },
  "audit": {
    "log_endpoint": "https://gerawitness.com/api/audit-log",
    "format": "tamper-evident-hmac-sha256"
  },
  "auth": {
    "required": true,
    "methods": ["bearer", "stripe-customer-id"]
  }
}

Sample 2 — Checkout agent

Initiates Stripe payment intents. Does NOT move funds itself (Stripe does); creates the intent. Escalates high-risk-country and high-amount transactions.

{
  "$schema": "https://gera.os/schema/agent-manifest-v1.json",
  "agent": {
    "id": "gera-checkout-agent",
    "version": "0.9.2"
  },
  "capabilities": ["initiate_checkout", "apply_coupon", "verify_address"],
  "side_effects": "creates-stripe-payment-intent",
  "money": {
    "moves_funds": false,
    "creates_payment_intent": true,
    "max_per_transaction_gbp": 5000
  },
  "escalation": {
    "human_in_loop_for": ["amount > 1000", "country_code in ['HIGH_RISK_LIST']"]
  }
}

Sample 3 — Escalation agent

Receives queued actions from other agents and decides: auto-approve under threshold, queue for human review above, hard-block for restricted categories.

{
  "$schema": "https://gera.os/schema/agent-manifest-v1.json",
  "agent": {
    "id": "gera-witness-review-agent",
    "version": "2.0.0"
  },
  "capabilities": ["receive_action", "queue_human_review", "approve_or_block"],
  "side_effects": "writes-review-decisions",
  "policy": {
    "auto_approve_threshold_gbp": 50,
    "queue_for_review_above": 50,
    "block_above": 5000,
    "block_categories": ["weapons", "controlled_substances"]
  }
}

Sample 4 — Audit recorder

Append-only event log. Issues HMAC-SHA256-signed receipts (tamper-evident, not tamper-proof — the distinction is exact: a receipt with a broken signature is detectable, but a sufficiently-resourced adversary can still rewrite history before signing). Long retention.

{
  "$schema": "https://gera.os/schema/agent-manifest-v1.json",
  "agent": {
    "id": "gera-audit-recorder",
    "version": "1.0.0"
  },
  "capabilities": ["append_event", "query_events", "issue_signed_receipt"],
  "side_effects": "append-only-write",
  "audit": {
    "tamper_resistance": "tamper-evident",
    "signature": "hmac-sha256",
    "retention_days": 2555
  },
  "money": { "moves_funds": false }
}

Sample 5 — Payment router

The most safety-critical of the five. Moves real funds via Stripe Connect transfers. Standard 2–7 day settlement window (Stripe Instant Payouts where the destination supports it). Hard cap of £25,000 per payout; first payout to a new account always escalates.

{
  "$schema": "https://gera.os/schema/agent-manifest-v1.json",
  "agent": {
    "id": "gera-payout-router",
    "version": "1.2.0"
  },
  "capabilities": ["route_payout", "select_rail", "compute_fees"],
  "side_effects": "stripe-connect-transfer",
  "money": {
    "moves_funds": true,
    "rails_supported": ["stripe-standard", "stripe-instant-where-supported"],
    "settlement_window_days": "2-7",
    "max_per_payout_gbp": 25000
  },
  "escalation": {
    "human_in_loop_for": ["amount > 5000", "first_payout_to_account"]
  },
  "auth": {
    "required": true,
    "methods": ["stripe-connect-account-id"]
  }
}

Discovery

Conventions, in order of preference:

1. /.well-known/agent.json on the root domain (HTTP standard for well-known URIs).
2. /agent-manifest.json on the root domain (simpler).
3. Registry submission to gera.os/registry/ (the GeraOS-specific surface).

Agents fetching another agent's manifest should treat it the same way browsers treat robots.txt: cache for a few hours, refresh, fail open if unreachable, fail closed if cryptographically required.

What this is NOT

The manifest is not a security boundary by itself. An agent that lies in its manifest is just lying — nothing stops it. The manifest matters because:

• It is auditable. A misalignment between manifest and behaviour is detectable.
• It is signable. The publisher can sign their manifest with a known key.
• It is composable. Other agents can decide whether to call you based on what you declare.

Real safety still comes from runtime enforcement (audit logs, escalation review, payment caps actually held in the financial layer). The manifest is the contract; the runtime is the enforcer.

Cross-product fit

GeraOS is the agent infrastructure layer behind the broader Gera ecosystem. Two siblings most relevant to the manifest pattern:

• GeraWitness — the human-in-loop review layer referenced by the escalation manifests above. Tamper-evident audit log; review queue UI; signed receipts.
• Gera Action Warranty — service guarantee that pairs with manifests. Bookings made through manifested agents qualify for action warranty receipts.

FAQ

Is the Agent Manifest the same as MCP?

No. MCP (Model Context Protocol) is a transport layer for tools and context. The Agent Manifest is a declaration format for what an agent does, what it does not do, and what guardrails apply. They compose: an agent can ship an MCP server and an Agent Manifest pointing at that MCP server.

Why declare an agent at all? Why not just expose an API?

APIs do not say what side-effects to expect, what authentication implies trust, or what categories of actions need human review. The manifest answers those: capability list, side-effect class, escalation rules, audit-log shape. It is the rules-of-engagement document, not the function call.

Where does the manifest live?

Convention: /agent-manifest.json or /.well-known/agent.json on the agent's root domain. Discoverable like robots.txt or llms.txt. The Gera ecosystem also accepts a registry-style submission to gera.os/registry/.

Is this an open standard?

The schema below is open and we encourage adoption. The specific fields used here mirror the GeraOS internal contract; we are happy for the broader ecosystem to fork it. There is no formal RFC yet — write us at agents@gera.systems if you want to coordinate.

How does this differ from OpenAPI?

OpenAPI describes endpoints. The manifest describes intent and trust. An agent can both publish an OpenAPI spec (for its tool calls) and a manifest (for what kinds of decisions the calls authorise). They answer different questions.