--- title: "Architecture" description: "See how the control plane, Agent Computer Workers, Actor Runtime, Brain, and Background Agent Jobs form the Ankole Agent Harness." url: "https://ankole.agentbull.com/en-US/docs/architecture/" lang: "en-US" --- > Documentation index for AI Agents: https://ankole.agentbull.com/en-US/llms.txt # Architecture Ankole is an enterprise Agent Harness with a Company Brain. It runs on company infrastructure and gives models the context, authority, persistent execution, and feedback that company decisions require. An Agent can work for hours, use the shared Company Brain, act through browsers, terminals, files, and connected systems, and deliver a judgment that people can inspect and later outcomes can test. The Harness identifies each actor, applies access rules, restores long work, keeps context current, and carries corrections into later decisions. ## System map **Ankole system architecture** Enterprise channels, external events, identity providers, the Console, and AI providers connect to the control plane. The control plane schedules one or more Agent Computer Workers through RuntimeFabric and stores durable state in PostgreSQL and Agent Home. - Enterprise and external systems - Channels and external events — Messages · webhooks · schedules - Console and APIs — Operators · enterprise apps - Identity Providers — SSO · directory · organization - AI Providers — Models · vectors · images · web - Control plane · one logical management boundary - [SignalsGateway](https://ankole.agentbull.com/en-US/docs/signals-gateway/index.md) — Signal routing · message delivery - [Principal and AuthZ](https://ankole.agentbull.com/en-US/docs/principal-authz/index.md) — Identity · access · config · plugins - [AIGateway](https://ankole.agentbull.com/en-US/docs/ai-gateway/index.md) — Model selection · sessions · credentials - [Actor Runtime](https://ankole.agentbull.com/en-US/docs/actor-runtime/index.md) — Long sessions · wake · recovery - [Brain](https://ankole.agentbull.com/en-US/docs/brain/index.md) — World model · recall · Dreaming - [Background Agent Jobs](https://ankole.agentbull.com/en-US/docs/background-jobs/index.md) — Non-blocking · resumable · interactive - RuntimeFabric · live control, no durable facts - Execution · one or more Workers - [Agent Computer Worker pool · 1…N](https://ankole.agentbull.com/en-US/docs/agent-computer-worker/index.md) — Main Agents · Jobs · Automation Jobs · tools · Skills · sandboxes - Durability boundary - PostgreSQL — Identity · sessions · memory · Jobs · audit - Agent Home — Files · workspaces · deliverables The control plane stores state and decides how work must run. Workers provide the compute environment. This split keeps Agent work independent of one process or machine. One private deployment instance has one logical control plane and one or more Agent Computer Workers. The control plane manages identity, state, and scheduling. Workers provide the compute environment where Agents work. External chats, webhooks, and schedules enter through SignalsGateway. Identity Providers supply people and the organization directory. AIGateway provides one boundary for models, embeddings, reranking, images, and web capabilities. ## Control plane and Agent Computer Workers ### The control plane stores state and makes decisions The Elixir/OTP control plane owns the Console, Principals and access, system configuration, signal routing, Actor sessions, Brain, Background Agent Jobs, AIGateway, and Control Plane Plugins. All these modules use the same rule. State that changes a user-visible result goes to PostgreSQL before it drives execution or external delivery. A process can restart, but accepted messages, Job state, memory, and audit records must remain. OTP supervision trees give Agents, connections, and Jobs separate failure domains. If one execution branch hangs or crashes, the control plane can recover that branch without failing the complete deployment instance. ### A Worker is the Agent's work computer An Agent Computer Worker runs model loops, tools, Skills, browsers, terminals, and file operations, and it also executes automation job script runs. It does not create durable domain state on its own. It accepts work from the control plane and commits execution results back to it. One Worker can serve several Agents, and each Agent still runs in a separate lightweight sandbox. Give an Agent a dedicated Worker when it needs stronger isolation. Add Workers for more concurrency or to separate work with different security requirements. RuntimeFabric connects the control plane and Workers over ZeroMQ. It carries wakeups, steering, cancellation, progress, and execution results. It is a low-latency live channel, not a database. Recovery still uses PostgreSQL state after a connection fails. ## How one message becomes resumable work ### SignalsGateway receives the outside world Chat adapters, webhooks, and schedules first convert external events into a common signal. A signal routing rule selects the Agent, session, and channel or thread that must receive the reply. A group chat can process only messages that address the Agent, record unaddressed messages, or let the Agent decide when to intervene. The available modes depend on the chat platform and signal routing rule. SignalsGateway stores a received message and its source before it wakes the Agent. It also creates traceable delivery state before an adapter sends a reply. A temporary provider failure cannot confuse “what Ankole decided to send” with “what the provider accepted.” ### A trigger can wake an Agent or run a script Cron, Checkback, and webhook endpoints are the three triggers in one system. Each trigger wakes an Agent conversation by default, and each can instead bind an automation job: a deterministic script that the Agent writes. The trigger event stays the same; only the consumer changes. The script completes mechanical checks silently, and every run leaves an inspectable record. When judgment is needed, it sends an event back to the owner conversation through `emitEvent`, and the Agent verifies and acts. The model therefore never idles in a polling loop. See [Automation Jobs](https://ankole.agentbull.com/en-US/docs/automation-jobs/index.md). ### Actor Runtime manages long-running sessions Each active session is an addressable Virtual Actor. It has a mailbox, lifecycle, and recovery position. New messages and schedules can wake it, and it can receive added input, cancellation, or human intervention while it runs. Actor Runtime owns this long-running work identity. It creates a new activation and fence for each turn. A Worker can commit only the turn it currently owns. An old Worker cannot overwrite a newer result after recovery or retry. Streamed content is progress. Only messages, tool results, and state transitions that the control plane confirms and stores are facts. This keeps “the interface shows work in progress” separate from “the work is complete.” ## Brain: a world model that stays current Brain is not a vector database filled with chat excerpts. It maintains an evolving world model. New evidence can extend, revise, or retire earlier claims. When evidence conflicts, Dreaming records the contradiction for human review instead of silently rewriting the claims. Knowledge can come from conversations with the Agent, eligible group messages that nobody addressed to it, and registered file or URL Sources. All Agents in one instance share one knowledge space. Each protected passage, claim, and timeline event uses a `world`, permission-group, or Principal audience scope. A Source or channel records provenance; it does not grant access to the learned knowledge. During a turn, unified recall supplies the long-term context that the current work needs. Offline Dreaming organizes new evidence, finds patterns, grades earlier predictions, and flags conflicts for review. [Brain](https://ankole.agentbull.com/en-US/docs/brain/index.md) owns “what the world is like now.” [Skill Lessons](https://ankole.agentbull.com/en-US/docs/skill-lessons/index.md) preserve Agent-specific process guardrails learned from repeated work evidence. They accompany the relevant Skill without changing its source and retire when they no longer apply. This structure implements the homepage promise that an Agent learns the team's rules over time. Compounding does not mean a longer log. It means that the next job starts from better knowledge and a better method. Long-term memory is the user view of this system. Brain owns storage, Dreaming, and write authority. ## Background Agent Jobs: long work without blocking the main session A main Agent can delegate research, data analysis, file work, code changes, and Deep Research to a Background Agent Job. The main session remains available and can continue talking to the user. The control plane stores the Job lifecycle, and a Worker runs the Job. If that Worker stops, the system can dispatch the Job again and continue from durable state. A process exit does not delete the complete job. The main Agent and Job can continue to communicate. A Job can ask for input, return failures and final results, or stay silent when requested. When it waits for a person, it releases its execution slot and resumes after the answer arrives. Deep Research is an advanced use of this architecture. An Agent Plugin supplies the workspace template, Skills supply the research method, and a Background Agent Job supplies durable execution. Agent Home retains the research material and deliverables. See [Background Agent Jobs](https://ankole.agentbull.com/en-US/docs/background-jobs/index.md) and [Deep Research](https://ankole.agentbull.com/en-US/docs/deep-research-job/index.md). ## AIGateway: one boundary for AI capabilities AIGateway separates model capabilities from Agent execution. Main Agents, Jobs, Brain, and external API clients use the same boundary for LLM, embedding, rerank, image, Web Search, and Web Fetch Providers. Agent model profiles select models for Agent execution. Brain uses five instance-wide model settings in AppConfigure. The control plane stores Provider credentials in encrypted form, and AIGateway uses them for upstream requests. Agents and Workers receive only the model choices and call results that they can use. AIGateway supports calls that store no history and stateful conversations that can continue. It owns request conversion, stream events, tool results, context compaction, usage records, and final-result commits. Workers do not implement a separate lifecycle for each Provider. When the tool catalog is large, a model can search tools on demand through Tool Search, or submit one program that calls many tools inside a restricted sandbox and returns only the results. A Provider with native support passes these calls through, and AIGateway supplies the same capability in the gateway for every other Provider. One Provider can also hold several credentials as a pool, including account credentials such as a ChatGPT subscription. Failure attribution, retries, and usage records stay per credential. See [AIGateway](https://ankole.agentbull.com/en-US/docs/ai-gateway/index.md) and [Add an LLM Provider](https://ankole.agentbull.com/en-US/docs/adding-a-provider/index.md). ## Enterprise identity, access, and extensions Ankole represents people, Agents, and system services as Principals. An Identity Provider supplies Console SSO and synchronizes employees, contacts, and the organization directory. A chat channel sends and receives messages. These Providers can use different platforms. AuthZ decides at runtime from the Principal, permission group, resource, action, and condition. Access is not a sentence in a prompt, and a model cannot declare that it has a permission. Control Plane Plugins connect IdPs, chat channels, and other control-plane capabilities. Agent Plugins add tools and workspace templates. Skills describe how to do a type of work and can be limited to the main Agent or Background Agent Jobs. External MCP servers enter through Skills. A Skill declares its connection, the Worker generates a per-execution configuration and removes it when the execution ends, and the model never faces one resident list of every MCP tool. See [Principals and permission groups](https://ankole.agentbull.com/en-US/docs/principal-and-groups/index.md), [Signal routing rules](https://ankole.agentbull.com/en-US/docs/signal-bindings/index.md), [Agent Library](https://ankole.agentbull.com/en-US/docs/skills/index.md), and the [MCP server reference](https://ankole.agentbull.com/en-US/docs/mcp/index.md). ## Durability boundaries PostgreSQL stores durable domain facts such as identity, access, configuration, messages, sessions, Jobs, memory, delivery state, and audit records. Use these records to decide whether the system committed a result. Agent Home stores workspace files, tool output, and final deliverables. A single-host deployment can use a local or virtual disk. A Kubernetes deployment with several Workers needs NFS or another shared volume that supports `ReadWriteMany`. RuntimeFabric, Worker process state, and stream previews are rebuildable. They support live execution, but they do not replace PostgreSQL or Agent Home. ## Three deployment forms | Form | Control plane and Workers | Persistence | | --- | --- | --- | | **Docker Compose · recommended for one host** | One Linux, macOS, or Windows host runs the control plane and one Worker | PostgreSQL and Agent Home use persistent volumes on the host | | **Kubernetes · recommended for enterprise deployment** | One control plane connects to one or more Worker Pods and schedules them by node or security need | PostgreSQL plus shared `ReadWriteMany` Agent Home storage | | **Source installation** | The development environment runs the control plane and Worker separately | PostgreSQL and a local workspace configured for development | The logical boundary is the same for every form. The instance has one control plane and can add Workers horizontally. See [Quick start](https://ankole.agentbull.com/en-US/docs/quickstart/index.md#1-deploy-ankole) for the complete procedures. ## Five technical decisions | Decision | Problem it solves | | --- | --- | | **Virtual Actors carry AI work** | Give each session an address, mailbox, lifecycle, and recovery position | | **OTP supervision trees define failure domains** | Recover one Agent or connection branch without failing the complete instance | | **ZeroMQ carries live control** | Move wakeups, steering, progress, and backpressure while an Agent runs | | **Agent Computer Workers provide execution** | Keep model loops, tools, files, terminals, and sandboxes near the workspace | | **The PostgreSQL ledger stores facts** | Make messages, Jobs, memory, decisions, and committed operations resumable and auditable | These decisions support one result. An Agent can work for hours, accept new information while it runs, fail and recover independently, and leave a trace for each committed action. For the longer runtime argument, read Why OTP Is a Better Runtime for Multi-Agent Orchestration.