# Keep your agents in your code

> Keeps each agent's prompt, model, script, functions and widgets as files in your repo, and has your coding agent apply them to Mindset as versions.

**Skill for your coding agent:** [`mindset-import-agent/SKILL.md`](https://docs.mindset.ai/skills/mindset-import-agent/SKILL.md)

Each agent is a folder of files in your repo, reviewed in pull requests like the rest of your code. Your coding agent applies that folder to Mindset through the `mindset-admin` MCP server, where the agent is tested, versioned and run, and a test in CI fails when a change in the files was never applied. You keep the agent in your code without building the plumbing that runs it.

## Ask your coding agent

```
Keep our Mindset agents in this repo under agents/. Write the invoice exceptions agent's prompt fields, model, resources and script there as files, apply them to Sandbox through the Mindset MCP server, then read the agent back into the repo and add a test that fails when the files and that read-back differ.
```

Skill: [mindset-build-agent](https://docs.mindset.ai/skills/mindset-build-agent/SKILL.md)

## What the repo holds

One folder per agent, and one for the connections they share:

```text
agents/
  connections/
    finance-system.json   the connection and its operations
  invoice-exceptions/
    agent.json            handle, name, model, availability, resources, idempotencyKey
    prompt/
      purpose.md
      personality.md
      background.md
      policy-rules.md
      output-formatting.md
    script.json           only if the agent needs a script
    functions/            one file per function
    widgets/              one file per widget
    tests.json            its behavior tests
    live.json             the last read-back from Mindset
```

Each file holds the fields the MCP tools take, under the same names, so nothing is translated on the way in. No file holds a credential: a person enters each key on a capture page, in each environment.

## How a change goes live

### 1. Change the files in a pull request

Edit a prompt file, a function or the script, and review it like any other change.

### 2. Apply it

Your coding agent reads the live agent, compares it with the files and makes only the calls that differ. Every change to a prompt field or the model is a new [version](https://docs.mindset.ai/docs/versions-and-going-live), so unchanged files make no calls.

### 3. Test it

Run the test parameters of its script and functions, then its behavior tests. See [Test before it goes live](https://docs.mindset.ai/docs/test-before-it-goes-live).

### 4. Activate it

On an agent people already use, your coding agent stages the change. A person activates it on **Versions & Availability** once the tests pass.

### 5. Read it back

Your coding agent saves the live agent to `live.json` and commits it. A test compares the files with `live.json`, so a prompt edited in the repo but never applied fails the build.

> **Tip:** Keep each agent's `idempotencyKey` in `agent.json`. If a create fails, your coding agent retries with the same key, so a retry can't make a second agent.

## What you decide

- **Where the agents live.** Next to the app code that calls them, so one pull request changes both.
- **Studio edits.** A change made in the Studio isn't in your files until your coding agent reads the agent back. Read back before each change.
- **Who activates.** Your coding agent stages a change to a live agent and never activates it itself.
- **When Production gets it.** The same files, applied to Production after Sandbox passes. See [Move it to Production](https://docs.mindset.ai/docs/move-it-to-production).

Creating the org and its API keys, entering credentials, approving writes and opening an agent to people all stay with a person. [Work with the MCP server](https://docs.mindset.ai/docs/work-with-the-mcp-server) lists each one.

## Done when

- Every agent your app calls has a folder in the repo.
- Applying unchanged files makes no calls.
- The test comparing the files with `live.json` runs in CI and passes.

## See it working

The Guide on this site is kept this way. Its prompt fields, script and resources are files in the docs repo, every change is applied through the MCP server and staged, and the build fails if a change to the files was never applied.