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 with Tembo Agent Studio. Agent definitions live in a Git repo as the source of truth. A Pydantic agent's spec is a YAML file the studio reads as its draft. The repo is the contract for changing the definition; the application still needs a database for runtime state and promoted stable snapshots. Git and a database solve different parts of the problem.[1] Disclosure: I am Tembo's founder and CEO.
This matters because review becomes a visible workflow. A branch and pull request let someone inspect a proposed change before it reaches the default branch; required approvals depend on the repository's rules. You can build similar controls around database edits, but then you have to build and maintain them. I would rather give operators a familiar diff and a clear place to say yes.[2]
The current Studio implementation separates that review from deployment. Authoring defaults to PRs, while an admin can choose YOLO direct commits where branch protection permits them. An owner or admin then promotes a draft to a stable snapshot. Automated runs default to stable after the first promotion, though schedules can opt into draft. Those are explicit policies to configure, not guarantees that follow from putting a YAML file in Git.[3][1]
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, who can change them, and which version a scheduled run will use. Put the definitions in a repo, make the review policy explicit, and give operators a way to test and promote changes. That is a foundation for trust you can inspect.
Key takeaways
- Agent definitions belong in a version-controlled repo, not as editable rows in an application database.
- PR review gives non-technical contributors a visible change history and an explicit approval process.
- A YAML spec is reviewable by non-developers, which decouples the gatekeeper role from engineering.
FAQ
Why not let users edit agent definitions directly in the app?
An application can build history and review around database edits, but a Git repo supplies an established change workflow. Use it as the source of truth for definitions while retaining runtime state and stable snapshots where they belong.
Doesn't requiring PRs slow down iteration?
PR review adds a deliberate approval step. Agent Studio defaults authoring to PRs and optionally permits direct commits; promotion to a stable runtime version is a separate decision. Configure both policies rather than assuming a production label enforces review.
Sources
Related Essays
Agents Are Software, Not Prompts
The industry treats agents as a new category. They are not. Agents are software, and the same engineering principles that have always mattered still apply.
Prototype on MCP, Productionize in Code
Pure LLM execution is a prototyping medium, not a production architecture. The $15 agent run becomes a $1 run when repeated reasoning gets hardened into code.
The Agent Is the Primitive, Not the Automation
Automations bundle trigger, prompt, tools, and model into one flat object. That works at five. It falls apart at fifty. The agent has to become its own primitive.