How Orca works
Checked against Orca Agent Engine v0.5.1
A harness runs the loop
An agent is a loop: a model asks for a tool, something runs it, and the result goes back. The program that drives that loop is a harness. Claude Agent SDK, Codex and Pi are harnesses.
What production asks for
The loop is the same on a laptop and in production. What changes is everything around it. Pick a demand to see what the loop alone leaves open.
Three parts, three interfaces
Orca Agent Engine separates the loop, the tools and the state, so each can fail or be replaced on its own. Pick a part.
Where each piece runs
Your application talks to one endpoint. Behind it, each concern has its own place. Pick something an agent touches to see where it lives.
One message, hop by hop
Follow a support ticket through the runtime. Each step lights the hop it takes and adds what that hop wrote to the session’s log.
Your app sends a message
A POST to the session’s events. A message is an event like any other, and the call returns as soon as it is stored.
The Registry appends it to the log
The append is synchronous: once the call returns 200, the message is in the session’s log and the session is running.
The Harness Server picks it up
It reads the new event from the log, then asks the Registry to prepare the run: the pinned agent version, its skills and the rules that apply.
A sandbox is acquired
Creating the session provisioned nothing. The first message is what acquires a sandbox, built from the session’s environment.
The model is called
The turn begins. The call leaves through the AI Gateway, which holds the provider key.
The agent looks up the ticket
The model asks for an MCP tool. This agent’s policy lets the tool run without asking, so once the rules are checked the Gateway makes the call, with the credential from the session’s vault.
It writes a note in the sandbox
A built-in tool this time. The harness asks the Sandbox to write the file, and the result comes back as another event.
The reply reaches your app
The agent’s message is appended to the log like everything before it. Your application’s stream delivers it, and the session goes idle.
Event log
- Nothing yet.
- user.message Triage this ticket: customer cannot log in.
- session.status_running the turn starts
- span.model_request_start model: claude-sonnet-4-6
- agent.mcp_tool_use tickets · get_ticket
- agent.mcp_tool_result ticket #4821
- agent.tool_use write · outputs/triage.md
- agent.tool_result written
- agent.message Routed to Identity: login is failing.
- span.model_request_end token usage
- session.status_idle stop_reason: end_turn
An illustration. Event types follow the API reference; the values are examples.
The harness becomes a field
You keep the harness you already use. On Orca it is a field on the agent, chosen when the agent is created. The rest of the map stays as it was.