The
A GrailAOS™ solution is a set of versioned text documents that declare what a business does, and a checks all of it before anything runs. This page explains it in concepts, without the syntax: the engine is proprietary.
What a solution is
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.
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
Each piece declares part of the business and names the other pieces it needs; the compiler checks those names.
What each piece declares
Names the piece where each conversation comes in.
They talk through the channels, use tools and knowledge, and delegate to other agents.
They chain steps, branches and decisions; the ones that run on their own add loops over lists, parallel branches, other workflows and approvals.
The built-in ones, HTTP integrations, the ones from servers and the ones from the 's startup code.
Limit Several built-in tools depend on configuration or on the deployment's startup code.
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.
Workflows send them in their message or template steps.
They run workflows, campaigns, reports and data ingestion on their schedule.
They live inside the agents and workflows they test.
Each 's own data, in the shape declared in the solution.
Limit The collection tools are enabled by the deployment's startup code.
What the owner turns on or off together, without publishing a release.
The manifest
An agent
A workflow
A scheduled task
An owner feature
A tool
Why text
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.
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.
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.
Each document declares the specification version it was written for: the 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.
The compiler
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 todayA report with every error it found
Measured in the repositories
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 , and when the runtime starts.
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.
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.
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.
Diagnostics
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.
Fixes
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
PartialRuns todayAgainWhat the compiler returns goes back to the model, which makes its fixes from that.
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.
Testing
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 todayTest 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.
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.
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.
What cannot be compared word for word is evaluated by a judge model, with configurable voting and a spending cap per run.
Questions
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.
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.
Runs todayMCP as a client
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 , its tools are pinned in the solution, and the connection goes through the same network guard.
Limit Only tools, not resources or ; if the server changes one, by default the call goes ahead with a warning; the connection belongs to the account.