Built-in Runtime Adapter

Built-in Runtime Adapter

When you use Governance + Managed Execution, Clasper Core runs LLM execution via its built-in runtime adapter. Your backend sends a message; Clasper Core runs governance, calls the LLM once, records the trace, and posts the reply back to your Control Plane. OS, browser, and data actions stay in your backend.

This document describes what the runtime adapter is, when to use it, how to call it, and how it fits with your backend.

What it is

The built-in runtime adapter is in-process code inside Clasper Core — not a separate service or “agent harness.” For each request it:

1. Governance — Evaluates whether execution is allowed (RBAC, risk, budgets, policies). If denied, no LLM is called.
2. One LLM turn — Builds the system prompt from your workspace (SOUL, AGENTS.md, skills), calls the configured LLM provider, and returns the model response.
3. Observability — Builds a trace and ingests trace, cost, and metrics for the Ops Console and APIs.
4. Control Plane callback — Posts the agent reply (and optional plan document) to your backend via the Control Plane Contract.

The adapter is stateless and single-turn: one request in, one reply out. It does not run tools, multi-step loops, or OS/browser actions; those remain in your backend.

When to use it

Use the built-in runtime when you want Governance + Managed Execution:

• You want Clasper Core to run the LLM (one place for governance and model calls).
• Your backend stays the source of truth for tasks, messages, and documents.
• OS, browser, and data actions are handled by your backend or your own tool endpoints.

Use Governance-only instead when execution runs in your existing runtime or in external adapters that request permission from Clasper Core and ingest telemetry. See Integration for both profiles.

Other runtime adapters (external)

Yes — other runtime adapters can be used besides the built-in one. Clasper Core treats execution as pluggable:

• Built-in runtime adapter (this document): runs inside Clasper Core. You call POST /api/agents/send; Clasper Core runs governance, one LLM turn, and posts the reply back. Best when you want one place for governance and LLM execution.
• External execution adapters: run outside Clasper Core (your own service, OpenClaw, Playwright, custom runners). They request permission from Clasper Core (POST /api/execution/request), execute in their own environment within the granted scope, then ingest telemetry back (POST /api/ingest/trace, cost, metrics). Clasper Core never runs their code — it only decides and records.

You can use the built-in adapter only, external adapters only (Governance-only), or both (e.g. built-in for simple LLM flows, external for tools/OS/browser). Governance (RBAC, risk, budgets, traces, audit) applies to all adapters. For how external adapters integrate, see the Adapter Contract.

Endpoints

Endpoint	Mode	Description
POST /api/agents/send	Request/response	Synchronous execution. Returns when the LLM reply is ready and posted to your backend.
POST /api/agents/stream	Streaming (SSE)	Real-time streaming response. Use when you need incremental output.

For POST /api/agents/send you can set "stream": true in the body to get streaming behavior on the same endpoint.

Request format (send)

Your backend (or a trusted client) calls Clasper Core with:

{
  "user_id": "<tenant user id>",
  "session_key": "user:<user_id>:<role>",
  "message": "User's message text",
  "task_id": "<optional; resolved from task_title or default if omitted>",
  "task_title": "<optional; used to find or create a task>",
  "task_description": "<optional>",
  "task_metadata": "<optional>",
  "messages": [],
  "metadata": {},
  "stream": false,
  "webhook": null
}

• user_id — Tenant scope. Must match the user_id encoded in session_key.
• session_key — Identifies the agent session (e.g. user:user-123:jarvis). Clasper Core uses this to select the persona (e.g. souls/jarvis.md) and to mint the agent JWT when calling your backend.
• message — The user message for this turn.
• task_id — If provided, the reply is posted to this task. If omitted, Clasper Core resolves a task by task_title or CLASPER_DEFAULT_TASK, or creates one.
• task_title / task_description / task_metadata — Used when no task_id is provided (find or create task).
• messages — Optional conversation history for context.
• metadata — Optional; can include workspace_id, system_prompt override, kickoff_plan, kickoff_note, and other hints.
• stream — If true, response is streamed (SSE) and the reply may still be posted to your backend when complete.
• webhook — Optional; Clasper Core can POST a completion payload to a URL you specify.

Authentication: if AGENT_DAEMON_KEY (or equivalent) is set, the request must include header X-Agent-Daemon-Key with that value.

Response (send, non-streaming)

On success you receive something like:

{
  "status": "ok",
  "task_id": "<uuid>",
  "trace_id": "<uuid>",
  "execution_id": "<uuid>",
  "response": "Agent's reply text",
  "usage": { "prompt_tokens": 120, "completion_tokens": 80, "total_tokens": 200 },
  "cost": { "model": "gpt-4o-mini", "totalCost": 0.001, "currency": "USD" }
}

Optional: context_warning when prompt usage is high relative to the model’s context window.

The agent reply is also posted to your Control Plane (e.g. POST /api/mission-control/messages) so your backend has a durable record.

What the adapter does and does not do

It does:

• Enforce governance (policy, risk, budgets) before running.
• Load workspace config (SOUL, AGENTS.md, skills, memory) and build the system prompt.
• Call the configured LLM provider once per request.
• Record trace, cost, and metrics.
• Post the reply (and optional plan document) to your backend using the Control Plane Contract.

It does not:

• Run tools, OS commands, or browser automation (those stay in your backend).
• Run multi-step agent loops or custom “harnesses” — it is single-turn.
• Persist sessions; it is stateless.

Configuration

Key environment variables when using the built-in runtime:

Variable	Purpose
BACKEND_URL	Your backend base URL. Clasper Core calls this to post messages and documents (Control Plane).
AGENT_JWT_SECRET	Shared with your backend. Clasper Core mints agent JWTs so your backend can authorize Control Plane calls.
CLASPER_WORKSPACE	Path to the workspace directory (SOUL, AGENTS.md, souls, skills).
CLASPER_DEFAULT_TASK	Default task title when no task_id or task_title is provided.
LLM_PROVIDER / LLM_MODEL_DEFAULT	LLM provider and model (e.g. OpenAI, Anthropic).
AGENT_DAEMON_KEY	Optional; if set, callers must send X-Agent-Daemon-Key to use the agent API.

See Configuration for the full reference.

Flow with your backend

Your backend                          Clasper Core
     │                                    │
     │  POST /api/agents/send             │
     │  (user_id, session_key, message,   │
     │   task_id, metadata)              │
     │ ─────────────────────────────────▶│
     │                                    │  1. Governance check
     │                                    │  2. Build prompt from workspace
     │                                    │  3. Call LLM
     │                                    │  4. Ingest trace/cost/metrics
     │                                    │  5. POST message (and optional doc)
     │                                    │     to BACKEND_URL (X-Agent-Token)
     │  ◀─────────────────────────────────│
     │  { response, trace_id, usage,      │
     │    cost, task_id }                 │

Your backend stores the user message in your own database before or after calling Clasper Core; Clasper Core posts the agent reply to your Control Plane so the full thread lives in your system.

Related

• Integration — Governance-only vs Governance + built-in runtime
• Adapter Contract — External execution adapters (request permission + ingest)
• Control Plane Contract — Backend API Clasper Core calls
• Getting Started — Quickstart with the built-in runtime
• Architecture — Core vs adapters, deployment profiles
• API Reference — Full endpoint details