Explanation

Trax and AI agents

An AI agent is one more client of a process, like a person in a browser or a script. It is the one most likely to try a move it should not make, and the one least likely to follow rules written only in its prompt. This page explains where Trax sits around an agent. It assumes Trax in five minutes.

Every client gets the same rules

One workflow, defined once on the server, driven by four kinds of client. Web users get steps in order and valid data at each step. Schedules and queues get retries, dead letters and a record of every run. Scripts and services in any language get the same rules. AI agents get only the moves they are allowed, and evidence the server reruns.

Because the rules live on the server, every kind of client gets the same ones. People in a browser get the steps in order and their input checked, through the TypeScript client Trax generates. Scheduled and queued work runs when you say; Trax queues it, retries it as often as you allow, dead-letters it when it runs out of retries, and records every run. Scripts and services call the same GraphQL API Trax serves, in whatever language they are written in, and the rules hold for them too, including the ones their language cannot check. AI agents can only make the moves you declared, and when a move needs evidence, a check you write as a train reruns it on the server before Trax accepts the move.

Where Trax sits around an AI agent

Two layers around an AI agent. The sandbox lets the agent run code, edit files, call tools and read data, but nothing in it reaches real systems. The only way out is through Trax, which checks that the move is allowed in this state, allowed for this agent, and that its evidence holds up, by rules you write. Only verified moves reach the real systems: tickets, orders, data.

AI agents are the most demanding client. Two layers do two different jobs. A sandbox limits what an agent can do: it can run code and make a mess, but only in its own box. Trax limits what it can change: its only way out is a small set of declared moves, each checked against the state, the agent's role, and evidence the server checks itself rather than takes on the agent's word. The sandbox is not Trax; you run it with whatever tool you already use. Inside Trax, you write the rules and the evidence checks, and Trax makes sure the agent cannot get around them. Most agent setups have the first layer and improvise the second with instructions in a prompt.

The Board sample

The Board sample. A bug ticket moves through five lanes, each owned by one client: Triage by triage-bot, Reproduce by repro-bot, Fix by fix-bot, QA by qa-bot and Review by Sam, a person. The ticket is in Fix, held by fix-bot. An agent submits its evidence, a check train the sample's author wrote reruns it on the server, and the ticket moves only if the check accepts it; otherwise it stays put.

Board is a Trax sample where bots move bug tickets through lanes. Four scripted bots and one person each own a lane, with keys of their own. A bot never moves a ticket itself: it submits evidence for its lane, a check train on the server reruns that evidence against the rules, and only the train's verdict moves the ticket. The sample's author wrote one check train per lane, as ordinary trains; building your own agent workflow, those are the trains you would write. Trax is what makes the verdict the only way a ticket moves. The last lane belongs to a person, so human sign-off is just another lane with a role. The bots are scripted, not language models, but they talk to the server the way an AI agent would.

What an agent cannot do there, and what it gets back:

The agent tries toThe server answersBecause
Claim a ticket another agent holdsALREADY_CLAIMEDa claim needs a ticket nobody holds
Approve its own fixFORBIDDENonly a reviewer may approve
Close a ticket as not reproducible too earlyGUARD_FAILEDclosing needs at least two cases the server ran
Claim work when none is waitingNOTHING_TO_CLAIMthere is no ticket in its lane

An agent cannot report its own test results either: the cases on record are written only by the server's check.

Where to go next

You want toRead
Run the Board sampleBoard
Decide between a train and a machine for a stepTrain or machine
Write the rules that say who may send a moveAuthorization rules
Point a coding agent at these docs/llms.txt, one file that lists every page