SPECIFICATION · agent.v1 / agent.v2

The .agent file format

One JSON file captures everything a runtime needs to execute an AI agent. Same file runs on the cloud, on your laptop, or from a shell script. The file never contains secrets. It declares which credentials the agent needs and the runtime asks the user.

Registered IANA media typeapplication/vnd.agentmug.agent+json

Schema

The canonical JSON Schema lives at a stable URL. Validators, linters, and editor tooling can fetch it directly.

https://agentmug.com/schemas/agent.v1.json
https://agentmug.com/schemas/agent.v2.json

The written specification, referenced by the IANA registration:

https://agentmug.com/spec/agent-v1.md
https://agentmug.com/spec/agent-v2.md

Every .agent file references this URL in its $schema field. Files referencing the legacy agentlit.dahshanlabs.com URL still validate. Backwards compatibility is permanent.

v1 is permanently code-free. v2 is used only when a worker carries an explicit digest-pinned executable capability capsule. Older hosts reject v2 by schema marker; current hosts quarantine every capsule until they independently verify it and provide an isolated no-network sandbox.

What's in the file

Identity: id, name, description, version, exportedAt. Survives forks.

Blueprint: primary model, full system prompt, and the list of tools the agent is permitted to use.

Tools: four kinds: builtin (executed natively by the runtime), mcp (delegated to an MCP server with user credentials), and webhook (arbitrary HTTP), and nango (a third-party API called through a credential broker that injects the user's OAuth token). Tools that need user OAuth declare it upfront. The runtime renders a Connect button if one is missing.

Inputs and outputs: declares modalities (text / audio / image) and output shape (text / json / void). Runtimes use this to render the right UI.

Triggers: manual, schedule (cron), webhook, or api. The runtime fails loud if it can't honor a declared trigger.

Connectivity: the identities, sources, and delivery channels required for the agent to work. The contract contains roles and references, never credentials or literal phone numbers.

Sample

{
  "$schema": "https://agentmug.com/schemas/agent.v1.json",
  "id": "agent_morning_brief_01",
  "name": "Morning Brief",
  "description": "Reads overnight Outlook messages and sends a 5-bullet summary to WhatsApp every weekday at 7am.",
  "version": "1.0.0",
  "exportedAt": "2026-05-19T07:00:00Z",
  "blueprint": {
    "primaryModel": "claude-sonnet-4-6",
    "systemPrompt": "You are a morning briefing assistant ...",
    "tools": [
      "nango:outlook:list_messages",
      "twilio.send_whatsapp"
    ]
  },
  "inputs": { "accepts": ["text"] },
  "outputs": { "shape": "void", "description": "Sends the brief silently via WhatsApp." },
  "triggers": [
    {
      "type": "schedule",
      "cron": "0 7 * * 1-5",
      "prompt": "Send my morning brief.",
      "timezone": "Asia/Riyadh",
      "label": "Weekday morning brief"
    }
  ],
  "connectivity": {
    "identities": [{ "role": "owner", "channel": "phone" }],
    "reads": [{ "provider": "microsoft-outlook", "resource": "outlook-inbox" }],
    "delivers": [
      { "channel": "whatsapp", "to": "owner", "via": "twilio.send_whatsapp" }
    ]
  }
}

Implementation notes

Three runtimes ship today, all loading the same .agent file:

Cloud: the hosted runtime at agentmug.com. Tokens stored on AgentMug infrastructure.
Desktop: Tauri shell for macOS / Windows / Linux. Tokens stay on the user's laptop.
CLI: agentmug run my.agent . Invoke it from cron jobs, CI, or other agents.

The reference runtime is published on npm. Its Apache-2.0 source repository is being prepared for public release. Custom runtimes are welcome. Implement the schema above and they can run every compatible agent in the marketplace.

Versioning

The $schema URL is the version marker. A breaking format change ships as a new URL (agent.v2.json); runtimes accept the versions they know about and reject the rest with a specific error. v1 is the only published version today.