> For the complete documentation index, see [llms.txt](https://docs.visdom.virtuslab.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.visdom.virtuslab.com/visdom-orchestrator/the-orchestrator-in-the-platform.md). # The Orchestrator in the platform The execution engine: definitions, drivers, triggers and oversight. The Orchestrator is the platform's execution engine: a Kubernetes controller that turns flow definitions into supervised, auditable executions. ## The definition model Four object types, all versioned through a draft-to-publish cycle: * **Agent**: the definition of a step's executor: runtime container image, model, declared inputs and outputs (data ports), the list of permitted MCP servers together with a method allowlist, filtered secrets (an agent sees only the secrets explicitly assigned to it), egress rules, system prompt and context document. * **Deterministic tasks**: scripts run as an explicit element of the process. They automate the work that does not require a model to decide anything, and they make that part of the flow predictable. * **Flow**: a graph of nodes joined by data and control ports. Node types: *Trigger*, *Agent* (with an `on_failure` policy), *Decision* (branching on CEL predicates), *Approval* (a human consent gate: approver role, TTL, expiry behaviour, approve and reject branches), *Loop* (while and for-each with an iteration limit and concurrency control), *SubFlow*, *Parallel* with a join gate, *Terminate*, *Output*. * **Container / MCP**: the catalogue of permitted runtime images and tool servers, with image versions pinned. Definitions can be managed visually in the graph editor, through the API, or as **configuration in code**: YAML definitions versioned in a Git repository, in either "changes through a pull request" or "mirror synchronisation" mode. Configuration changes are then reviewed the same way code is. ![A flow as a graph: triggers, agents, decisions, approvals and loops wired port to port](https://1374978342-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FOeaiyW8tyqPn9AEYJrgX%2Fuploads%2FDntc5ZKJ6ATmbkZJwnox%2Fflow-graph.png?alt=media) The mechanics of that graph (port names, CEL expressions, loop variables) are in [Flows: nodes, ports and edges](/visdom-orchestrator/user-guide/flows-nodes-ports-and-edges.md). ## The execution model Every agent step runs as a **separate Kubernetes job in a dedicated namespace**: one agent, one pod, with its own resource budget, its own identity and its own network rules. The agent pod talks to the controller only over authenticated channels (an Ed25519-signed token, an mTLS sidecar), pulling secrets just in time and reporting events, outputs and token metrics. Steps of a flow share a persistent workspace volume holding the repository clone and intermediate artefacts. ## The coding-agent driver layer The Orchestrator separates the definition of a step from the executor that runs it. The same flow can be executed by any of the supported drivers (**Claude Code, Codex and IBM Bob** among them) or by the platform's own minimal agent loop (a native Anthropic Messages API driver and an OpenAI Chat Completions-compatible driver with a configurable endpoint, which covers LiteLLM and any other OpenAI-compatible proxy). Changing model or vendor is a change to an agent definition, not a rebuild. ![An agent definition: driver, model, container, resources, and the MCP servers the agent may call](https://1374978342-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FOeaiyW8tyqPn9AEYJrgX%2Fuploads%2FbPRjbj259MaZtMYApcEE%2Fagent-definition.png?alt=media) ![The driver layer between an agent definition and a model vendor](https://1374978342-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FOeaiyW8tyqPn9AEYJrgX%2Fuploads%2FyqovP2qiakuNKuMqIiMz%2Fdriver-model.png?alt=media) The fields behind that screen are covered in [Configuring an agent](/visdom-orchestrator/user-guide/configuring-an-agent.md). ## Triggers Three mechanisms: * **Inbound webhooks**: an endpoint on an integration adapter, with signature validation, a CEL event filter (for example "only bugs from project X, priority at or above medium, labelled `ai-fix`"), a retry queue with exponential backoff, a dead-letter queue and a circuit breaker. * **Cron schedule**: for example a periodic "is there anything to do?" poll against a queue. * **Manual execution** from the UI or API, with the option to supply additional context, which is also how an agent is re-run for the same ticket with a further instruction. {% hint style="info" %} **CEL** is the Common Expression Language, a small sandboxed expression language, used here for event filters, branch predicates and loop stop conditions. {% endhint %} ## Human in the loop Four oversight mechanisms: *Approval* nodes with versioned acceptance policies; mid-execution questions (an agent can ask a human a question while working and wait for the answer); comments and discussion threads on executions; and chat sessions attached to a run, so an operator can refine instructions while it is in progress. Any execution can be **cancelled**, which discards work in progress and leaves the working branch unpublished, and a completed or interrupted one can be **re-run with additional context**. ![Human in the loop: an approval gate stopping a run until a named role answers](https://1374978342-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FOeaiyW8tyqPn9AEYJrgX%2Fuploads%2FOpoPCkOcMWkGPR8lpyyL%2Fhuman-in-the-loop.png?alt=media) How those four differ in practice, and which one to reach for, is in [Humans in the loop](/visdom-orchestrator/user-guide/humans-in-the-loop.md). What ships today and what does not is in [Known limitations](/visdom-orchestrator/user-guide/known-limitations.md). ## The reference issue-to-pull-request flow The platform ships a cryptographically signed catalogue of ready agents and flows (22 agent definitions, among them research, implementation, test authoring, code review and triage), including the automated issue-to-PR flow: issue → analysis and solution design → implementation → open a pull request → review-and-fix loop (a subflow with an iteration limit and a CEL stop condition) → tests → quality gates → notification. That flow is the starting point of a deployment and is adapted to the organisation's own conventions: branch naming, commit message and pull request templates, reviewer assignment, and marking a pull request as AI-generated. ## What that looks like on an ordinary day One orchestrator runs every flow end to end, watching, correlating, planning and preparing, with the same gates, the same approvals and the same audit trail. People step in only where judgment matters. | Scenario | Starts with | Ends with | | --------------------- | ----------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------ | | **Incident response** | Alerts fire at 02:14, error rate spiking on production | 02:31 root cause pinned and a fix run through every gate; the morning standup reviews a green, fully traced pull request | | **Regression hunt** | The checkout API starts failing twice as often | Events correlated across services in two minutes, the breaking deploy identified, a proposed fix waiting on one approval | | **Bug reproduction** | Support escalates a recurring, hard-to-pin failure | Replayed from logs and telemetry, a failing test reproduces it, the fix ships with the regression test attached | | **Security patch** | A CVE lands in a dependency you run | Affected components mapped, dependency bumped, full gate suite run, a verified upgrade ready to merge within the hour | | **Migration** | A framework deprecates an API your repository calls in 214 places | Call sites mapped, the mechanical 95% migrated with gates run on every change, six call sites left for human judgment | | **CI hygiene** | A flaky test blocks every other merge | The test quarantined, history bisected, the race condition pinned, a deterministic fix landed | ## Where this sits in Visdom Context Fabric decides what an agent knows, the Orchestrator decides what it may run, and AI Tracing records what it did. --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter: ``` GET https://docs.visdom.virtuslab.com/visdom-orchestrator/the-orchestrator-in-the-platform.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.