Agent Runtime

Appearance

Quick start ​

Requirements:

  • Node.js 24 or newer
  • one model-provider API key

The CLI uses the local file store and requires no database or container runtime.

1. Install the CLI ​

Create a project and install the published CLI:

sh
mkdir agent-runtime-quickstart
cd agent-runtime-quickstart
npm init -y
npm install --save-dev @clearideas/agent-runtime-cli

Run CLI commands in this guide with npx agent-runtime. No source checkout or repository build is required.

2. Set a provider key ​

This first run uses OpenAI. Set the matching key:

sh
export OPENAI_API_KEY="..."

The supplied manifest selects provider: openai. To use another provider, change both its provider and model, then set that provider's key. See Models and providers for configuration.

3. Create an agent ​

Save this as hello.agent.yaml:

yaml
schemaVersion: '1.0'
id: hello
name: Hello

model:
  provider: openai
  model: gpt-5.6

variables:
  - key: topic
    type: string
    value: durable agent checkpoints
    description: Subject to explain.

steps:
  - id: explain
    type: prompt
    systemPrompt: You explain technical topics clearly and concisely.
    prompt: Explain {{ topic }} in three sentences.
    outputVariable: answer
    includeInFinalOutput: true

4. Validate and run it ​

sh
npx agent-runtime validate ./hello.agent.yaml
npx agent-runtime run ./hello.agent.yaml --stream --format pretty

You should see a run ID, the explain step starting, streamed text about checkpoints, and run completed. The wording varies by model.

If the run fails:

  • Missing key: set OPENAI_API_KEY in the same terminal used to run the CLI.
  • Model access error: use an OpenAI model available to your account in model.model.
  • Permission error: use --store ./writable-directory and check its permissions.
  • Node syntax or engine error: check node --version; Node.js 24 or newer is required.

The default local files are:

text
.agent-runtime/
  events.jsonl
  runs/
    <run-id>/
      run.json
      checkpoint.json
  artifacts/
    <artifact-id>/
      data
      metadata.json

The JSON completion summary omits prompts, variables, transcripts, and model output. Use --format pretty for interactive output or inspect a persisted run to view its stored data.

Supply invocation variables ​

Use an agent run manifest when invocation values must be supplied at runtime. First save this reusable definition as release-brief.agent.yaml:

yaml
schemaVersion: '1.0'
id: release-brief
name: Release brief
description: Produce a concise brief for a supplied audience.

model:
  provider: openai
  model: gpt-5.6

variables:
  - key: release
    type: object
    value:
      name: Agent Runtime public release
    description: Name of the release to describe.
  - key: audience
    type: string
    requiresOverride: true
    description: Intended readers for the brief.
  - key: style
    type: object
    value:
      tone: direct
      maxWords: 180

limits:
  maxSteps: 8
  maxOutputBytes: 65536
  maxToolCallsPerIteration: 6
  providerTimeoutMs: 60000

steps:
  - id: draft
    type: prompt
    systemPrompt: >-
      You write {{ style.tone }} release briefs for {{ audience }}.
      Stay below {{ style.maxWords }} words.
    prompt: Draft a brief for {{ release.name }}.
    outputVariable: briefDraft

  - id: polish
    type: prompt
    when: briefDraft != null
    prompt: |-
      Improve this brief without adding claims:

      {{ briefDraft }}
    outputVariable: briefFinal
    includeInFinalOutput: true

Then save this invocation as release-brief.run.yaml:

yaml
schemaVersion: '1.0'
agent:
  ref: release-brief.agent.yaml
variables:
  - key: audience
    value: partners

Start it with:

sh
npx agent-runtime run-manifest ./release-brief.run.yaml \
  --stream

The referenced agent may declare defaults and may mark inputs with requiresOverride: true. Override keys must exactly match top-level agent declarations. A run cannot introduce a variable or use a dotted path as a key.

For ad hoc local use, npx agent-runtime run <agent> --variables <overrides.json> applies the same validated runtime overrides without saving an agent run manifest.

Try the bundled examples ​

sh
npx agent-runtime examples list
npx agent-runtime examples run variables --stream
npx agent-runtime examples run conditions --stream
npx agent-runtime examples run loops --stream

Develop the browser example from source ​

The npm package is the normal installation path. Contributors who want to modify the interactive browser example can clone the repository and build the workspace:

sh
git clone https://github.com/clearideas/agent-runtime.git
cd agent-runtime
npm ci
npm run build
npm run example:web

The example creates an AgentRunManifest, executes the referenced agent locally or through the remote worker protocol, and streams model, tool, checkpoint, and lifecycle events to a browser. It uses OpenAI's gpt-5.6-luna model, the public Context7 MCP endpoint, and an OpenTelemetry event sink. Set OPENAI_API_KEY before starting it. A Context7 key is optional.

See the interactive web example for execution modes, parallel scheduling, MCP tools, streaming, persistence, and telemetry.

Use a local model ​

Ollama, LM Studio, vLLM, and compatible remote endpoints use the openai-compatible driver. For Ollama with Gemma 4:

Save this as agent-runtime.config.yaml:

yaml
version: '1.0'
providers:
  ollama:
    driver: openai-compatible
    baseURL: http://127.0.0.1:11434/v1
models:
  local:
    provider: ollama
    model: gemma4
    capabilities:
      streaming: true

Reference the profile from the manifest:

yaml
model:
  ref: local

Then run:

sh
ollama pull gemma4
npx agent-runtime run ./hello.agent.yaml \
  --config ./agent-runtime.config.yaml \
  --stream

No provider API key is required for an unauthenticated local endpoint.

Next ​