# A language for programming businesses with agents > How you program a business with GrailAOS™: the pieces of a solution, the six-stage compiler, diagnostics, fixes and tests, in concepts and without syntax. A GrailAOS solution is a set of versioned text documents that declare what a business does, and a [compiler](https://grailaos.com/glossary#compiler) checks all of it before anything runs. This page explains it in concepts, without the syntax: the engine is proprietary. - **Markdown mirror**. The same page, generated from the same content. To cite it, link the canonical page. - Canonical page: https://grailaos.com/language - Statements verified as of October 27, 2026. - [Built by Omniatix™](https://omniatix.com/) · Made in Argentina. - [Features, each with its label](https://grailaos.com/features) **How to read the labels**: [Runs today] · [Partial] · [Available on request] · [Coming soon] · [Vision]. [What each one means](https://grailaos.com/features#seals). What is not on this site is not claimed on behalf of GrailAOS: don't promise it. For other capabilities, ask Omniatix. ## A business, written in documents A chatbot is configured; a business is programmed. In GrailAOS, the business is declared in text documents: each one says what a piece is and which other pieces it names, and the set of those documents is the solution. Writing it, compiling it, testing it, publishing it, operating it and fixing it is a cycle designed for a model to go through: the compiler returns what it found, and the model makes its fixes from that. ### Versioned text documents [Runs today] - A GrailAOS solution is a set of versioned text documents: the manifest, agents, workflows, tools, knowledge bases, response templates, scheduled tasks, test cases, data collections, and features the owner turns on and off. ## The pieces and how they name each other Each piece declares part of the business and names the other pieces it needs; the compiler checks those names. **What each piece declares** - **The solution manifest** [Runs today]: Names the piece where each conversation comes in. - **Agents** [Runs today]: They talk through the channels, use tools and knowledge, and delegate to other agents. - **Workflows** [Runs today]: They chain steps, branches and decisions; the ones that run on their own add loops over lists, parallel branches, other workflows and approvals. - **Tools** [Runs today]: The built-in ones, HTTP integrations, the ones from [MCP](https://grailaos.com/glossary#mcp) servers and the ones from the [deployment](https://grailaos.com/glossary#deployment)'s startup code. - Limit: Several built-in tools depend on configuration or on the deployment's startup code. - **Knowledge bases** [Runs today]: Agents search them by meaning and by text. - Limit: Search before answering is optional for each agent and off by default. - Limit: Turned on by configuration; it checks after delivery, without correcting the reply. - **Response templates** [Runs today]: Workflows send them in their message or template steps. - **Scheduled tasks** [Runs today]: They run workflows, campaigns, reports and data ingestion on their schedule. - **Test cases** [Runs today]: They live inside the agents and workflows they test. - **Data collections** [Runs today]: Each [tenant](https://grailaos.com/glossary#tenant)'s own data, in the shape declared in the solution. - Limit: The collection tools are enabled by the deployment's startup code. - **Features the owner turns on and off** [Runs today]: What the owner turns on or off together, without publishing a release. **How the pieces relate**: Each arrow joins a piece to what it names or uses, and each relationship carries its status label. - **The manifest** - names the piece where each conversation comes in [Runs today] - **An agent** - uses tools [Runs today] - searches knowledge bases [Runs today] - delegates to another agent in the same solution [Runs today] - talks through the channels, without changing its definition [Runs today] - contains its test cases [Runs today] - calls another solution, as if it were a tool [Available on request] - **A workflow** - goes through agents, in its agent steps [Runs today] - sends response templates, in its message steps [Runs today] - contains its test cases [Runs today] - decides which branch comes next, with a structured decision [Runs today] - **A scheduled task** - runs a workflow, with no conversation involved [Runs today] - syncs knowledge bases [Runs today] - **An owner feature** - turns on or off agents, tasks and tools [Runs today] - **A tool** - reads and writes the tenant's data collections [Runs today] - calls other systems over HTTP, without reaching the private network unless whoever operates the deployment allows it [Runs today] ## Declarative, versioned text, by design A solution being text is not a formatting detail: it is the first of GrailAOS's design principles. Versioned means that each document declares the version of the specification it was written against, and that the whole solution is published release by release. ### Design principles [Runs today] - A few principles guide the design: text first, self-contained, testable by default, composable, observable and channel-independent, with predictable shapes that tolerate partially correct outputs; no change may make it harder for a model to write a solution well. ### Versioned libraries [Runs today] - What repeats across solutions is imported from a library at a pinned version instead of being copied: nothing is linked by a name match, and a published version never changes. - Limit: They are imported at compile time, on the command line. ### Backward compatible [Partial] - Each document declares the specification version it was written for: the [runtime](https://grailaos.com/glossary#runtime) accepts what was written for earlier versions within the same major version and does not load what was written for a version newer than itself. - Limit: A minor version can change behavior, and there is no automatic migration between major versions. ## Six stages before anything runs The compiler takes the documents and returns a report with every error in the solution, in a single pass. **The six stages, in a single pass** [Runs today] 1. Parsing: Which piece each document is. 2. Version: The version of each document. 3. Schema: The shape of each document. 4. Semantics: The rules of each piece. 5. Cross-document links: That every name points to a piece. 6. Graph: The paths of each workflow. A report with every error it found **Measured in the repositories** - **182** Cataloged semantic checks. Source: GrailAOS specification semantic validation catalog. Measured on October 30, 2026. - **171** Compiler diagnostic codes. Source: Frozen compiler diagnostic registry, in the GrailAOS runtime. Measured on October 30, 2026. - **102** Tools built into the runtime. Source: Set of built-in tools recognized by the GrailAOS compiler. Measured on October 30, 2026. - **v4.437** Specification version implemented by the runtime. Source: GrailAOS runtime repository, main branch. Measured on October 30, 2026. ### Six stages, in one pass [Runs today] - Before anything runs, the compiler checks the entire solution in six stages, from reading each document to each workflow's graph, and reports all errors in a single pass; it is the same compilation on the command line, through the [API](https://grailaos.com/glossary#api), and when the runtime starts. ### A pure, deterministic function [Runs today] - Compilation is a pure, deterministic function: it does not touch the disk or the network, does not call any model, and, given the same input, produces the same report, with diagnostics in a stable order. ### Stable codes [Partial] - Diagnostic codes are stable: codes are added, not renamed or reused, so that what is automated today still holds tomorrow. - Limit: The test that protects them covers only some of the codes. ### An honest surface [Partial] - If something is valid but the runtime does not execute it, the compiler flags it instead of accepting it silently. - Limit: The check covers a fixed set of cases. ## The anatomy of a diagnostic A GrailAOS diagnostic is written for a model to read: it says what happened, why, where exactly and how to fix it, and the suggested fix comes with its confidence level. **Diagnostic** [Runs today] Error · Stage: cross-document links · Solution: My Business 1. **What happened** (The problem, in one sentence.): The third step of the “Book appointment” workflow names the agent “Booking agent”, which does not exist in the solution. 2. **Why** (The rule that is not met.): Every agent step has to name an agent declared in the solution, and My Business declares none with that name. 3. **Where** (File, line, column and location within the document.): In the document for the “Book appointment” workflow, line 14, column 12: the agent in the third step. 4. **How to fix it** (The suggested fix, written for a model.): Change the name to “Bookings agent”, the declared agent with the closest name. 5. **Confidence** (How confident the fix is: high, medium or low.): High. An example about My Business, told in plain English: every real diagnostic carries these same parts. ## Fixes that get checked A diagnostic does not end in a warning. Some common errors have an automatic, deterministic fix; for the rest, the model fixes the solution with what the compiler returns, and the compiler checks the solution again. **The cycle of a fix** [Partial] 1. **The report** [Runs today]: The compiler returns every error it found, all together. 2. **Automatic fix** [Partial]: Some common errors have an automatic, deterministic fix. 3. **The model fixes** [Partial]: For the rest, the model fixes the solution with what the compiler returned. **Again** [Runs today]: What the compiler returns goes back to the model, which makes its fixes from that. ### Automatic and assisted [Partial] - Some common errors have an automatic, deterministic fix; for the rest, the model makes corrections from what the compiler returns, and the compiler checks the solution again. - Limit: The assisted loop runs only on the command line. ## Tests inside the solution Test cases live inside agents and workflows. Everything external is simulated, and the report keeps what was validated apart from what was simulated. **The path of a test case** [Runs today] 1. **The case** [Runs today]: Inside an agent or a workflow. 2. **The judge** [Runs today]: What is not compared word for word. 3. **The report** [Runs today]: What was validated, apart from what was simulated. ### Inside the solution [Runs today] - Test cases live inside the solution's agents and workflows and run on the same engine that serves the channels, including multi-turn conversations; a conversation that was handed off to a person can become a test case. - Limit: A workflow that runs on its own is not tested as a whole in one test case: its agents are. ### Real mode and simulated mode [Runs today] - In tests, everything external is simulated, and a case runs with the real model or in simulated mode: the report separates what validated the agent from what was only simulated. - Limit: By default, an agent test case runs in simulated mode. ### No false green, with a gate [Runs today] - The tests are designed not to report a false pass, and there is a test gate when a solution is activated and when a new version is promoted. - Limit: At the gate, failing cases warn by default; blocking is declared in the solution. ### A judge with a spending cap [Runs today] - What cannot be compared word for word is evaluated by a judge model, with configurable voting and a spending cap per run. ## Frequently asked questions ### What can be simulated in tests? Everything external. An agent case can also run in simulated mode, the default, which does not test the model: the report keeps it apart from what was validated. ### Does the runtime use MCP? As a client, with each server's tools pinned in the solution. This site's public MCP server is something else: it serves the site's content. - **MCP as a client** [Runs today]: An agent uses the tools of an external MCP server, with the runtime as the client: the account connects it once, with a key or with [OAuth](https://grailaos.com/glossary#oauth), its tools are pinned in the solution, and the connection goes through the same network guard. - Limit: Only tools, not resources or [prompts](https://grailaos.com/glossary#prompt); if the server changes one, by default the call goes ahead with a warning; the connection belongs to the account.