@clearideas/agent-runtime

The standalone TypeScript runtime for portable, declarative agents. Run agents locally, inside an application, or through a remote execution engine while retaining control of providers, credentials, tools, state, and compute.

Documentation · GitHub repository

Install

npm install @clearideas/agent-runtime

Requires Node.js 24 or newer.

Minimal TypeScript host

Set OPENAI_API_KEY, save this as agent.ts, and run node agent.ts:

import { createAgentRuntime, defineAgent } from "@clearideas/agent-runtime";
const manifest = defineAgent({
  schemaVersion: "1.0",
  model: { provider: "openai", model: "gpt-5.6" },
  steps: [
    {
      id: "hello",
      type: "prompt",
      prompt: "Explain checkpoints in one sentence.",
      includeInFinalOutput: true,
    },
  ],
});
console.log((await createAgentRuntime({ manifest }).run({})).output);

The default store is in memory. Pass a durable runStore to recover across processes. See embedding for adapter overrides, resource ownership, and installing individual packages.

What is included

The package exports the standard Agent Runtime composition:

• versioned Agent Manifest and Agent Run Manifest contracts;
• the execution core, checkpoints, resume, cancellation, and ordered events;
• model profiles and AI SDK model-provider configuration;
• MCP connections with credential references, connection modes, tool allowlists, and host authorization hooks;
• prompt, loop, approval, webhook, code, and sub-run step contracts and executors;
• local persistence and local or remote execution interfaces.

Authorization policy and sandbox contracts are native runtime capabilities. Concrete compute, sandbox, persistence, artifact, and telemetry providers are available as separate @clearideas/agent-runtime-* packages so applications install only the infrastructure they use. The project includes Docker and Modal sandbox providers, SQLite persistence, generated-file handling, Modal compute, and OpenTelemetry.

Dependency-aware graph execution

Watch the 27-second manifest graph execution demonstration.

At run time, Agent Runtime resolves manifest variable reads and outputs into a dependency-aware execution plan. Parallel mode concurrently schedules eligible independent prompt branches, keeps dependent and effectful work ordered, and commits results in manifest order. This preserves deterministic orchestration while substantially reducing elapsed time for agents with enough independent work.

Use the CLI

For a first local run:

npm install --save-dev @clearideas/agent-runtime-cli
npx agent-runtime examples list
npx agent-runtime examples run variables --stream

The CLI persists runs and events locally by default.

Documentation

The complete guides and reference are available at agent-runtime.clearideas.com.

• Quickstart
• Build agents
• Embed Agent Runtime
• Connections and tools
• Adapter catalog
• Contract reference
• Production guide

Licensed under the Apache License 2.0.