A standalone, provider-neutral TypeScript runtime for defining, running, and observing AI agents locally, inside an application, or on remote compute.
Agent Runtime separates portable agent manifests from execution infrastructure, so the same agent contracts can run in-process, in a child process, through a remote worker, or with host-provided adapters. Applications retain control of models, credentials, tools, persistence, compute, sandboxes, and telemetry. It is an independent open-source project licensed under Apache 2.0.
Install the standard TypeScript composition:
npm install @clearideas/agent-runtimeOr install the CLI locally and run it with npx:
npm install --save-dev @clearideas/agent-runtime-cli
npx agent-runtime examples listThe complete documentation is available at agent-runtime.clearideas.com.
- Quickstart
- Build agents
- Embed Agent Runtime
- Connections and tools
- Contract reference
- Production guide
- Versioned YAML and TypeScript agent manifests
- Sequential execution by default with optional dependency-safe prompt fan-out
- Streaming model output and ordered tool execution
- Native authorization boundaries for credentials, connections, and tools
- Native sandbox contracts for code execution and generated artifacts
- Durable checkpoints, suspension, fresh-process resume, and cancellation
- Local, child-process, and remote execution engines
- Memory, file, and SQLite run stores; JSONL and console event sinks
- Provider-neutral model, compute, sandbox, artifact, and telemetry adapters
- Privacy-conscious OpenTelemetry integration
Parallel mode is selected per agent run. It runs independent, tool-free prompt steps concurrently and commits their results in manifest order. Stateful steps, loops, and tool calls remain ordered.
For teams evaluating LangChain, LangGraph, or a custom agent harness, Agent Runtime provides a manifest-first option:
- agent behavior and run inputs use portable, versioned contracts;
- local and remote execution share the same event and checkpoint model;
- providers, persistence, compute, sandboxes, and telemetry are adapters;
- credentials and tool authorization remain host-controlled; and
- sequential execution, dependency-safe parallel steps, loops, conditions, approvals, and resumable runs use one runtime.
Applications can embed the TypeScript API, invoke the CLI, or implement the remote execution protocol without changing their agent manifests.
| Path | Purpose |
|---|---|
packages/agent-runtime |
Primary @clearideas/agent-runtime entry point |
packages/contracts |
Versioned manifests, events, checkpoints, and schemas |
packages/core |
Deterministic execution engine and host ports |
packages/runtime |
Provider, model, connection, and secret configuration |
packages/cli |
agent-runtime command-line interface |
packages/step-* |
Prompt, loop, approval, webhook, code, and sub-run executors |
packages/store-* |
Local and SQLite persistence adapters |
packages/execution* |
Execution contracts, engines, and compute adapters |
packages/sandbox* |
Sandbox contracts and provider adapters |
packages/artifacts |
Sandboxed artifact generation |
packages/telemetry-otel |
OpenTelemetry event sink |
docs |
VitePress documentation |
examples |
Manifests and runnable integrations |
Requirements:
- Node.js 24 or newer
- npm 11
npm ci
npm run validateUseful focused commands:
npm run build
npm test
npm run check:boundaries
npm run check:docs
npm run check:tarballsThese commands are for contributors developing Agent Runtime itself. Users of the public packages can start with the quickstart, then see concepts, embedding, and production guidance.
Agent Runtime packages adapters separately from the core contracts. Install only the integrations used by the host application.
| Capability | Included implementations |
|---|---|
| Models | AI SDK provider adapter |
| Persistence | memory, files, and SQLite |
| Event sinks | JSONL and console |
| Conditions | JEXL |
| Remote compute | Modal |
| Sandboxes | Docker and Modal |
| Telemetry | OpenTelemetry |
See the adapter catalog for package names and integration guidance.
Package changes use Changesets:
npm run changeset
npm run version-packagesThe release workflow is manually dispatched, gated by the repository variable
NPM_RELEASES_ENABLED=true, and protected by the npm-production GitHub
environment. npm trusted publishing uses GitHub OIDC, so publishing does not
require a long-lived npm token.
All publishable packages use the @clearideas scope and explicitly target the
npm registry. The repository .npmrc, each package's publishConfig,
Changesets, and the release workflow all resolve or publish these packages
through https://registry.npmjs.org/ with public access and npm provenance. No
Agent Runtime package is configured for GitHub Packages.
The same workflow builds the VitePress documentation before publishing and deploys it to a private S3 origin behind CloudFront at agent-runtime.clearideas.com after a successful npm publish or when documentation deployment is explicitly requested. The deployment job uses GitHub OIDC to assume a repository-scoped AWS role. It does not store long-lived AWS credentials in GitHub.
Run npm run release:check to validate the complete package set without
publishing. Official releases are produced only by the protected GitHub
workflow.
Agent Runtime is licensed under the Apache License 2.0. See LICENSE.
Copyright 2026 Clear Ideas Incorporated. Clear Ideas is a trademark of Clear Ideas Incorporated. See TRADEMARKS.md.