Inside Orca Agent Engine: Governing Managed Agents from Outside the Agent

Orca Agent Engine separates the agent loop, tool execution, and session state so they can evolve independently. This companion to Open-Sourcing Orca Agent Engine: Building an Open Runtime for Managed Agents explains how those interfaces work, how sessions recover, and where governance is enforced. It is for developers who want to run or extend the engine; the examples use names from the code.

We did not start from a blank page. Anthropic’s engineering post on managed agents laid out the principles we adopted: decouple the brain from the hands, keep credentials out of the sandbox, and treat the session as a durable log rather than a context window.

For Orca, we added two requirements: support multiple harnesses and model providers, and let teams operate the runtime in their own infrastructure. Operators also need to set limits that agents cannot weaken. Those requirements shaped the interfaces below.

Scroll to see the whole diagram →

• The brain is the model call, and it lives in the harness.
• The hands are tool execution: the Sandbox runs built-in tools and the AI Gateway carries MCP calls.
• The session is the state, kept in the event store, with the file and memory stores beside it.
• Each part relies only on the others' public interfaces.

Separate the harness from tool execution

Scroll to see the whole diagram →

• SDK, CLI and UI clients reach the Registry.
• The Registry works with the Harness Server. It never runs agent code itself.
• The Harness Server executes built-in tools in a Sandbox.
• The Harness Server and the Sandbox both reach the AI Gateway, which holds the credentials.
• The AI Gateway calls MCP tool servers and LLM providers on their behalf.
• Transcripts and audit logs land in the Event Store, backed by Kafka, Postgres or Pulsar.

Agents can generate and execute code that has not been reviewed. We treat that code as untrusted. The runtime separates the contract for the agent loop from the contract for executing tools, with isolation determined by the chosen harness and sandbox implementation.

In Orca Agent Engine, the three parts are three interfaces. The brain is an AgentHarness: events in, events out, with durable session state recorded outside the harness process. The hands are a sandbox, acquired from a pluggable runtime and driven through a handle:

runtime.acquire(env)          → handle
handle.run({ tool, args })     → { stdout, stderr, exit_code }
handle.files.read(path) · handle.files.write(path, data)
handle.destroy()

The session is backed by the event store, which the next section covers. The Registry is the control plane: it stores declared resources and does not execute agent-generated code. Before execution, the harness asks the Registry to prepare the run and receives the agent version, pinned skills, and compiled rules it needs.

The Harness Server coordinates execution through the Claude Agent SDK (the default), Codex, or Pi. Placement depends on the harness. In the Claude Agent SDK integration, the harness runs beside the sandbox. Its built-in tools are disabled and replaced by tools that call the sandbox handle, so a shell command or file edit runs in the sandbox rather than in the harness process. Model-provider and MCP calls routed through the AI Gateway use the gateway’s credential handling.

Sandbox runtimes include local isolation for development, E2B, and OpenSandbox. The Harness Server requires an explicit runtime selection at startup, so a missing selection fails before a session is created.

Sandboxes are disposable. When a session goes idle, its sandbox is destroyed; the next message provisions a fresh one and restores the session according to the harness’s recovery behavior. This reduces dependence on a particular machine, but adds a cold start. The session log does not preserve arbitrary files on the sandbox’s disk: unpushed repository edits, for example, are lost unless saved elsewhere.

The session is the log

A session is represented by an append-only event log in the event store, called TranscriptStore in the code. Each session has its own log. An event records its ID, sequence, producer, timestamp, kind, and opaque payload. The store does not interpret the payload. It appends, reads, and follows events:

append(workspaceId, sessionId, events)          → eventIds
read(workspaceId, sessionId, { fromCursor })    → events
tail(workspaceId, sessionId, { fromCursor })    → live events

The event-store backend coordinates which Harness Server replica drives a session: a consumer group on a per-session topic with Kafka, leases with PostgreSQL, or a key-shared subscription with Pulsar. A session starts idle, with no sandbox until its first message. The sandbox is released when the session becomes idle again.

The event-store adapters deduplicate appends by event ID, but the guarantee depends on the backend. PostgreSQL uses a unique key; the Kafka and Pulsar adapters keep deduplication state in memory, so it does not survive a process restart. This describes Orca’s adapters, whose guarantees can differ from the underlying brokers. The backend is configurable, with Kafka as the default.

The harness side of the contract is just as small:

harness.submit(event, { onAccepted })   → 'submitted' | 'deferred'
harness.events()                         → stream of AgentEvent

The onAccepted callback records an acceptance marker after validation and before execution proceeds. It marks that a replica has accepted the event. At the end of the turn, the engine writes a completion marker with the final status. After a crash, the replica taking over reads those markers to distinguish completed work from interrupted work.

Recovery depends on the harness. The Claude Agent SDK rebuilds its context from the log through a session store that Orca implements on top of the event store. The Codex and Pi SDKs maintain their own checkpoints and record each turn’s progress. If a turn is found half-finished after a crash, those integrations mark it as an error rather than replaying it.

Delivery is at least once. The engine does not guarantee exactly-once model execution or external tool side effects. A process can fail after a tool runs but before its turn completes, and a retry can repeat the call. Tools that change external state should support idempotent operations, using a stable operation ID where possible.

Secrets stay behind the gateway

Gateway-managed credentials stay outside the sandbox. This matters because untrusted code can read secrets placed in its environment.

Credentials for gateway-mediated calls live in vaults. A session references vaults, and the agent works with references rather than the underlying secrets. When the session starts, the harness receives a short-lived token scoped to that session. Configured MCP server addresses are rewritten to point at the AI Gateway. This lets the gateway attach credentials without depending on network-interception hooks in the harness SDK.

For each proxied call, the gateway checks the session token, identifies the target server and its credential, fetches the secret from the vault, and injects it into the outgoing request. The underlying credential value is not passed into the sandbox for that call.

The workspace scopes resource access. Requests resolve to a workspace, and its agents, credentials, and transcripts are accessed within that scope. Keeping gateway-managed secrets outside the sandbox reduces credential exposure; it does not prevent an agent from disclosing data it can read. Operators still need permissions and network controls appropriate for their workload.

The harness and the model are fields

Scroll to see the whole diagram →

• A Session pins a version of an Agent, so changing the agent never rewrites a run that already happened.
• A Session runs in an Environment and produces Events.
• A Session references Vaults for credentials, by id and never by value.
• A Session mounts Files, MemoryStores and Skills.
• A Trigger creates Sessions — on an event, a topic, or a schedule.

The resource model defines the Agent, the Environment it runs in, the Vaults it may use, the Files, MemoryStores, and Skills it can read, and the Triggers that start it. Versioning lets a session retain the configuration it started with.

• Every update to an Agent creates a new version. A session keeps the version it started with, so editing an agent does not change the definition used by an existing run.

• A Skill is pinned by version and by a hash of its exact contents, so you can identify which instructions a run used.

• A MemoryStore keeps every version of every memory.

• A Trigger, our addition to the API, starts sessions on a cron schedule, each against a pinned version of the agent.

Updates are guarded by the version they read: an update based on a stale version of an agent is rejected rather than silently overwriting someone else’s change.

The model is a field on the Agent. Moving a task to another supported model is an explicit configuration update that creates a new agent version; Orca does not choose a cheaper model automatically. The harness is also a field, but it is fixed when the agent is created. Switching from the Claude Agent SDK to Codex requires creating a new agent. Existing sessions retain their pinned agent version.

Adding a harness does not require the runtime to own its context strategy. Summarization and compaction stay with the harness and its SDK. A new integration supplies a provider that builds the harness and an adapter that maps its native session format onto the event store. Skills are loaded on demand: the system prompt carries a catalog of pinned skills, and the agent reads the full instructions when needed.

Limits that live outside the agent

Permissions stored only in an agent’s editable configuration can be weakened by whoever controls that configuration. Orca stores governance rules in the Registry and enforces supported checks through the harness integration. An agent cannot loosen a higher-level rule by changing its own configuration.

Scroll to see the whole diagram →

• What usually happens: the agent holds its own limits and can rewrite them.
• With Orca, the agent's actions pass two checkpoints that sit outside it.
• Before it acts: may this run, and is there budget left?
• Before it leaves: may this data go out, and to whom?
• The agent cannot reach either checkpoint.

Rules are compiled when they are written, so malformed rules are rejected up front. In addition to built-in rule kinds, a rule can be an expression over the action and the session’s usage. When execution is prepared, the Registry recompiles the applicable rules and composes them in order: session, agent, workspace, organization. The harness receives that ordered list, and rule edits take effect from the next turn. The agent version stays pinned even when applicable governance rules refresh. Each supported check resolves to one decision:

verdict = fold(guardrails, seed = permissionPolicy(tool), max)   // allow < ask < deny

• Each guardrail answers allow, ask or deny.
• Scopes compose by taking the strictest answer, so a verdict only moves up the staircase.

The fold starts from the tool’s permission policy and takes the maximum at every step, so a rule can tighten a verdict but cannot loosen it. A workspace cannot relax its organization’s rule, and a session cannot relax its agent’s. Organization rules are the one tier a workspace administrator cannot remove. When an agent dispatches subagents, the coordinator’s rules apply to the delegated work, and spawn_bounds caps how many subagents it can start in a turn.

Guardrails attach to execution phases. Current integrations support checks when a turn starts, before a tool call runs, and before a tool result reaches the model; coverage varies by harness. Enforcement checks fail closed: if the check errors, the action is denied. Observation-only checks fail open. A fourth phase, the model request, is defined but is not yet evaluated by any harness. The Claude Agent SDK integration warns when a rule targets that phase.

The ask verdict is supported at the tool-call phase and uses the existing tool-confirmation round trip. A deny withholds a rule’s proposed state updates; an ask defers them until approval. Approved rule state must be persisted through the Registry before the corresponding action proceeds. Persisting that state lets counters survive a session restart.

Budgets are stateful rules measured in dollars or tokens and scoped to a session, a user’s day, or a subagent. Enforcement depends on the harness: the Claude Agent SDK integration checks budgets at tool calls, while Codex and Pi check stateful rules at the start of a turn. A turn-boundary check cannot interrupt an in-flight model request. The budget policy treats unpriced models as requiring approval rather than zero-cost usage. Soft thresholds ask once where that approval path is supported. A hard-cap policy can block named expensive models while allowing cheaper ones. Allowing a cheaper model does not select it: an operator must configure the model change.

Built-in rules include blast_radius, which classifies shell commands as safe, risky, or catastrophic; detect_loop, which detects repeated calls; and worktree_guard, which restricts writes to an allowed root. These checks complement sandbox isolation; they do not replace it.

API compatibility is explicit

Orca implements supported operations from the Claude Managed Agents API. The official Anthropic SDKs can connect by changing their base URL, with coverage and differences documented in the conformance matrix. The matrix is generated from the code and checked in CI; it records implemented operations, known differences, and the rationale for each difference. Orca-specific extensions, such as Trigger, are identified separately.

We want teams to use familiar clients while choosing the runtime they operate. Publishing the differences is part of that contract: API similarity is useful only when developers know which behavior they can rely on.

What stays stable and where to contribute

Orca defines a small set of interfaces: durable session events, tools reached through a sandbox handle, credentials resolved at the gateway, and supported actions evaluated against centrally managed rules. The harness, model, sandbox runtime, and event-store backend can evolve behind those interfaces. Their recovery and enforcement behavior remains part of the integration contract.

That is also where we would most like help:

• More harnesses. Implement a provider and session adapter, and help test the integration’s recovery and guardrail behavior.

• Agent frameworks. Help bring framework-based agents under the same resource model, event log, and governance interfaces.

• More guardrails. Extend the built-in rules and improve tests for enforcement and approval behavior.

• More backends. Add event stores, sandbox runtimes, and observability destinations, with clear documentation of their guarantees.

Orca Agent Engine is open source and in Developer Preview. Start with the quickstart, run a session, and test recovery and policy behavior with your workload. Report what breaks, propose an interface change, or contribute an integration. We would like to build this with the community.

• Orca Agent Engine: github.com/orca-ae/orca-agent-engine

• Documentation and quickstart: docs.runorca.ai

• Claude Managed Agents conformance matrix: conformance-matrix.md

Acknowledgments: thanks to Sijie Guo, Guangning E, and the Orca maintainers and contributors.