Claude Agent SDK harness

The claude_agent_sdk harness runs the agent loop in the harness server, outside the session sandbox. The sandbox is a pure tool executor: the loop decides what to do, and the sandbox runs the file and shell operations on request. This is the default, and it is the only harness with the complete feature set.

Get your registry endpoint

Select this harness

Select it explicitly, or omit both metadata keys and get it by default:

ork agent create \
  --name "support-triage" \
  --model claude-sonnet-4-6 \
  --metadata harness=claude_agent_sdk

This harness runs only in separate mode. Pairing it with mode: "colocated" returns 400.

After configuring the Python SDK, pass the same harness metadata:

from orca import Orca

client = Orca()
agent = client.agents.create(
    name="support-triage",
    model="claude-sonnet-4-6",
    metadata={"harness": "claude_agent_sdk"},
)

For a local Compose walkthrough using this harness, see Run an agent with ork local.

What it supports

Everything documented elsewhere in these docs applies to this harness without qualification:

• The full built-in toolset - bash, read, write, edit, glob, grep, list, and delete.
• Permission policies, including always_ask, which pauses the session and waits for a user.tool_confirmation event.
• Guardrails at request, tool_call, and tool_result, including stateful rules and rules bound to a subagent. A guardrail that asks uses the same confirmation exchange.
• MCP servers, rewritten at session start to route through the gateway with a short-lived session token.
• Token-level streaming, as opt-in event_start / event_delta frames. agent.message is still emitted whole once per turn either way - the deltas arrive alongside it, not instead of it, and only when the stream request asks for them.
• user.interrupt, user.define_outcome and its outcome-evaluation spans, and agent.thread_context_compacted when the thread's context is compacted.
• Any sandbox runtime, including the local runtime used by the evaluation stack.

Client-executed built-in tools

On self_hosted environments only, this harness can hand the built-in tools to your application instead of running them in the sandbox. The agent emits agent.tool_use and waits for a user.tool_result carrying that event's id as tool_use_id - the event has no tool_use_id field of its own to copy. Same shape as a custom tool round trip, where the id is echoed as custom_tool_use_id.

Use it when the "filesystem" the agent should operate on is not a sandbox at all - a document store, a customer's own machine, a service you front.

Session continuity

Conversation state lives in Orca's transcript store rather than in the sandbox. Each session resumes from a deterministic identifier, so a session that pauses and restarts picks up its history even if the underlying sandbox was replaced. Nothing about continuity depends on the sandbox surviving.

Model access

The harness server supports direct provider access and Orca AI Gateway egress. The deployment default is direct unless the operator sets LLM_EGRESS_DEFAULT=gateway. A session's metadata.orca_llm_egress value overrides that deployment default. Provider credentials stay on the harness host for direct egress and never enter the sandbox.

See Use the gateway with Agent Engine to configure Gateway egress for every session by default.

What's next