Building Agents
Roles
System-prompt overlays per agent, session, or call.
Roles live under .fabricharness/roles/<role-name>.md. They are system-prompt overlays, not persisted user messages.
Format
---
description: Senior backend engineer focused on safe, minimal changes.
model: openai/gpt-5.5
---
You are a senior backend engineer. Prefer small, well-tested changes.
Do not make broad refactors unless required.Precedence
call role > session role > agent role// Agent default
const fabricAgent = await init({ role: 'engineer' });
// Session-scoped override
const session = await fabricAgent.session(undefined, { role: 'reviewer' });
// Call-scoped override
await session.prompt('Review this PR', { role: 'reviewer' });Why a role and not just a prompt
A role is reusable, scoped, and never appears in the user-message history that the model sees. That keeps the conversation clean and prevents role text from being summarized away during compaction.