@agentmug/runtime

The portable AI agent runtime. The same .agent file runs identically in cloud, on the desktop (Tauri), from the CLI, and as a Model Context Protocol server for any compatible client (Claude Code, Cursor, Continue, Cline).

npm install @agentmug/runtime

Hello agent in 10 lines

import { quickRun, parseAgentFile } from "@agentmug/runtime";
import { readFileSync } from "node:fs";

const agentFile = parseAgentFile(JSON.parse(readFileSync("./hello.agent", "utf8")));

const result = await quickRun({
  agentFile,
  userInput: "Say hi in 5 words.",
  llm: { anthropicApiKey: process.env.ANTHROPIC_API_KEY! },
  onEvent: (e) => e.type === "token" && process.stdout.write(e.content),
});

console.log("\n→", result.totalTokens, "tokens");

That's the whole API for a quickstart. quickRun() wires in-memory persistence + tracing for you. When you need production storage, swap in runAgent() directly with your own adapters — everything below is optional power.

What you get out of the box

• Multi-LLM — Anthropic, OpenAI, Gemini. Routes by model-ID prefix (claude-sonnet-4-6, claude-opus-4-8, gpt-4o, gemini-2.0-flash). No allowlist, so newer model IDs work without a runtime upgrade. Per-model token pricing.
• Pluggable adapters — persistence, tracing, LLM, transcription, reminders, OAuth. Swap any layer.
• Streaming events — started, token, tool_start, tool_complete, paused, error, done.
• Abort + pause/resume — AbortSignal aborts mid-run (cuts the in-flight LLM stream). ask_user pauses for input; resume from a snapshot.
• Self-improving — runs carry a built-in "learn from feedback" directive so an agent can refine its own behavior over time.
• Tool registry — 25 built-in tool definitions (Gmail, Slack, GitHub, Calendar, web search/browse, image gen, code exec, memory, shell, Twilio/WhatsApp/Telegram/Discord, Sheets, etc.). Plus pluggable MCP and HTTP tools. (Executors are supplied by the host; a first-party executor bundle is rolling out.)
• MCP both ways — call out to MCP servers (LangGraph, Continue toolbox, etc.) AND be called as one (via @agentmug/mcp-bridge).
• Portable .agent files — declarative JSON spec (system prompt + tools + parameters + inputs/outputs). Version-controllable. Forkable.

The .agent file format

{
  "$schema": "https://agentmug.com/schemas/agent.v1.json",
  "id": "email-triage",
  "name": "Email Triage",
  "description": "Sorts your unread Gmail and drafts replies.",
  "emoji": "📧",
  "blueprint": {
    "primaryModel": "claude-sonnet-4-6",
    "systemPrompt": "You triage emails…",
    "tools": ["gmail.send", "memory.save", "ask_user"]
  },
  "inputs": { "accepts": ["text"] },
  "outputs": { "shape": "text" }
}

Pass it to runAgent({ agentFile, ... }) or load via parseAgentFile(json).

Adapters — the universality lever

The runtime knows nothing about where it's running. Everything that touches the outside world is an adapter:

| Adapter | What it does | Example impls | |---|---|---| | LlmClient | Sends messages, streams tokens | AnthropicLlmClient, OpenAiLlmClient, GeminiLlmClient, or write your own | | PersistenceAdapter | Creates/updates run records | Postgres (cloud), in-memory (CLI), .agent file (desktop) | | TracingAdapter | Records LLM call telemetry | Postgres, console, OpenTelemetry | | TranscriptionAdapter | Audio → text | Gemini live | | RemindersAdapter | Where reminders land | iCloud CalDAV, local .ics, Postgres |

Run identically against any combination.

Tool registry

import { InMemoryToolRegistry, gmailSendDefinition } from "@agentmug/runtime";

const tools = new InMemoryToolRegistry();
tools.register(gmailSendDefinition, new YourGmailExecutor());

Tools are normal classes implementing ToolExecutor. They receive a ToolExecutionContext with runId, userId, optional signal (for abort), and currentToolUseId (for streaming side channels).

Sister packages

• @agentmug/cli — agentmug run my.agent --input "..."
• @agentmug/mcp-bridge — expose any AgentMug agent as a Model Context Protocol tool

Status

v0.4.x — published on npm and used in production by agentmug.com. The API may still move before v1.0 based on real-world adoption. Issues + PRs welcome at the main repo.

License

MIT