Agent Engine architecture
How Workspaces, Runtime, and Registry fit together in Orca Agent Engine.
Orca Agent Engine runs inside a Workspace, the isolation unit for tenancy, identity, and governance. Each Workspace contains two user-facing pillars: Runtime and Registry.
Architecture at a glance
How the pieces interact
Running an agent involves three processes. The registry stores the agent and the session and hands out the pinned configuration. A harness drives the agent loop. A sandbox executes the agent's tool calls in isolation. MCP traffic leaves through the AI Gateway. Model traffic also uses the gateway when the harness requires it or the deployment or session selects Gateway egress.
| Step | What happens |
|---|---|
| 1. Define | You create an Agent in the registry: model, system prompt, tools, MCP servers, skills. Every change makes a new version. |
| 2. Start | You create a Session against an agent version and an Environment. The agent version is pinned for that session's lifetime; the environment is not - it is re-read each turn. |
| 3. Provision | The runtime builds a sandbox from the environment and mounts the session's files, memory stores, and repositories. |
| 4. Drive | You send events; the harness runs the loop and calls tools. Where the harness runs is the one runtime choice an agent author makes - see Runtime. |
| 5. Authenticate | On the default topology, MCP calls that need credentials resolve them from Vaults at the gateway, so secrets never enter the sandbox. |
| 6. Observe | Events, files, and outputs are recorded per session and readable through the registry. |
The deprecated Agent Function path packaged agent code as a function-mesh deployment. Current clients do not expose that resource; use triggers for event-driven or scheduled agents.
Inheritance from the streaming substrate
On StreamNative Cloud, Orca Agent Engine runs on the same leaderless, object-storage-native substrate that powers StreamNative's data streaming (Pulsar, Kafka, Ursa). That means:
- Functions over Pulsar or Kafka, sources, sinks, and Kafka Connect are available as StreamNative Cloud extension resources alongside managed agents.
- Schema Registry, connections, and the streaming substrate remain available to those Cloud workloads through the Workspace registry.
- Operators use the same monitoring, alerts, and audit tooling they already use for streaming workloads.
Registry endpoint
Every Agent Engine API call goes to a registry endpoint. On StreamNative Cloud, each Workspace has its own: when you enable Agent Engine on a Workspace, the controller publishes the registry endpoint URLs in the Workspace's status.serviceEndpoints[]. On a self-hosted deployment, the endpoint is the URL where you expose the registry service.
See Connect to the registry for a self-hosted deployment.
AI Gateway
Orca AI Gateway governs the model and MCP tool traffic shown in the diagram. It is a separate product with its own documentation.