Agents & Agent Instructions
What "the agent" actually is, and how Agent Instructions steer how every agent behaves across your workspace.
When we say "the agent," we mean the AI that does the work inside a sandbox: it reads files, runs commands, calls tools, and produces changes. There is no roster of named agents to create or manage. An agent is the combination of three things: the model it runs on, the tools it is allowed to call, and the instructions it follows.
This page covers what an agent is and how you steer its behavior. The other two pieces have their own pages: the model is an AI runtime, and the tools are governed by approved actions. For the how-to of editing, drafting, versioning, and overriding instructions per sandbox profile, see Agent Instructions in Work with agents.
What an agent is
An agent is not a persona you configure ahead of time. It is the runtime that executes a Flow step or a chat turn, and it comes together at the moment of the run from three inputs.
- A model, chosen by your AI runtime settings.
- A set of tools it may call, bounded by approved actions.
- Its instructions, which is the subject of the rest of this page.
Every agent runs inside an isolated sandbox and stops at the checkpoints you set. There is nothing to spin up or tear down by hand.
Agent Instructions
Agent Instructions are the standing guidance every agent follows. Think of them as the operating manual that sits behind every run: how your team writes plans, the conventions to respect, the tone for a review, the things to avoid. You write them once, and every agent reads them.
Instructions resolve from three layers, and the most specific one wins:
- The platform default that Disco Parrot ships, which is the baseline if you change nothing.
- Your workspace override, which your team writes to encode how you work.
- An optional per-sandbox-profile override, for when a particular profile (say, one pointed at a different stack) needs different guidance.
These layers are not stitched together. The most specific layer you have set is used in full, and the ones beneath it stand in only when the layer above is empty. Set nothing and every agent reads the platform default. Add a workspace override and that text becomes the guidance every agent follows. Point a sandbox profile at its own instructions and a run on that profile uses those instead, leaving every other run on the workspace text.
When an agent runs, the platform resolves the effective instructions and records which layer they came from, so there is never any doubt about what guidance was in force. The same resolved instructions reach not only the main agent but the subagents a run fans out to, so the guidance holds across the whole run rather than only its first turn.
A platform policy section is always applied on top of your instructions and cannot be overridden. It carries the safety and operating rules the platform depends on, so your customizations extend the guidance rather than removing the floor beneath it.
Agent Instructions are not the same as a skill. Instructions are standing guidance every agent reads on every run: your conventions, your guardrails, your house style. A skill is a named prompt for one kind of work that you invoke when you want it. Instructions set the constant; a skill sets the task. The two stack, so when a skill runs the agent follows your instructions and the skill's prompt together.
These pieces are layered in a fixed order. The platform policy sits at the top and cannot be moved or removed. Your Agent Instructions come next, so your conventions govern everything below them. The prompt for whatever skill is running comes after that, as the specific task for this run. The result is predictable: the safety floor always holds, your standing guidance always applies, and the skill decides only the work in front of it.
The workspace-wide instructions live on the Agent Instructions settings page. A per-profile override lives on the sandbox profile itself, under its own Agent Instructions tab, so the profile carries its guidance wherever it runs. Profile scope is the finest grain: there is no separate per-Flow or per-step instruction set, which keeps the model simple to reason about.
Editing instructions
You start from the platform default and customize it, which creates your workspace override that you then edit in place. The default is read-only until you customize, so you always know whether you are looking at the shipped baseline or your own text. A profile override works the same way on its own tab.
Editing is a privileged action. Reading the instructions and changing them are separate permissions, so you can let the whole team see the guidance while only a few people are allowed to rewrite it. The body has a generous size limit in the tens of thousands of characters, which is far more than a working manual needs and a guard against runaway content.
If you later remove a workspace or profile override, that layer falls back to what it inherits from the layer above, and the reset is captured as its own version. The history shows a rollback as plainly as it shows an edit.
Instructions can be written with the agent's help. You can ask it to draft or refine them for you, and it makes the change through a guarded path that is permission-checked and recorded, the same as any other agent-authored change.
Versioned and reversible
Every save snapshots a version, tagged with whether the edit came from a person, the AI, or the system. You can compare any version against the current text or against the content it inherits from the layer above, and you can restore an earlier version. Restoring is non-destructive: it writes a new version rather than discarding the later one, so nothing is lost. A save that matches the text already in force is recognized as a no-op, so the history records real changes rather than filling with duplicates.
Why it matters
For your team, Agent Instructions mean you set your conventions once and every agent follows them, instead of repeating the same guidance in prompt after prompt.
For the people who govern how AI is used, instructions are a single, central, versioned control over agent behavior, with a platform policy floor that cannot be removed and a full history of who changed the guidance and when.