Writing Agent Instructions That Actually Work

The most common source of poor agent behavior is not the underlying model — it is the instructions given to it. A capable model operating under vague, inconsistent, or incomplete instructions will produce capable-but-wrong behavior that frustrates users and confuses owners. Writing system prompt instructions that actually produce the behavior you intend is a craft, and like all crafts it improves with deliberate practice and honest feedback.

Effective agent instructions cover five domains: who the agent is, what it does, how it communicates, what it should not do, and what it should escalate. Instructions that cover all five domains clearly produce coherent agent behavior. Instructions that cover three domains in detail and assume the other two will work themselves out produce agents that are excellent in three areas and unpredictable in the other two.

Persona specification must be concrete, not abstract. 'Professional but approachable' is not actionable. 'Uses short sentences, avoids jargon, addresses the user's specific question before providing context, never uses first-person for the agent itself' — this is actionable. The more specific the persona instruction, the more consistent the behavior it produces. Abstract persona descriptions give the model latitude to interpret; concrete ones constrain that latitude toward your intent.

Scope and boundary definition should state both what the agent does and what it does not do with equal specificity. Many system prompts describe the agent's purpose in detail and then add a vague instruction to 'stay on topic.' The model's interpretation of where the topic boundary lies will not match the owner's unless the owner draws it explicitly: 'If the user asks about X, acknowledge that this is outside my scope and suggest they consult Y.' This specificity prevents the boundary violations that generate complaints and disputes.

Escalation trigger design is where system prompts most often fail. A general instruction to 'escalate complex situations' leaves the model to define what complex means — and its definition will differ from yours in exactly the cases that matter most. Effective escalation instructions name the specific conditions that trigger escalation: 'If the user expresses any indication of crisis or distress, immediately provide crisis resources and surface the conversation to the human owner. If a purchase request exceeds [threshold], pause and request human authorization before proceeding. If the user claims a material error in a previous interaction, flag the conversation for human review.'

Edge case handling deserves explicit treatment in the system prompt for every edge case category you can anticipate. When a user asks a question the agent cannot answer confidently? When a user appears to be testing the agent's constraints? When the conversation language switches mid-thread? When a user provides conflicting information about their situation? Each of these common situations should have a defined response in the instructions — not because the model cannot handle them without guidance, but because your defined response will be more consistent with your agent's purpose than the model's improvised one.

Testing the instructions before deployment is not optional. Assemble a test set of representative interactions — including the edge cases you have written instructions for — and run the draft system prompt against each. Note every response that deviates from your intended behavior. Revise the relevant instruction to address the deviation. Retest. A system prompt that has been through three revision cycles against a realistic test set will produce dramatically better behavior than one that was written in a single session and deployed directly.

Iterating based on observed behavior is the practice that makes system prompts effective over the long term. The interactions your agent actually has reveal the cases you did not anticipate in your test set. Review escalations, complaints, and unusual interaction patterns regularly for evidence of instruction gaps. Each gap represents a specific addition or revision to the system prompt. Owners who treat the system prompt as a living document — revised in response to evidence — operate agents that continuously improve. Those who treat it as a one-time artifact operate agents that plateau.