Taos Architecture Overview

Version: 1.1 · Date: April 2026

Design Principles

Taos is built on a single premise: governance is structurally enforced, not contractually promised. An agent cannot bypass policy because it has no execution path that avoids the kernel. An agent cannot exfiltrate credentials because it never possesses them.

Every architectural decision flows from that constraint. The choices below — the two-plane split, the credential model, the relay, the audit design — are consequences of taking it seriously as a hard rule rather than a goal.

The Two-Plane Model

The platform divides into two independent planes that share no operational data:

┌──────────────────────────────────────────┐
│        Control Plane  (Taos SaaS)        │
│                                          │
│  Policy authoring  ·  User/group mgmt    │
│  Workflow registry  ·  Approvals UI      │
│  Audit dashboard   ·  Configuration      │
│                                          │
│  Holds: workflow/step/tool definitions   │
│  Never holds: execution data, PII, creds │
└──────────────────┬───────────────────────┘
                   │  Registry metadata only
                   │  (bootstrap pull — not in hot path)
┌──────────────────▼───────────────────────┐
│    Data Plane — Taos Kernel  (on-prem)   │
│                                          │
│  Policy engine  ·  Credential broker     │
│  Authorization chains  ·  Saga engine    │
│  Audit emitter  ·  Approval relay        │
│                                          │
│  Holds: all execution data               │
│  Never pushes: user data to control plane│
└──────────────────────────────────────────┘

Bootstrap is the only moment the two planes communicate: the kernel pulls workflow and step definitions from the control plane at startup. After that, all execution happens inside the customer's network.

The Kernel as Mandatory Chokepoint

The kernel is the only party that can authorise an agent to act. This is structural, not configurable — a consequence of how credentials work.

Agent workers do not hold tool API keys or user credentials. Before each step, the worker calls the kernel to claim the step. The kernel evaluates policy, brokers the credential scoped precisely to that step, and issues a short-lived Agent Request Token (ART). The worker presents the ART to the tool server, which verifies it against the same signing key. If the kernel did not issue the ART, the tool call fails authentication.

There is no configuration path that places credentials directly in the agent.

The Token Credential Hierarchy

Every agent action is backed by a four-layer credential chain, each layer narrower than the one above:

Corporate IdP JWT
  — user's raw identity, from the customer's identity provider
  └─ OBO Token  (On-Behalf-Of)
       — kernel-issued, represents delegated user authority
       — scoped to a group and its permitted workflows
       — stored in the kernel vault; the user never handles it
       └─ Session Credential
            — scoped to one interactive workflow session
            — renewable on reconnect; expires on idle/absolute timeout
            └─ ART  (Agent Request Token)
                 — scoped to exactly one step execution
                 — single-use; expires on step completion or timeout
                 — carries only the permissions that step's policy allows

The OBO token is issued using RFC 8693 (Token Exchange), anchored to the user's corporate identity. The ART carries RFC 9396 (Rich Authorization Requests) structured claims specifying exactly what the step may do. A complete audit of any action can trace from the tool call back to the authorising human, through each delegation link, with cryptographic proof at every step.

OBO consent is collected eagerly at group membership assignment. When an administrator adds a user to a group, the user consents to the group's capabilities once. There are no approval pop-ups during live workflow execution — the OBO token is already in the vault before any workflow runs.

Policy Evaluation

The kernel embeds a Rego policy engine (Open Policy Agent's language, in-process — no external OPA server required). Policy evaluation runs at the step execution boundary, before the step executes.

Policies can examine the full accumulated execution context — previous step outputs, risk scores, computed attributes — in addition to user identity and role. For example:

"Allow this payment only if the risk score from step 2 was below 0.7."
"Require a second approver if the transfer amount exceeds the user's delegation limit."
"Deny if the vendor is not on the approved list loaded from the customer's database."

Policy decisions have four outcomes: allow, deny, require-approval (pause for a named approver), or require-group-approval (quorum). Deny and escalation halt execution and trigger the saga rollback sequence.

Policies are authored in the control plane, version-controlled, and diffable. They are readable by auditors and can be submitted to a regulator as a governance artefact.

The Outbound Relay and Human Approval

The kernel is on-prem behind a firewall; approvers may be anywhere. Taos solves this without inbound firewall rules.

The kernel maintains a persistent outbound WebSocket to a Taos relay service. The relay is a dumb pipe — it routes signed message envelopes by kernel ID and cannot read or forge their contents. The signing key is customer-owned and never seen by Taos. This is the same architecture used by GitHub Actions self-hosted runners and Cloudflare Tunnel.

When a step requires human approval, the kernel sends a signed request over the relay. The approver acts via the control plane UI or a notification. Their signed response returns over the same channel. The kernel verifies the signature before resuming execution.

Approval class	Triggered by	Duration
OBO consent	Group membership assignment	Hours–days (policy-defined)
Step gate	Workflow paused at approval step	Configurable; default 15 min

Credential Brokerage and the Secrets Vault

The kernel includes a pluggable secrets vault. Three tiers match customer operational maturity:

Embedded vault — encrypted local store unlocked at startup. Zero external dependencies. Suitable for initial deployment.
HashiCorp Vault — for organisations already running Vault. Secrets never leave the Vault boundary.
Cloud secrets managers (AWS Secrets Manager, Azure Key Vault) — for cloud-native deployments via managed key services.

All three tiers expose the same interface to the kernel. Switching tiers is a configuration change.

The signing key used for OBO token minting is customer-generated, stored in the vault, and rotated by the customer. Taos is not involved in rotation and is not notified when it occurs. The kernel supports key versioning — a workflow executing step 3 can still verify a token signed with the key that was rotated before step 2.

Saga Compensation

Every step registered with the kernel must declare a compensation handler. There is no default — a step without one fails validation at registration time.

Type	When to use	How it executes
`tool_call`	A programmatic reversal exists (e.g. `payments.reverse`)	Kernel invokes the named tool automatically
`human_escalation`	No automated reversal is possible (e.g. settled wire transfer)	Kernel suspends rollback and routes a decision task to a named human
`noop`	The step has no observable side effect (e.g. read-only query)	Explicit declaration — cannot be accidentally omitted

On step failure, the kernel executes compensations in reverse order. Checkpoint steps halt automated rollback — they represent committed states after which automatic unwinding is inappropriate. A failed checkpoint triggers human escalation rather than continuing to unwind.

The distinction between noop and a missing declaration is intentional: "nothing to undo" and "I forgot to declare a rollback" look identical at runtime. Taos treats absence as a schema error at registration time.

Framework Integration

Any agent framework integrates via three gRPC primitives:

RegisterWorkflow — declare the workflow DAG, step definitions, and all compensation handlers at startup. The kernel validates and stores the registration.
GetStepParams — before each step, call the kernel. Receive the ART, step context, and brokered credentials. If policy denies, this call returns the denial — the step never runs.
SubmitStepResult — after execution, return outputs and status. The kernel records the audit entry and triggers compensation on failure.

For LangGraph specifically, a single wrapper function applies governance to an existing graph without modifying it. The inner graph requires no Taos imports. The wrapper inserts a pre-policy checkpoint before the inner graph and a post-policy checkpoint after it. The inner graph has no edge to END — it cannot complete without passing both checkpoints.

Audit Log Architecture

Two audit domains with two owners:

Configuration audit (control plane): Policy changes, user and group modifications, delegation assignments. Stored in the control plane. Carries no customer PII. Accessible via the audit dashboard.

Execution audit (on-prem kernel): Policy decisions, step executions, tool invocations, OBO chain evaluations, compensation events. Produced by the kernel and stays within the customer's network. Never persisted in the control plane database.

The kernel emits execution audit records to the customer's own storage — SIEM, Iceberg lakehouse, Splunk, or any OpenTelemetry-compatible sink. The control plane can act as a notary: it cryptographically witnesses periodic commitments over batches of audit records without seeing any record content, providing tamper evidence suitable for regulated-industry requirements.

PII Tokenization

The kernel can substitute real sensitive values with session-scoped tokens before data reaches the agent. The agent reasons over a token like <ACCT-tok-7f2a> rather than a real account number or SSN.

Detokenization requires an ART authorised for that specific operation. A token string obtained by an exfiltrated agent payload is useless — it carries no information, cannot be reversed without kernel access, and expires when the session ends.

This provides a structural defence against prompt injection: even an agent executing malicious instructions cannot exfiltrate meaningful data, because it never had access to the real values.

Standards Reference

Standard	Application in Taos
RFC 8693 — OAuth 2.0 Token Exchange	OBO token chain — cryptographic proof of human-to-agent delegation
RFC 9396 — Rich Authorization Requests	ART scopes — per-step permission claims
RFC 9068 — JWT Access Tokens	Structured, verifiable claims in all kernel-issued credentials
OPA / Rego	Embedded policy evaluation — deterministic, diffable, auditor-readable
OpenTelemetry	Execution trace and metrics export to customer-owned observability
OpenAPI 3.0	Tool server onboarding and schema introspection
MCP — Model Context Protocol	Tool server adapter type for MCP-compatible servers
W3C PROV	Agent action provenance and lineage attribution
mTLS	Optional kernel-to-tool-server mutual authentication