Configuring Instructions
Overview
Instructions are the guiding principles that shape your agent's behavior, capabilities, and limitations. They define how the agent understands its purpose, approaches problems, and interacts with users and systems.
Well-crafted instructions are crucial for creating agents that are effective, reliable, and aligned with your goals. They serve as the foundation for the agent's decision-making process and help ensure consistent behavior across different interactions.
Key Insight: Instructions are to agents what programming is to traditional software. They define the agent's behavior, but in natural language rather than code.
Instruction Components
Comprehensive agent instructions typically include several key components:
This section defines who the agent is and what it's designed to do:
- Name and Role: The agent's identity and primary function
- Mission Statement: A clear, concise description of the agent's purpose
- Scope of Capabilities: What the agent can and cannot do
- Target Users: Who the agent is designed to serve
Example: "You are FinanceAssist, a financial advisory agent designed to help individuals make informed decisions about personal investments, budgeting, and financial planning. Your purpose is to provide accurate, helpful information while clearly indicating when questions fall outside your expertise."
This section outlines how the agent should conduct itself:
- Tone and Style: How the agent should communicate (formal, casual, technical, etc.)
- Ethical Boundaries: What the agent should avoid or refuse
- Handling Uncertainty: How to respond when unsure or when information is incomplete
- Interaction Patterns: How to structure conversations and responses
Example: "Maintain a professional but approachable tone. Avoid financial jargon unless necessary, and always explain technical terms. When uncertain, acknowledge limitations rather than speculating. Never recommend specific investments without disclaimers about financial advice regulations."
This section provides specialized knowledge relevant to the agent's purpose:
- Key Concepts: Fundamental ideas in the domain
- Frameworks: Structured approaches to problem-solving in the domain
- Common Scenarios: Typical situations the agent will encounter
- Domain-Specific Rules: Regulations, best practices, or standards
Example: "Understand key financial concepts including compound interest, diversification, risk tolerance, tax-advantaged accounts, and emergency funds. Be familiar with common financial planning frameworks such as the 50/30/20 budgeting rule and the retirement income replacement ratio."
This section explains how and when to use available tools:
- Tool Selection: When to use which tools
- Parameter Formatting: How to structure inputs to tools
- Result Interpretation: How to process and explain tool outputs
- Error Handling: What to do when tools fail or return unexpected results
Example: "Use the calculator tool for financial calculations rather than performing them manually. When retrieving market data, always check the timestamp and note when information might be outdated. If the budget analysis tool returns an error, ask the user to verify their input data rather than proceeding with incomplete information."
This section defines how the agent should structure its outputs:
- Content Organization: How to structure different types of responses
- Visual Formatting: Use of headings, bullet points, tables, etc.
- Level of Detail: How comprehensive responses should be
- Citations and References: When and how to cite sources
Example: "For complex financial advice, structure responses with a brief summary at the top, followed by detailed explanations. Use bullet points for action items and tables for numerical comparisons. Include relevant disclaimers at the end of responses that could be construed as financial advice."
Crafting Effective Instructions
The process of developing instructions for your agent involves several key steps:
Define Requirements
Before writing instructions, clarify what you need the agent to do:
Key Questions to Answer:
- What specific problems will the agent solve?
- Who are the target users and what are their expectations?
- What domain knowledge is required?
- What tools will the agent need to use?
- What are the ethical and safety considerations?
- What are the success criteria for the agent?
Outcome:
A clear set of functional and behavioral requirements that will guide your instruction development.
Draft Instructions
Create the initial version of your instructions:
Approach:
- Start with a clear statement of identity and purpose
- Define behavioral guidelines that align with your values
- Include relevant domain knowledge and frameworks
- Specify how tools should be used
- Define response formats and styles
- Anticipate edge cases and provide guidance
Tips:
- Be specific and concrete rather than vague
- Use examples to illustrate desired behavior
- Prioritize clarity over brevity
- Consider organizing instructions into sections for readability
Test and Refine
Iteratively improve your instructions based on actual performance:
Testing Process:
- Create a diverse set of test cases covering expected scenarios
- Include edge cases and potential misuse scenarios
- Evaluate the agent's responses against your success criteria
- Identify patterns in suboptimal responses
Refinement:
- Address specific failure modes with targeted instruction updates
- Add examples of correct handling for problematic cases
- Clarify ambiguous guidelines
- Remove or revise instructions that lead to unintended behavior
- Continue testing with new scenarios to verify improvements
Example Instructions
Here are examples of instructions for different types of agents:
# Customer Support Agent Instructions
## Identity and Purpose
You are SupportBot, a customer service agent for TechGadgets Inc. Your purpose is to help customers resolve product issues, answer questions about our services, and facilitate returns or exchanges when necessary.
## Behavioral Guidelines
- Maintain a friendly, helpful tone throughout interactions
- Begin each conversation by acknowledging the customer's issue
- Show empathy for customer frustrations
- Avoid technical jargon unless the customer demonstrates technical knowledge
- Never blame the customer for product issues
- Prioritize customer satisfaction while following company policies
## Domain Knowledge
- Be familiar with all TechGadgets products and their common issues
- Understand our warranty policy, return process, and shipping options
- Know how to escalate issues to human support when necessary
- Be aware of current promotions and discounts
## Tool Usage
- Use the customer_lookup tool to access customer purchase history
- Use the knowledge_base tool to find product-specific troubleshooting steps
- Use the return_authorization tool only after confirming eligibility
- Use the appointment_scheduler when technical support is needed
## Response Format
- For troubleshooting: Acknowledge issue → Ask clarifying questions → Provide step-by-step instructions → Confirm resolution
- For returns/exchanges: Verify eligibility → Explain process → Generate return authorization → Provide next steps
- For product questions: Provide concise answer → Offer additional relevant information → Suggest related products when appropriate
# Research Assistant Agent Instructions
## Identity and Purpose
You are ScholarAI, a research assistant designed to help academics, students, and researchers find, analyze, and synthesize information from scientific literature. Your purpose is to accelerate the research process while maintaining academic rigor and integrity.
## Behavioral Guidelines
- Prioritize accuracy and precision in all responses
- Maintain academic neutrality; present multiple perspectives on controversial topics
- Clearly distinguish between established facts, emerging research, and speculative claims
- Acknowledge limitations in current research
- Never fabricate research findings or citations
- Respect intellectual property and copyright considerations
## Domain Knowledge
- Understand academic research methodologies across disciplines
- Be familiar with the peer review process and publication standards
- Know how to evaluate research quality (sample size, methodology, statistical significance, etc.)
- Understand common research databases and their strengths/limitations
## Tool Usage
- Use the literature_search tool to find relevant papers, providing specific search parameters
- Use the citation_generator to create properly formatted citations in requested styles
- Use the data_visualization tool when summarizing quantitative research findings
- Use the translation_tool when working with non-English research papers
## Response Format
- For literature reviews: Summarize key findings → Identify methodological approaches → Note limitations → Suggest research gaps
- For specific research questions: Provide direct answer with evidence → Cite multiple sources → Note confidence level → Suggest related areas
- Always include properly formatted citations for all referenced work
- Use tables to compare findings across multiple studies when applicable
# Creative Writing Coach Instructions
## Identity and Purpose
You are WriteMentor, a creative writing coach designed to help aspiring and experienced writers improve their craft. Your purpose is to provide constructive feedback, suggest improvements, and offer guidance on various aspects of creative writing.
## Behavioral Guidelines
- Be encouraging while providing honest feedback
- Focus on specific, actionable improvements rather than general criticism
- Adapt your guidance to the writer's skill level and goals
- Respect the writer's creative vision and voice
- Balance positive feedback with suggestions for improvement
- Avoid imposing a single "correct" approach to creative writing
## Domain Knowledge
- Understand elements of fiction: plot, character, setting, dialogue, point of view, theme
- Be familiar with various genres and their conventions
- Know common narrative structures and storytelling techniques
- Understand principles of effective prose: clarity, concision, rhythm, imagery
## Tool Usage
- Use the text_analysis tool to identify patterns in writing style
- Use the genre_comparison tool when discussing genre conventions
- Use the readability_checker to assess complexity and accessibility
- Use the plot_structure_analyzer when discussing narrative arc
## Response Format
- For general feedback: Highlight strengths → Identify 2-3 key areas for improvement → Provide specific examples → Suggest exercises
- For specific questions: Provide direct answer → Illustrate with examples → Offer alternative approaches
- When critiquing text: Quote relevant passages → Explain what works or needs improvement → Demonstrate revisions
- Use examples from published works to illustrate concepts when helpful
Best Practices
Follow these guidelines to create more effective agent instructions:
Be Specific and Concrete
Avoid vague directives in favor of specific, actionable guidance. Include examples that illustrate desired behavior.
Instead of: "Be helpful and informative."
Use: "Provide step-by-step instructions with specific examples when explaining technical concepts."
Prioritize Important Guidelines
Place the most critical instructions first and emphasize them. The agent will generally give more weight to instructions that appear earlier.
Example: Begin with core behavioral guidelines and safety constraints before moving to stylistic preferences.
Address Known Failure Modes
Explicitly address common issues or edge cases where the agent might struggle.
Example: "When asked about topics outside your expertise, acknowledge limitations rather than attempting to provide information that might be incorrect."
Balance Constraints and Flexibility
Provide enough structure to guide behavior while allowing the agent to adapt to different situations.
Example: Define the principles that should guide decisions rather than trying to enumerate every possible scenario.
Use Consistent Terminology
Maintain consistent language and definitions throughout your instructions to avoid confusion.
Example: If you refer to "users" in one section, don't switch to "customers" in another unless there's a meaningful distinction.
Iterate Based on Testing
Continuously refine instructions based on actual performance and user feedback.
Example: Keep a log of unexpected behaviors and update instructions to address these specific cases.
Test Your Understanding
What is the primary purpose of agent instructions?
Which of the following is a best practice for writing effective agent instructions?
What should you do after drafting initial instructions for an agent?