Ship the Agent Specs as Code, Not as Database Rows

When you build an agent platform, the first instinct is to treat agent definitions as application data. Users log in, edit a text field describing what the agent should do, hit save, and the new behavior is live. It feels clean. It is also a trap.

We went the other direction. Agent specs live in a git repo, not in the app's database. Every agent is a YAML file. The studio reads that repo as its source of truth. Change the model from Opus to Sonnet in the file, commit it, and the running system reflects the change. The repo is the contract, and the app is just an execution surface over it.

This matters for one reason that database rows can never give you: review. A repo with PR-only merges means no one can accidentally destroy a working agent. A non-technical operator can spin up a draft and iterate fast, but the moment an agent is marked production, changes go through a pull request. Someone has to say yes. That is not bureaucracy. That is the difference between a demo and a system you can run with fifteen people touching it.

The part people miss is that the gatekeeper does not have to be an engineer. A YAML spec is not code. It is a readable description of intent, tools, and steps. A customer success lead can look at a diff and decide whether the change is sane. That decouples approval authority from engineering capacity, which is exactly what you need when agents start breaking out of engineering and into the rest of the org.

The deeper principle: if it is not in version control, it is not operationalized. The same discipline that made software deployable makes agents deployable. This is why agents are software, not prompts: the prompt is the cheap part. The factory around it, the review, the history, the source of truth, is the actual product.

If you are building an internal agent platform, start by asking where the definitions live. If the answer is a text box, you have a demo. Put them in a repo and you have something you can trust at scale.