How to Write AI Agent Instructions That Actually Work

Writing prompts to ChatGPT is one thing. Writing instructions that define how an AI agent behaves across hundreds of interactions is another. This guide shows you how to write agent instructions that actually work, with real templates you can use today.

AI agent instructions are a set of permanent rules that define how an AI agent behaves, what tools it can use, and how it formats responses. Unlike a one-time prompt you send to ChatGPT, instructions persist across every conversation the agent has. Think of them as the agent's operating manual.

A prompt is a single request. An instruction is a standing rule.

When you ask ChatGPT to "write an email," you get a response. The next time you ask, it has no memory of your preferences unless you repeat them. When you give an AI agent instructions that say "write emails in a conversational tone, keep them under 150 words, and always include a clear CTA," that behavior becomes permanent. Every email the agent writes follows those rules until you change the instructions.

This distinction matters because teams building agents need predictable, repeatable behavior. A support agent answering 50 customer questions a day cannot start from scratch every time. Instructions ensure consistency.

The confusion between prompts and instructions causes most early agent failures. Developers and business teams often approach them the same way, but they serve completely different purposes.

Prompts are ephemeral. You write a prompt, get a response, and the interaction ends. The next prompt starts fresh. Prompts work well for one-off tasks like drafting a blog post, summarizing a document, or generating ideas.

Instructions are persistent. They define behavior across hundreds or thousands of interactions. An agent instruction tells the system "this is how you always operate," not "do this once."

Prompts are task-focused. "Analyze this sales call transcript and pull out objections." The task is clear, bounded, and complete when the response arrives.

Instructions are role-focused. "You are a sales analyst. When reviewing call transcripts, identify objections, categorize them by type, and suggest responses based on past successful rebuttals." The instruction defines a repeatable process.

Prompts assume no context. Every interaction starts from zero. You provide all the information the model needs in the prompt itself.

Instructions assume ongoing context. Agents know their role, the tools they have access to, and the company data they can query. Instructions build that foundation so individual prompts can be shorter and more specific.

Most platforms now distinguish between the two explicitly. On Dust, agent instructions live in the agent builder and persist across all conversations. Prompts are the individual questions users ask once the agent is live.

Every high-performing agent instruction set includes the same core elements. Miss one, and the agent either fails unpredictably or produces inconsistent outputs.

Define who the agent is and what expertise it brings. This shapes every decision the agent makes about tone, depth, and approach.

A vague role produces vague results. "You are a helpful assistant" tells the agent almost nothing. "You are a customer support specialist for a SaaS platform serving mid-market sales teams" gives the agent a specific identity and implied knowledge base.

The role sets boundaries on what the agent should and should not attempt. A support agent should not make product roadmap promises. A sales agent should not troubleshoot technical issues. Defining expertise prevents agents from wandering into areas where they lack context.

Provide information the agent needs to understand your business, product, or workflow. This is where you fill the gap between the agent's general training data and your company's specific reality.

Context includes things like what your product does, who your customers are, common pain points, and how your team operates. If your support agent does not know that your platform integrates with Salesforce and HubSpot, it cannot answer questions about those integrations accurately.

The key is selectivity. More context is not always better. Give the agent what it needs to handle its specific role, not everything it could possibly know.

Explain the process the agent should follow when handling requests. This is especially important for agents that execute multi-step tasks.

A content agent might follow this workflow: search internal documentation for the topic, identify the three most relevant sources, extract key points, draft an outline, expand each section with supporting details, and format the output as markdown.

Breaking workflows into numbered steps reduces errors. The agent knows what comes first, what dependencies exist between steps, and when the task is complete.

Specify which tools the agent can use and when to use them. Agents with access to multiple tools often choose poorly without explicit guidance.

If your agent can search documentation, query a CRM, and send Slack messages, tell it when each tool is appropriate. "Use the documentation search tool when answering product questions. Use the CRM query tool when looking up account details. Use Slack only to notify the team of escalations."

Tool names matter. "Search Product Docs" is clearer than "Search Tool 1." The agent interprets the name semantically, so descriptive labels improve tool selection accuracy.

Define what the response should look like. Specify structure, length, tone, and any required elements.

An agent without format instructions might return three paragraphs when you need bullet points, or write 500 words when 100 would suffice. Format constraints reduce revisions and make outputs more usable.

Tone matters more than most teams realize. A sales agent should sound confident and consultative. A support agent should sound patient and helpful. An internal research agent can be more direct and technical. Specify tone explicitly.

Set clear rules about what the agent should never do. This is the most frequently skipped section and the one that causes the most production failures.

Boundaries include things like: never fabricate data, never modify files outside this directory, never make promises about pricing or timelines, always cite sources, and always ask for confirmation before sending emails.

The three-tier boundary framework works well: always do (non-negotiable requirements), ask first (actions that need approval), and never do (hard stops that prevent damage).

Certain instruction patterns appear repeatedly in high-performing agents. These are not rigid templates but proven structures that reduce failure rates.

When you give an agent multiple conditional instructions, make sure each condition is distinct and unambiguous. Overlapping conditions confuse agents and lead to inconsistent behavior.

Bad example: "If data is missing, ask the user for it. If data is incomplete, request clarification."

Good example: "If required fields are empty, ask the user to provide them. If optional fields are empty, proceed without them."

The difference is specificity. "Missing" and "incomplete" sound similar enough that the agent might interpret them interchangeably. "Required fields empty" versus "optional fields empty" creates a clear decision boundary.

Tell the agent what to accomplish, not the technical implementation details. Agents reason semantically, not programmatically.

Bad example: "Invoke the CreateCase API using the customer ID from the previous query."

Good example: "Create a support case for this customer."

The agent knows how to create cases if it has access to the right tool. Describing the outcome you want produces better results than specifying API calls.

Tell the agent what to do, not what to avoid. Negative instructions confuse language models more than positive directives.

Bad example: "Do not send emails without user approval."

Good example: "Always request confirmation before sending emails."

The affirmative version gives the agent a clear action. The negative version leaves the alternative behavior undefined.

Each instruction should be internally consistent. Embedding both "do this" and "do that" in the same sentence creates ambiguity.

Bad example: "If an invoice is marked paid, send a confirmation email but also flag it for follow-up."

Good example: Split into two instructions: "If an invoice is marked paid, send a confirmation email." "If an invoice is marked paid and the payment date is over 90 days old, flag it for follow-up."

One thought, one instruction. If the logic branches, write separate instructions for each branch.

When instructions involve judgment calls or nuanced interpretation, show the agent what good output looks like.

An agent that needs to categorize customer feedback into themes benefits from examples of each category. "Feature requests: 'It would be great if we could export data to Excel.' Bug reports: 'The dashboard stopped loading this morning.' Pricing questions: 'Do you offer annual discounts?'"

Examples help the agent map new inputs to known patterns, reducing misclassification.

Agents are not good at math, complex calculations, or deterministic processes that must produce perfect results every time. Move that logic into tools.

If your agent needs to calculate discount eligibility based on account tier, contract length, and payment history, build a tool that handles the calculation. The agent should invoke the tool, not attempt the math itself.

This pattern improves accuracy and makes debugging easier. If the discount calculation is wrong, you fix the tool, not the agent instructions.

For tasks where accuracy matters more than speed, tell the agent how confident it needs to be before proceeding.

"Only provide an answer if you are at least 90% confident based on the retrieved documents. If confidence is below 90%, respond with 'I do not have enough information to answer that accurately' and suggest contacting the team directly."

This prevents hallucinations. Agents without confidence thresholds will guess rather than admit uncertainty.

Use this template as a starting point. Adapt the sections to match your agent's purpose, but keep the overall structure intact.

--- Agent Name: [Descriptive name that indicates function] Description: [One sentence explaining what this agent does] --- ## Role and expertise You are a [specific role] for [company/team/product]. You specialize in [primary function]. Your goal is to [outcome the agent should achieve]. ## Context [Background information the agent needs] - Our product/service: [brief description] - Our customers: [who they are, what they need] - Our team structure: [relevant organizational context] ## When a user asks you to [primary task]: 1. [First step] 2. [Second step] 3. [Third step] 4. [Final step] ## Tools you can use - [Tool name]: [when to use it and what it does] - [Tool name]: [when to use it and what it does] - [Tool name]: [when to use it and what it does] ## Output format - Length: [word count or paragraph limit] - Structure: [bullets, numbered lists, prose, etc.] - Tone: [conversational, formal, technical, etc.] - Required elements: [citations, links, specific sections] ## Examples of good output [Paste 2-3 real examples that show what success looks like] ## Boundaries ✅ Always do: - [Required behavior 1] - [Required behavior 2] - [Required behavior 3] ⚠️ Ask first: - [Action requiring approval 1] - [Action requiring approval 2] 🚫 Never do: - [Hard stop 1] - [Hard stop 2] - [Hard stop 3]

Seeing how teams structure instructions for actual business workflows clarifies what works in practice.

This agent answers technical questions from customers using internal documentation.

--- Agent Name: Support Copilot Description: Answers technical support questions using product documentation and past ticket resolutions --- ## Role and expertise You are a technical support specialist for [Product Name], a workflow automation platform used by operations teams. You help customers resolve technical issues quickly and accurately. ## Context - Our product connects to Slack, Notion, Google Drive, and Salesforce - Common issues: authentication errors, sync delays, permission problems - Our customers are typically operations managers at mid-market companies ## When a user asks a support question: 1. Search product documentation for relevant articles 2. Search past resolved tickets for similar issues 3. Provide a clear answer with specific troubleshooting steps 4. Always cite which documentation or ticket informed your answer 5. Ask if the user needs additional help ## Tools you can use - Search Product Docs: Use when answering questions about features, setup, or configuration - Search Past Tickets: Use when the question describes a specific error or bug - Create Support Ticket: Use when the issue requires engineering review ## Output format - Keep answers under 200 words - Use numbered steps for troubleshooting procedures - Include links to relevant documentation - Use a patient, helpful tone ## Boundaries ✅ Always do: - Cite your sources (documentation or ticket number) - Provide specific steps, not vague suggestions - Ask clarifying questions if the issue is unclear ⚠️ Ask first: - Before escalating to engineering - Before making promises about fix timelines 🚫 Never do: - Fabricate troubleshooting steps if documentation does not cover the issue - Make commitments about product roadmap or new features - Share internal engineering details or system architecture

This agent prepares account research before discovery calls.

--- Agent Name: Sales Research Agent Description: Prepares pre-call research briefs for account executives --- ## Role and expertise You are a sales research analyst. You gather company intelligence from public sources and internal CRM data to prepare account executives for discovery calls. ## When asked to research a company: 1. Query the CRM for any existing relationship history 2. Search web for recent company news, funding, leadership changes 3. Identify likely pain points based on industry and company size 4. Suggest discovery questions tailored to this account 5. Format output as a concise brief ## Tools you can use - CRM Query: Use to check if we have existing contacts, past conversations, or deals - Web Search: Use to find recent news, funding announcements, executive changes - Company Data Lookup: Use to pull firmographic data (size, industry, tech stack) ## Output format Structure every research brief using this template: **Company:** [Name] **Industry:** [Primary industry] **Size:** [Employee count and revenue if available] **Recent news:** [2-3 bullet points] **Existing relationship:** [Summary from CRM or "None found"] **Likely pain points:** [3-4 based on industry patterns] **Suggested questions:** [4-5 discovery questions] Keep the brief under 300 words. Use bullet points for readability. ## Boundaries ✅ Always do: - Check CRM first before researching externally - Flag if company is already in an active deal - Cite sources for news and data points ⚠️ Ask first: - Before reaching out to contacts outside the assigned territory 🚫 Never do: - Fabricate company details if data is unavailable - Share research briefs outside the sales team - Make assumptions about budget or decision-making authority without evidence

This example comes from Dust's own content team. The agent prepares interview briefs and handles post-interview workflows.

--- Agent Name: Interview Prep Agent Description: Prepares customer interview briefs and manages post-interview content workflows --- ## Role and expertise You are a content marketing coordinator. You prepare interview briefs for customer case studies and manage the workflow from transcript to published draft. ## When preparing an interview brief: 1. Query CRM for account details, contract value, key contacts 2. Search Slack for any customer mentions or support context 3. Search past case studies for similar companies or use cases 4. Generate a brief with background, suggested questions, and angles to explore 5. Send the brief to the interviewer 24 hours before the call ## When processing a transcript: 1. Extract key quotes that illustrate measurable results 2. Identify the problem-solution-outcome narrative arc 3. Generate a draft outline with H2 and H3 structure 4. Flag any claims that need verification or data points 5. Route the draft to the editor ## Tools you can use - CRM Query: Pull account details and contract data - Slack Search: Find internal discussions about the customer - Case Study Database: Search past published stories - Email: Send interview briefs and draft outlines ## Output format **For interview briefs:** - Customer background (100 words) - Known results or outcomes (bullet list) - Suggested questions (8-10) - Angles to explore (3-4) **For post-interview outlines:** - H1: [Suggested title] - Opening hook (2-3 sentences) - H2 sections with key points under each - Quotes to feature (with speaker attribution) - Data points that need verification (flagged) ## Boundaries ✅ Always do: - Verify contract value and customer tier from CRM before including in briefs - Flag any unverified statistics or claims in transcripts - Include source citations for internal data ⚠️ Ask first: - Before publishing any customer-specific metrics - Before reaching out to customers directly 🚫 Never do: - Fabricate quotes or paraphrase customer statements - Share interview transcripts outside the marketing team - Include unverified ROI claims in drafts

Dust agents work differently than generic LLMs because they connect to your company's actual data and tools. That changes how you write instructions.

When you build an agent in Dust, you define three layers: instructions, knowledge sources, and tools. Instructions tell the agent what to do. Knowledge sources give it access to company context. Tools let it take actions beyond answering questions.

The instruction framework Dust recommends mirrors the template above but emphasizes knowledge scoping. More data does not equal better results. Agents perform best when they access only the information they need for their specific role.

A support agent needs access to product documentation and past tickets, not the entire company Notion workspace. A sales agent needs CRM data and competitive intelligence, not HR policies. Focused knowledge access improves response quality and speed.

Dust also separates tools by function. Instead of one generic "search" tool, create distinct tools like "Search Product Docs," "Search Support Tickets," and "Search Sales Playbooks." The agent interprets tool names semantically, so descriptive labels improve accuracy.

The platform includes a "thinking" view that shows exactly what the agent did: which sources it searched, what it found, which tools it used, and why. This transparency makes debugging easier. If an agent produces a wrong answer, you can trace whether the issue was bad instructions, missing knowledge, or incorrect tool usage.

Most agent failures trace back to one of five instruction errors.

Vague role definitions. "You are a helpful assistant" provides no behavioral guidance. The agent has no constraints, no expertise, and no clear purpose. Specific roles produce specific behavior.

Contradictory rules. Instructions that say "always ask for confirmation" and "respond immediately without delay" cannot both be true. The agent will choose inconsistently. Review instructions for internal contradictions before deploying.

Overloading with tools. Giving an agent access to 15 tools when it only needs three creates decision paralysis. The agent wastes time choosing tools and often selects wrong ones. Start minimal, add tools only when needed.

No output format specification. Without format constraints, agents default to verbose prose. Specify structure, length, and required elements. "Respond in under 150 words using bullet points" produces more usable outputs than "answer the question."

Missing confidence thresholds. Agents without explicit permission to say "I do not know" will guess rather than admit uncertainty. This causes hallucinations. Tell the agent when accuracy matters more than completeness.

Yes, but outputs may vary slightly. Instructions written for Claude, GPT-4, or Gemini generally transfer across models because they rely on natural language structure rather than model-specific syntax. The role, context, and workflow steps remain the same. However, different models interpret tone and formatting instructions with varying levels of precision, so test your instructions on the specific model you plan to deploy. Dust allows you to build an agent with one model, and then change the model to something else.

Test the agent with real scenarios your team will encounter. Run 10-15 typical requests and check for consistency. If the agent produces the same quality of output across similar inputs, your instructions are working. If outputs vary wildly, refine your role definition and add examples. Use the agent's "thinking" or debug view if available to see which instructions it followed and which it ignored.

No. Instructions define how the agent behaves, not how users interact with it. Technical and non-technical users can ask the same agent different types of questions. The agent's instructions should be specific enough to handle both. If you find yourself writing separate instructions for different user groups, you might need two distinct agents with different roles rather than one agent trying to serve everyone.

Update instructions when the agent consistently fails at a task, when your product or workflow changes, or when you add new tools or knowledge sources. Treat instructions like documentation. If your team's process evolves but the agent's instructions do not, outputs will drift from expectations. Review instructions quarterly at minimum, more frequently for agents handling critical workflows.

Long enough to be specific, short enough to remain coherent. Most effective agent instructions run 200-500 words. If your instructions exceed 1,000 words, consider whether you are building one complex agent or several focused agents. Shorter, focused agents with clear roles outperform long, multi-purpose agents with sprawling instructions.

Not yet. Agents follow the instructions you give them but do not rewrite those instructions based on usage. If you want an agent to improve, you need to review its performance, identify failure patterns, and update the instructions manually. Some platforms track agent usage metrics to help you spot where refinements are needed, but the human still makes the changes.