# One YAML File Should Define Everything an AI Agent Is Allowed to Do

The industry has spent the last two years building increasingly sophisticated ways to give AI models tools. We have function calling, ReAct loops, tool-use frameworks, and multi-agent orchestration libraries.

Very few of them treat the *full contract* of an agent as a first-class, reviewable artifact.

## What a real agent contract looks like

When you send an agent to do work, it needs more than a system prompt and a list of functions. It needs:

- Who it is (persona)
- What repositories or data sources it can touch
- Which tools are actually allowed (not just "it has the MCP server")
- Which secrets it receives (by name, not by dumping the whole environment)
- How long it is allowed to exist
- Whether it should remember anything between runs
- What "done" looks like for this particular mission

Most current setups scatter this information across prompts, environment variables, wrapper scripts, and whatever the developer happened to remember when they started the process.

That is not a contract. That is vibes.

## Why YAML works surprisingly well here

YAML is not exciting. That is exactly why it is good for this job.

A single YAML file can express the entire mission contract in a way that is:

- Human readable and reviewable in a pull request
- Machine parseable without a complex DSL
- Version controllable alongside the rest of your infrastructure
- Easy to diff when requirements change

Here is a real example of a researcher agent:

```yaml
name: researcher
description: Read-only research analyst. Reads, reasons, keeps notes in memory.
bot: secret://research-bot
ttl: 30m
model: sonnet
persona: >
  You are a research analyst. You read the material provided and your own notes,
  reason carefully, and write findings to your memory file (notes.md) so the next
  run continues where you left off. You do not change code or send anything.
secrets: [anthropic]
mcps: [notion]
skills: [summarise]
repos: []
tools:
  publish: false
output: chat
persist: true
```

Everything an auditor or teammate needs to understand the agent's scope is right there. No hidden environment variables. No "it just has access because the container has the token."

## The recipe is the product

One of the most powerful ideas in the RAID approach is that a new kind of agent should not require new code. It should require a new recipe.

Want a different researcher that can also write to a specific Google Doc? New YAML file. Want a dev agent that is only allowed to touch the frontend repo and can only use `git` and `npm` (no arbitrary shell)? New YAML file with tighter tool restrictions.

This changes the review process. Instead of reviewing "the agent code," you review a small, explicit contract. That is a much smaller and more meaningful diff.

## Secrets by name, not by accident

A very common anti-pattern is to give the agent the entire environment or a broad API key. In a recipe you declare:

```yaml
secrets: [anthropic, github]
```

The runtime resolves only those named secrets and injects them for *this* mission only. The control plane itself never sees the values.

This is a small detail that has massive implications for blast radius and auditability.

## Policy is part of the contract

Most frameworks bolt policy on after the fact ("we'll add guardrails later"). In a proper recipe, allowed actions and restrictions are declared up front.

You can say an agent is allowed to read and write in the workspace but not call `shell`, or that it can use `git` and `vercel` but not arbitrary commands. These constraints are part of the definition of the agent, not an afterthought.

## What this enables for teams

When every agent is defined by an explicit, versioned recipe you get:

- Real code review for agent capabilities
- Easy rollback ("revert to the previous recipe")
- Clear documentation for what each agent is *supposed* to be able to do
- The ability to create specialized agents without forking core logic

This is very different from the "one giant agent with access to everything" pattern that many teams accidentally create.

## The alternative is technical debt

If your agent capabilities live only in prompts, ad-hoc scripts, and whatever was in the environment when someone last ran it, then every change is risky and every audit is painful.

Treating the full contract as data (in this case, YAML) makes the agent's identity something you can reason about, review, and improve over time.

That is the difference between "we have an AI agent" and "we have a governed capability delivered through an agent."