iNexCCo DownloadBook an assessment
Reference architecture

VelocityOS

The layers an organization needs in place before AI agents are allowed to touch systems of record, and the constraints that stop each layer absorbing work belonging somewhere else. Read it if you'll be accountable for the result in production.

VelocityOS is a blueprint, and it carries no license fee. Every product named here is one you license in your own name. We assemble it, integrate it and hand it over. We hold no reseller agreement on any of it, the tools named are common defaults swapped per engagement, and you can replace any layer without asking us. We do bring our own accelerators to speed the build, on terms agreed in the contract, and you get their source code to keep.
Shape of it

Six layers, two planes

Governance and telemetry are drawn as planes rather than layers because that's what they are. Enforcement embeds at every boundary; telemetry aggregates from every layer. Neither is a slab you can point at in the request path.

Systems you already run · core apps · warehouse · SSO · collaboration · ITSM · event buses · source control · mainframe
PolicyAuthored once. Evaluated at intake, retrieval, routing, tool call, promotion and config change. Fails closed.
L6ExperienceChat, copilots in tools already open, the approval inbox, run status
L5OrchestrationIntake, decisioning, durable state, saga compensation, tool gateway
L4Models and toolsProvider gateway, model registry, tier routing, sandboxed execution
L3GovernancePolicy bundles, machine identity, secrets, evidence and lineage
L2DataIncremental ingestion, hybrid retrieval, entitlements at the data layer
L1DeploymentIaC, GitOps promotion, residency boundary, rollback by routing
TelemetryInfra metrics, traces, quality scores, cost per agent and tenant, human feedback. Collected as infrastructure, not app code.
Infrastructure it runs on · compute · data platforms · inference · retrieval · agent frameworks · DevOps · identity · observability
Layer by layer

What each layer owns, and what it must not do

The negative constraints matter more than the positive ones. Most failures we're called in to fix are a layer quietly doing another layer's job.

Experience

OwnsThe surfaces where people meet agents: conversational UI, copilots inside the tools already open on the desk, the approval inbox, run status, and a catalog of who owns which agent. Feedback belongs here too, and a rating is useless unless it carries session ID, agent version and the output text.

Must notHold model credentials, call a provider directly, or decide what a user may see. A widget that acquires its own API key is a governance hole nobody finds until an audit.

Fails asAdoption. A standalone portal gets a fortnight of curiosity traffic and flatlines, and since nothing writes back to the system of record, someone re-keys the output by hand.

BackstageSlackTeamsJira

Orchestration

OwnsThe path from intent to completed work: intake with an idempotency key, durably committed before the caller is acknowledged; a decisioning step picking agent, model tier and permitted tools before any inference; state held outside the workers so workers stay disposable; a durable runtime with checkpoints, retries and saga compensation; the tool gateway and the agent sandbox.

Must notDefine policy, store the corpus, or call a provider directly. One rule matters more than the rest: when an agent delegates to a sub-agent, the delegation re-enters at intake and passes every gate again. An internal fast path there hands an attacker a tool-calling primitive with no authorization on it.

Fails silentlyMost in-house builds break here around month four, when the first two-day workflow meets the first pod eviction. With no side-effect ledger, a retry after a crash sends the same invoice twice. With no compensation, a workflow dying at step four leaves an account half-created across three systems and nobody knows which three.

TemporalLangGraphKafkaPostgresRedis

Models and tools

OwnsA gateway in front of every provider, a registry of approved models and their costs, tier routing by task class and data classification, and the optimizations worth real money off the bill: prefix caching, semantic response caching, batched embedding runs. Tool execution is the other half, sandboxed and classified per call as read, write or irreversible, with a circuit breaker per tool so one sick downstream API isolates itself instead of taking out the worker pool.

Must notBe bypassable. If any layer can hold a provider SDK and its own key, safety filtering, cost attribution and the audit record become optional, and optional controls are absent controls.

Fails asLock-in you discover during a pricing change, and an inference bill nobody can attribute to a team.

ClaudeProxy gatewayMCPvLLM

Governance and trust

OwnsArtifacts, and not a slab of the request path: policy bundles in Git, machine identities for agents, the secrets store, the evidence and lineage archive, a bill of materials per deployed agent, and the pipeline that threat-models and adversarially probes an agent before promotion. Identity covers three principal types, human, agent and service, with agent credentials revocable fleet-wide in seconds, which is what makes containment possible.

Must notBe drawn as a horizontal band between orchestration and data. Enforcement embeds at every boundary in every other layer; only authoring, identity and evidence live in one place. Every enforcement point fails closed, which teams find painful in week one and stop noticing by week six.

Fails asA policy document instead of a policy engine, at which point "show me every action this agent took against customer data in March" takes six weeks of log archaeology to answer badly.

Open Policy AgentCedarVaultSigstoreSnyk

Data and integration

OwnsIngestion, retrieval and memory. Connectors pull incrementally so the corpus tracks the business instead of a nightly snapshot. Retrieval is hybrid: vector for semantic similarity, a graph for the relational questions vector search cannot answer, keyword for the exact-term cases both miss.

Must notScrub PII after embedding. Once sensitive text is embedded it's mathematically present in vectors you cannot fully purge, so the DLP gate sits before chunking. Entitlements are enforced inside the data layer at query time, from ACL metadata attached at ingest. Filter in application code after retrieval and one application bug is one data breach.

Fails asAn entitlement sync lagging group membership changes, so a leaver keeps retrieving for hours.

AirbytepgvectorNeo4jRedis

Deployment

OwnsInfrastructure as code, GitOps promotion, environment isolation, GPU pools that idle to zero outside production, and the option to run inside your residency boundary. What matters operationally is that rollback is a routing change: repointing takes seconds, and a container rebuild takes minutes you don't have during a quality incident.

Fails asAgent versions tracked in a spreadsheet.

KubernetesTerraformArgo CD
Cross-cutting

The two planes

Policy enforcement

Authored once, evaluated in many places, never all in one box. The decision points: intake, where a principal with no grant is refused before compute is spent; retrieval, where the ACL goes into the query instead of onto the results; routing, where a data classification forces a different or local model; tool invocation, where irreversible operations divert to a human; promotion, where a failed safety probe blocks release and no seniority overrides it; and configuration change, since a runtime parameter edit is itself a governed action.

The cost is a few hundred milliseconds. The benefit is that no single component failing open produces an uncontrolled action.

Telemetry

Every layer emits, one place aggregates, and collection is infrastructure-level instrumentation so no application code carries monitoring logic. Five signals matter and they're genuinely different: infrastructure metrics, execution traces, quality scores, cost events keyed to agent and tenant, and human feedback.

It can't be an afterthought, because AI failures are quiet. A degrading agent returns HTTP 200 at a zero error rate while its answers get worse, so the service-level indicator has to be successful structured completions and groundedness. Response codes tell you nothing.

One further discipline: attribute cause before remediating. Rolling back an agent version when the real problem was a stale index costs you the outage twice.

Runtime

The path of one request

Fourteen hops. The interesting column is what can refuse it.

  1. Intake. Normalize, assign an idempotency key, commit durably, then acknowledge.refusesschema failures, duplicate keys inside the dedupe window
  2. Identity. Validate the token, build a principal context combining the human and the agent identity.refusesexpired, unscoped or revoked credentials
  3. Scope resolution. Policy returns the namespaces and tool classes this principal may touch.refusesno grant for the domain, before a token is spent
  4. Deduplication. Semantic match against recent answers. A hit still re-runs the entitlement check, since the second asker may not be cleared for what the first one saw.
  5. Planning. Decompose into a task graph, dry-run it against the knowledge graph and tool registry.refusesa plan naming entities or tools that don't exist. Cheap here, expensive at step four of a two-hour workflow
  6. Retrieval. Fan out across vector, graph and keyword; rerank; assemble with provenance per chunk.refusesthe store itself, per chunk, on ACL
  7. Context budgeting. Enforce the token budget before dispatch, truncating by priority. Prevents silent provider-side truncation, where the model loses the tail of the context and nobody upstream is told.
  8. Input guard. Injection and jailbreak screening, PII in the prompt.refusessynchronously; the model call does not proceed
  9. Routing. Tier by task class, then residency. A compliance conflict reroutes to a permitted model, so the caller sees a slower answer instead of an error.
  10. Inference.
  11. Output guard. Exfiltration, toxicity, unverified claims.refusesblock, redact or escalate depending on trigger
  12. Tool call. Classified read, write or irreversible; the ledger entry is written before the call.refusesa tripped circuit breaker, or an irreversible action with no approval on record
  13. Settlement. Ledger commit, or compensation in reverse order if a later step fails. Compensation deactivates instead of deleting, so a re-run reuses what was already built.
  14. Delivery and evidence. Stream to the caller, write the trace and lineage record, emit cost and quality telemetry.
Two to three seconds for a conversational query with tools. Hours or days for anything holding a human gate.
Human gates

Where a person is required

Resuming costs little in state and more than teams expect in time. The workflow checkpoints atomically before the pause and replays from exactly that point. Rehydration does have to re-validate that retrieved knowledge is still current, since a document may have changed during a two-day wait, and a long enough pause can invalidate the plan itself.

But the real cost is queue latency, and it's invisible to infrastructure monitoring. A backed-up review queue stalls production workflows while every dashboard stays green. Instrument queue depth, reviewer response time and SLA breach, or the design quietly degrades into a batch process on a weekly cadence.

Cost and fit

What it costs, and when not to build it

The floor is a gateway, identity and policy enforcement, a vector store, a durable workflow engine, tracing and an evidence archive. License cost for that set is real and rarely the binding constraint. Three things dominate instead: inference spend, which caching and tier routing reduce substantially, though the range is wide and depends on how repetitive your traffic is; a GPU floor if residency rules force self-hosting, usually the largest single line; and two to four engineers keeping policy bundles, connectors and evaluation sets current, indefinitely. Integration cost is front-loaded. Operating cost is mostly salaries.

Do not build this if any of the following holds

Terms

Glossary

Idempotency key
A caller-supplied identifier letting the system recognize a retry as a retry, so a network timeout doesn't become a second order.
Side-effect ledger
A write-ahead record of every external action, written before the call. It's what makes exactly-once behavior possible against systems that don't offer it.
Saga compensation
The registered inverse of each completed step, run in reverse order when a workflow fails partway, so systems return to a consistent state without manual cleanup.
Durable execution
A runtime persisting its event history, so a process surviving days and a pod crash resumes at the step it reached.
Hybrid retrieval
Vector, graph and keyword search combined, because relational questions defeat vector search and exact-term questions defeat both.
Entitlement at the data layer
Access control evaluated inside the query against metadata attached at ingest, so an application bug cannot leak a document.
Fail closed
When an enforcement component is unreachable, the default answer is deny.
Agent machine identity
A scoped credential issued to an agent instead of borrowed from a user. It makes per-agent permissions and fleet-wide revocation possible.
Drift
Gradual divergence between model output distribution and current reality. Detectable statistically, invisible to error rates.
Trace replay
Rebuilding a production execution from its recorded trace, to reproduce a failure and turn it into a permanent regression test.
Rollback by routing
Reverting to a previous agent or model version by changing a route. Seconds instead of minutes.

Where this starts

Two weeks, one value stream, a costed plan for your board. We measure your baseline first, and if the honest answer is that you're not ready, we say so then.

Book a readiness assessment