Multi-Agent Systems Need Role Contracts, Not Personality Prompts

A useful agent role is defined by inputs, outputs, authority, required evidence, and handoff rules—not by colorful persona text. The difference matters when multiple agents share a codebase, touch the same files, or need to hand off work to each other. A persona makes agents brittle; a contract makes them predictable.

The persona trap

Most agent systems start by writing a character description: “You are a helpful, creative assistant who loves problem-solving.” This feels good to write but tells an agent almost nothing about what boundary it must respect. The agent inherits no clarity about who gets to decide if its output is correct, when it should refuse a request, or what it does when it finds a conflict.

Personas are interior monologue. Contracts are operational discipline. When agents share decision-making power—say, two agents reviewing the same pull request, or three agents building different parts of the same configuration—a persona is noise. A contract is law.

What a role contract includes

A role contract is a structured, machine-readable agreement about what an agent does and where it stops. It has five hard parts:

Input schema: What data or request types trigger this agent? What fields are required? What do empty or missing values mean? Example: a code-review agent accepts a file path, a diff, and an acceptance-criteria document. A request with only a file path and no acceptance criteria gets rejected before the agent runs.

Output schema: What format does the agent produce? Is the output a decision (approve / reject), a list of items, a structured log, a modified artifact? The downstream consumer must know exactly what shape to expect. If an agent can produce either JSON or Markdown depending on mood, every consumer needs to handle both—cost and fragility that belongs nowhere.

Authority and scope: What is this agent allowed to decide? A code-review agent might be allowed to flag security issues but not to change project priorities. A refactoring agent might be allowed to reorganize imports but not to remove dependencies. Scope is not a suggestion—it is the blast radius. When an agent overreaches, you need to see it immediately.

Evidence requirements: What must be present before the agent acts? If a deployment agent needs a green test suite before it deploys, that is a contract requirement. If a schema-migration agent needs a rollback plan, that is written down. If a security agent needs a threat model on file, it is stated. Evidence requirements are the acceptance criteria that guard against silent failures.

Handoff rules: When does this agent stop and hand off to another? If a code-review agent finds a merge conflict, does it resolve it, report it, or refuse the review? If a refactoring agent finds a breaking API change, does it stop, escalate, or propose a mitigation? Handoff rules are the circuit breakers that prevent agents from running open-loop.

Artifact contracts prevent collision

When agents read and write the same files, collision is not a possibility—it is the default state. Git helps with text, but it does not teach agents what they are allowed to change.

An artifact contract is a sub-schema that lives inside a file or directory structure. It specifies which agent owns which sections, what fields are read-only, what changes trigger approval, and what changes require a rollback plan.

Example: a configuration file might have sections owned by different agents. One section is owned by the ops-provisioning agent (read-only for everyone else). Another is owned by the security-policy agent. The contract specifies which sections each agent can modify, what the merge strategy is if both agents want to change the same line, and who breaks a tie.

Without an artifact contract, agents collide silently or conflict loudly. With one, collision is prevented by design. Each agent knows its lane.

Escalation and stop conditions

An agent that never says “I don’t know” or “this is above my pay grade” will eventually make a decision that should have been made by a human.

Stop conditions are the opposite of open-loop. They are the explicit points where an agent must halt, log why, and hand off to a reviewer or another system. Examples:

• A code-review agent stops and escalates if it finds code that matches a security pattern it was not trained to evaluate.
• A refactoring agent stops if it discovers a dependency that is no longer actively maintained.
• A deployment agent stops if the health-check endpoints return data it has not seen before.
• A data-migration agent stops if the source and destination schemas differ in ways the migration plan did not account for.

Stop conditions are not failures. They are proofs that the agent knows its limits. A well-designed stop condition is more valuable than a flashy success.

Escalation rules define who gets notified and what form the handoff takes. Is it a pull request? A ticket? A human review gate? Escalation is not “alert someone and hope they notice.” It is a defined, tested handoff with acknowledgment.

Overlap and conflict resolution

When two agents have overlapping authority, you need a tiebreaker rule written down before the conflict happens.

Scenario: a code-quality agent wants to refactor a function for readability. A performance-optimization agent wants to keep it as-is because the current form is cache-friendly. Both agents are right. Who wins?

Your contract specifies the priority. Examples of priority rules:

• Security always beats convenience.
• Correctness always beats performance.
• Explicit always beats implicit.
• Approved changes beat exploratory changes.
• Older-filed requests beat newer requests (FIFO tiebreaker).

Priority rules are not arbitrary—they encode your system’s values. If performance beats security in your contract, every agent will optimize for speed first. If you later discover a performance exploit, the conflict was baked in.

Conflicts should be rare if roles are well-bounded. If conflicts are frequent, the roles are overlapping too much. That is a signal to redesign, not to add more tiebreaker rules.

Agent role contract worksheet

When defining a new agent role, work through this checklist before implementation:

• Role name and purpose: One clear sentence. What is this agent’s reason to exist?
• Input schema: Document every required field, accepted types, and what happens if a field is missing.
• Output schema: Specify format (JSON, Markdown, structured log), required fields, and error responses.
• Authority scope: List what this agent is allowed to decide. List what it is explicitly not allowed to do.
• Evidence requirements: What must be present before the agent runs? What makes a request valid?
• Stop conditions: List at least three scenarios where this agent must halt and escalate.
• Escalation path: When the agent stops, who gets notified and how?
• Conflict rules: For each overlapping role, specify a tiebreaker.
• Artifact ownership: Which files or sections does this agent own? Which are read-only?
• Audit trail: How will you log what this agent did, why it did it, and who approved it?

If you cannot answer these questions before building the agent, you are not ready to build it.

Grounded systems scale; personas don’t

When agents start as personas, they work fine in a one-off experiment. One agent, no conflicts, nothing to break. The moment you add a second agent, the persona system collapses. Agents contradict each other. They make overlapping decisions. They step on each other’s work.

A role contract is overhead when you have one agent. It is the only thing that scales when you have ten. The contract is the interface. The agent is the implementation. Change the implementation without rewriting the contract, and the system still works.

The hard part is writing the contract correctly—being precise about what the agent owns, what it is not allowed to touch, and when it must defer to something smarter than itself. That is also where the real design work happens. The persona was always fiction. The contract is the architecture.