The runtime that executes every AI actor
A model gives you language. It can't, on its own, reliably ground itself in your real data, pick the right tool and call it correctly, recover when a call fails, carry a multi-step task through to completion, or leave behind a trajectory you can replay. The Socialhub Harness is the enterprise agent runtime that does all of that — the execution engine that turns a capable model into a dependable agent.
Every AI actor in Flash — the Marketing, Loyalty and Risk managers, the member concierge, and every behind-the-scenes generator — is an Agent Definition: a structured blueprint (model routing, context sources, skills, tools each with a scope, an MCP surface, workflow, memory and a loop policy) that thisruntime executes. And because every actor runs through one runtime, governance isn't a separate product — it's a structural property of unified execution: a model gives language; a runtime gives action; a unified runtime gives governance for free.
This reference is the developer's view of that runtime — what it does at execution time, the Definition type it executes and its axes, how skills compose into executed steps, the reproducible trajectory each run emits into the event log, and the guards that fall out of running everything in one place. For the business overview see the Socialhub Harness product page.
What the runtime does at execution time
Start here, because this is the point of the whole system. When a run begins, the Harness runtime does the work a language model can't do for itself — the five things below, in order — and the result is a task carried to completion and a trajectory you can replay.
1 · Context assemblyThe runtime grounds the actor: it assembles the brief and the real business facts — task, member/segment rollups, brand kit, metrics — per run, PII-minimized. The model never guesses at your data; it is handed it.
2 · Model routingThe runtime resolves which reasoning engine executes each step, with fallbacks, from what the Definition names. Routing is the runtime's job, not the prompt's.
3 · Skill composition into stepsThe runtime injects the composed skills' ordered steps and decision guidance into the prompt, so what executes is a named, versioned procedure — not whatever the model improvised.
4 · The tool loopThe runtime drives the select-call-observe loop: it picks a governed tool, checks permission, calls it, reads the result, and recovers or escalates on failure — the reliability a bare model call lacks.
5 · A reproducible trajectoryEvery step is emitted, in order, into the append-only event log — stamped with a run ID and the exact blueprint version — so the run is auditable and replayable step by step.
A model gives language; a runtime gives action; a unified runtime gives governance for free. Everything below — the Definition the runtime executes, how skills compose, the event log it produces, and the guards that hold — follows from these five steps running in one place for every actor.
Anatomy of an Agent Definition — what the runtime executes
The runtime executes a Definition: a structured blueprint — not code, not a free-form prompt — that composes the parts below. Editing any of them produces a new versioned blueprint the runtime picks up on the next run; the version is stamped onto every event that run emits.
| Blueprint part | What it composes |
|---|---|
| model routing | Which reasoning engine executes each step — and the fallbacks. It names the model; the runtime resolves it. |
| context sources | The brief and business facts the actor starts from — task, member/segment rollups, brand kit, metrics — assembled per run, PII-minimized. |
| skills | The structured playbooks composed onto the actor (see below). Named procedures, not free-form prompting. |
| tools | The governed actions the actor may take — each with a scope. The Definition names a tool; it never grants it. The database is the authority. |
| MCP surface | Which tools are exposed over the Model Context Protocol for an external agent holding a scoped key, and under which gears. |
| workflow | The ordered steps or graph the runtime drives — claim, read, decide, act, complete — for worklist and orchestrated actors. |
| memory | What the actor may carry across steps and runs, and what it must re-read fresh each time. Bounded, not a scratch pad for PII. |
| loop policy | The stopping rule: max steps, budget ceiling, and the escalate-to-human condition. The runtime enforces it; the actor cannot extend it. |
It names capability; it never grants it. A Definition can reference a tool, a model or a data source, but whether this workspace and this key may actually use it is resolved by the runtime against the database at call time. The blueprint is the composition surface; because the runtime resolves authority in one place, the guards below hold for free.
One Definition type, described across three axes
There is a single Definitiontype for every actor. It doesn't fork per persona — it is described along orthogonal axes, so the same runtime, event log and guards apply whether the actor is an external agent, an in-Flash loop, or a single-shot generator.
| Axis | Values | What it captures |
|---|---|---|
| runtimeForm | mcp_external · server_orchestrator · inline_function | HOW the definition executes. mcp_external = an external agent holding a scoped key, calling in over MCP. server_orchestrator = an in-Flash loop the runtime drives step by step. inline_function = a single-shot generator invoked in the flow of a screen. |
| agentType | employee · chatbot · function | WHAT it is to the business. employee = a named worker you manage (goals, tasks, feedback). chatbot = a conversational surface grounded in real data. function = a single-purpose generator or classifier with no persona. |
| technical kind | agent · generator · embedded · custom · workflow | The engineering classification of the blueprint — a composed multi-step agent, an inline generator, an embedded capability, a workspace-custom definition, or a multi-step workflow graph. |
| business domain | one of 8 domains (right) | WHICH part of the business it serves: Marketing & Campaign, Loyalty & Retention, Risk & Compliance, Member Service, Content & Creative, Customer Intelligence, Analytics & Insights, Research & Simulation. |
40+ governed actors, one model. The live roster is 5 composed agents (multi-step, server-orchestrated: the four managers plus the member concierge), 28 inline functions (single-shot generators and classifiers threaded through the product), and 8 embedded capabilities (in-flow helpers on a screen). Every one of them is the same Definition type, differing only along the axes above.
Skills: database-authoritative playbooks composed onto an agent
A skill is a structured playbook, stored in the database and composed onto an agent's blueprint the way you'd hand a new hire an SOP. It is not a paragraph of prompt text — it is a typed record with the following parts:
triggerThe condition under which this skill applies to the current run.
required stateThe member/business state that must be present for the skill to run responsibly — absent, it fails closed to a person.
tool allowlistThe subset of the agent's tools this skill may use — a narrowing, never a widening, of what the blueprint already permits.
ordered stepsThe procedure the runtime walks, in order.
verifier rulesThe checks that must pass on the result before the step is considered done.
decision guidanceHow to choose — including when to HOLD or escalate — expressed as guidance, not a hard-coded branch.
At run time the runtime injects the skill's steps and decision guidance into the prompt— so what executes isn't “whatever the model came up with,” but a named, versioned procedure your team can read and approve. Because skills are database-authoritative, the same skill can be composed onto more than one agent, and changing it changes every agent that uses it — no redeploy.
The runtime's output: a reproducible trajectory
Producing a replayable trajectory is step 5 of what the runtime does — and it's also your audit evidence. Whatever the actor and however it runs, every run emits a stream of events into a single append-only event log. Each event is stamped with a run ID and the exact blueprint (definition) version that produced it — so a run is auditable and replayable. The ordered event types a run emits:
Alongside these, the log carries the mirrored MCP tool calls (when the actor drives Flash over MCP) and the closing business outcome — so the trajectory, from intent to result, lives in one place.
// one run's trajectory (abbreviated — every event carries runId + definitionVersion)
{
"runId": "run_a1f9…",
"definition": "loyalty-manager",
"definitionVersion": 4,
"events": [
{ "type": "run_started", "at": "2026-08-26T09:14:02Z" },
{ "type": "user_intent", "intent": "work the win-back worklist" },
{ "type": "context_loaded", "sources": ["task", "member_rollup", "churn_signal"] },
{ "type": "model_selected", "model": "…" },
{ "type": "prompt_assembled","skill": "winback-worklist-execution" },
{ "type": "reasoning", "summary": "high value, at-risk, consented" },
{ "type": "permission_check","tool": "issue_coupon", "result": "allowed" },
{ "type": "tool_called", "tool": "issue_coupon", "args": { "value": 10 } },
{ "type": "tool_result", "ok": true },
{ "type": "cost", "tokens": 3120, "usd": 0.04 },
{ "type": "run_ended", "outcome": "coupon issued · within budget" }
]
}Read a run's trajectory through the Flash app. Fetch one run by ID, or list recent runs:
# one run's full trajectory
GET https://flash.socialhub.ai/api/flash/agent-runs/{runId}
# list recent runs
GET https://flash.socialhub.ai/api/flash/agent-runsEntries are never edited, only appended — the log is the complete history of what each actor did and why, reconstructable step by step from the stamped run ID and blueprint version.
Governance for free: five fail-closed guards
Here's the payoff of a unified runtime. Because every actor's execution flows through one runtime, the safety floor doesn't have to be bolted onto each agent — it's a structural property of the single place all action passes through. These five guards are code-owned, run under every actor on every action, and no setting can switch them off. The composition of a Definition — its skills, tools, model and context — is yours to configure in the AI Employees console; the guards below are not.
| Guard | What it enforces |
|---|---|
| Authorization scope × plan tier | Every tool call is checked against the key's scope AND the workspace's plan tier. The Definition names a tool; authority to run it lives in the database, resolved at call time. A tool the key can't reach is simply hidden. |
| Write-value caps + rate | Value-moving writes (points, coupons) are bounded by a per-call value cap and a per-key write-rate limit, both enforced fail-closed on the server — independent of anything the actor's prompt or client-side confirmation claims. |
| Budget ledger | Each run executes inside a token + cost budget, pre-charged before the actor acts and drawn down as it runs. When the ledger is exhausted the run stops — an actor can never run away with spend. |
| Kill-switch | Any actor — a whole definition or a single action — can be paused instantly. Off by default, capped when on, and stoppable the moment you want it to stop. |
| Audit | Every step is written to the append-only event log with the run ID and the exact blueprint version. Nothing an actor does goes unrecorded, and no setting can suppress a log entry. |
Configure the composition at /flash/agents. The AI Employees console is where you edit an actor's skills, tools, model and context — producing a new versioned blueprint. What you can never edit there is the safety floor: the five guards above are enforced in code, not in configuration.
Where the Harness fits with the rest of the platform
The Harness is the execution runtime under every AI actor — and, because everything runs through it, the governance layer too. Two adjacent references cover the pieces it leans on:
- MCP surface. An
mcp_externalactor holds a scoped key and calls Flash's governed tools over the Model Context Protocol. The endpoint, auth, client config and full tool catalog are in the MCP Integration guide. - Authorization gears & approvals. The per-action gear (auto / review / forbidden), the pending / refused write semantics and the approval lifecycle that sit on top of the authorization guard are documented in AI Governance: Introspection & Approvals.