Runtime
How Orca Agent Engine executes an agent - the harness that drives the loop, the sandbox that runs its tools, and the two topologies you can choose between.
Three processes are involved every time an agent runs in Orca Agent Engine. The registry stores the agent and the session and hands out the pinned configuration. The harness drives the agent loop: it calls the model, decides which tool to invoke next, and emits the events your application reads. The sandbox is an isolated container where the agent's file and shell operations actually happen.
The registry and the sandbox are always separate. What varies is where the harness runs, and that is the only runtime decision an agent author makes.
The two topologies
Claude Agent SDK
The default. The loop runs in the harness server; the sandbox executes tools on request.
Claude Code
The loop runs inside the sandbox image, and the harness server bridges events in and out.
Codex SDK
Run an OpenAI model with the Codex SDK, separately or inside the sandbox.
Pi SDK
Run a supported provider model with the Pi SDK in either mode.
separate is the default. The harness server holds the loop and treats the sandbox as a tool executor: read this file, run this command. Provider credentials stay on the harness host, and the sandbox never learns the real address of an MCP server it calls.
colocated puts the loop inside the sandbox image. Cloud Claude Code, Codex SDK, and Pi SDK use the harness server's sandbox bridge. Their workers reach models through Orca AI Gateway with a session-scoped token rather than holding a provider key. in_sandbox remains a deprecated alias for this mode.
colocated mode is not fully implemented in this release. Use separate, the default.
The selected harness also determines the model catalog and available capabilities - see Choose a harness for how to set it.
What each topology supports
The comparison below applies to the two Claude harnesses: claude_agent_sdk in separate mode and claude_code in colocated mode. See the Codex SDK and Pi SDK pages for their capabilities.
Claude Agent SDK (separate) | Claude Code (colocated) | |
|---|---|---|
| Built-in tools | all eight | six - no list, no delete |
always_ask policy | pauses for confirmation | tool dropped from the session |
| MCP servers | routed through the gateway | not wired |
| Token-level streaming | yes | no |
user.interrupt, user.define_outcome | supported | rejected |
user.tool_result | self_hosted environments only | rejected with 400 |
| Model traffic | direct or AI Gateway, selected by deployment or session configuration | routed through the AI Gateway |
| Sandbox runtime | any | requires one that exposes a port |
| Outputs | object storage when configured | captured inside the sandbox |
Skills, subagents, custom tools, agent.thinking, and the file, memory-store, and GitHub repository mounts behave the same on both.
Session lifecycle
A session reports lifecycle state through distinct event types rather than one event with a status field. The two topologies share the event names where they support a capability:
| Event | Meaning |
|---|---|
session.status_running | The harness started or resumed work. |
session.status_idle | The agent stopped. stop_reason.type says why - requires_action means it is waiting on you. |
session.status_rescheduled | The default harness is retrying a transient model-provider failure. It does not change the session record's status. |
session.status_terminated | Reserved, and never emitted. The harness leaves a failed session idle and resumable rather than terminating it, and archive and delete are handled by the registry, which emits session.updated / session.deleted. Do not wait on this event. |
See Events and streaming for the full event taxonomy, and Sessions for creating and driving one.
Scaling and isolation
Sessions are independent. Each one gets its own sandbox, and the registry pins the agent version at creation time so a session's behavior does not change when the agent is updated underneath it. Concurrency is bounded by the Workspace's quotas rather than by anything in the agent definition.
Under Cloud colocated execution, the loop additionally runs inside a kernel namespace that restricts writes to the paths the session declares, and the check fails closed: if isolation cannot be established, the session does not start.
Agent Functions, the earlier runtime
Before managed agents, agent code was packaged and deployed as an Agent Function on the Workspace's function-mesh runtime, alongside Pulsar Functions and connectors. Agent Functions are deprecated, and current clients do not expose their operations. Use Agent Triggers for event-driven and scheduled agents.
Agent vs Agent Trigger vs Agent Function
Three related concepts in Orca Agent Engine use the word "agent":
- Agent - a registry resource that defines a model, system prompt, tools, MCP servers, and skills. Managed with
ork agentand documented under Agents. - Agent Trigger - starts sessions for an agent on a schedule or in response to events. Managed with
ork agent triggersand documented under Triggers. Use triggers to run agents automatically. - Agent Function - the deprecated function-mesh code unit that ran an agent before managed agents. Agent Triggers replace it, and current clients do not expose it.
The ork agent commands manage agents and their related registry resources: sessions, environments, files, vaults, skills, memory stores, and triggers.
Agent Triggers
Run an agent on a schedule or from events - the replacement for Agent Functions.
Functions
Stream processing over Pulsar or Kafka in the current Cloud extension API.
Sources and sinks
Pulsar IO connectors that bridge topics and external systems.