Instruction profiles: a pickable brain-style for your agent

An agent's instructions are not one fixed wall of text. They are assembled from composable blocks — a protocol block, a workspace block, an exec block, a citations block. Because they are composable, an agent can offer more than one set of them, and let a user choose which set drives a conversation — exactly like choosing a model. We call an offered set an instruction profile.

Blocks compose into named sets

The same blocks can compose a full, thorough instruction body or a distilled one that keeps every hard rule and drops the restatements and long examples. Each named set is a profile with an id.

Distillation is not summarization: every load-bearing signal — exact tool ids, parameter orders, path grammar, the plan-ack markers, the exec contract — is preserved. What leaves is the prose a large hosted model can afford but a small local one pays for in seconds of prompt evaluation.

The user picks one, per conversation

An agent declares its profiles in config, and the pick lives beside the model pick in the same capabilities picker. The admin declares the ceiling — which profiles exist and which is the default — and the user chooses one for a conversation.

react:
  default_agent:
    instruction_profiles:
      default: full
      options:
        - { id: full,       label: Full }
        - { id: extra-lite, label: Extra Lite (local models), blocks: [ "xlite:workspace_exec" ] }

Choosing a profile switches the system prompt, so the runtime treats it with the same care as a model switch — the change lands on the user's cold-cache policy, not silently mid-conversation.

The contract is id-only

The wire and the picker carry only { id, label, description }. What an id resolves to — a distilled block set, an inline body, or the platform default — never crosses that boundary. That keeps the surface framework-neutral (any agent kind can declare its own ids) and leaves room for a future instruction module where ids gain versions and some sets ship built in.

agent config            wire / picker           runtime
─────────────           ─────────────           ───────
id + blocks/body   ──▶   id + label      ──▶    resolve id → instructions
(the content)           (only this)             (behind the boundary)

Why it exists

Two agents with the same tools do not always want the same instructions. A hosted model can read the full body; a serving-constrained local model needs the lean one; a specialized workflow may want a stripped protocol with one extra rule. Profiles make that a declared, user-visible choice instead of a fork of the agent — one agent, several brain-styles, picked per conversation and bounded by the admin.

Documentation on GitHub

The live docs behind this entry:

• Reserved platform properties
• How to construct a ReAct agent
• One home for what the user decided
• A local model as your agent's brain