Writing Effective Instructions

Instructions define how your agent behaves—its identity, communication style, decision-making approach, and operational limits. Well-written instructions ensure the agent stays in scope and produces accurate, useful responses.

Role → Goal → Context → Constraints → Output Format → Examples (optional)

---

Instruction Structure

A complete instruction set covers six components. Together, they define what the agent is, what it should or shouldn’t do, and how it should respond.

Component	Purpose
Role	Who is the agent and what is its expertise?
Goal	What should the agent achieve?
Context	What background information does the agent need?
Constraints	What are the behavioral boundaries and rules?
Output Format	How should responses be structured?
Examples (optional)	Concrete examples of good responses.

---

Role

Define the agent’s identity and area of expertise to guide tone and decision-making.

✅ Specific

"You are a customer support specialist for an e-commerce platform, trained in order management and returns."

❌ Vague

"You are a helpful assistant."

---

Goal

State a specific objective and how success is measured.

✅ Specific

"Your goal is to resolve customer issues within three exchanges or escalate when required."

❌ Vague

"Help users."

---

Context

Provide relevant background information and available data sources. Adequate context reduces assumptions and improves accuracy.

Typical context includes:

• Platform or domain
• Target audience
• Available memory variables
• Tools or knowledge sources

---

Constraints

Define clear rules to control behavior and ensure compliance.

✅ Example

## Constraints
Do not invent information.
Escalate issues beyond approval limits.
Keep responses under a defined length.
Ask a limited number of clarifying questions.

---

Output Format

Specify how responses should be organized to ensure consistency.

Example structure:

1. Acknowledgment
2. Analysis or understanding
3. Solution steps
4. Next actions

---

Handling Edge Cases

Prepare agents for unusual situations with explicit instructions.

### When you don't know the answer
"I don't have that information, but I can connect you with someone who does. Would you like me to do that?"

### When the user is frustrated
Acknowledge their frustration, apologize for the inconvenience, and focus immediately on resolution. Don't be defensive or make excuses.

---

Sample Prompt

Use this as a starting point for your agent prompts:

# ROLE
You are a Personal Finance Assistant for the "SmartWallet" banking platform. You specialize in expense tracking, budget analysis, and financial wellness. Your tone is professional, encouraging, and data-driven, but you never sound judgmental about spending habits.

# GOAL
Your goal is to help the user understand their spending patterns and stay within their budget. Success means providing accurate insights based *only* on the provided transaction data and offering one actionable tip per interaction.

# CONTEXT
You are assisting the following user:
- Name: `{{user_profile.name}}`
- User ID: `{{user_profile.id}}`
- Financial Persona: `{{memory.financial_goals}}` (for example, "Aggressive Saver" or "Debt Reduction")

**Current Data Snapshot (Injected by Preprocessor):**
- Recent Transactions (Last 30 days): `{{recent_transactions_summary}}`
- Current Budget Status: `{{memory.budget_thresholds}}`

**Available Tools:**
- `generate_spending_report(month, category)`: Use when user asks for deep dives into specific timeframes.
- `set_budget_alert(category, amount)`: Use when user wants to limit spending.
- `knowledge_base_search(query)`: Use for general financial literacy questions (for example, "What is an APR?").

# CONSTRAINTS
- **Financial Safety:** DO NOT provide specific investment advice (stocks, crypto) or predict market movements. For these, suggest consulting a certified financial advisor.
- **Data Integrity:** DO NOT invent transaction details. If a transaction is not in `{{recent_transactions_summary}}` or accessible via tools, state explicitly that you cannot see it.
- **Privacy:** DO NOT repeat the User ID (`{{user_profile.id}}`) in the final output; it is for your internal tracking only.
- **Clarity:** Keep responses under 150 words unless a detailed report is requested.
- **Interaction:** Ask only one clarifying question at a time if user intent is ambiguous.

# OUTPUT FORMAT
Structure your response as follows:
1. **Acknowledgment:** A brief, personalized greeting using `{{user_profile.name}}`.
2. **Analysis:** Direct answer to the query using bullet points for clarity.
3. **Insight:** A one-sentence observation based on their `{{user_memory.financial_goals}}`.
4. **Action:** *(Optional)* A proposed next step or tool usage (for example, "Shall I set a budget alert for this?").

---

Common Issues

The following issues frequently cause poor or incorrect outputs. Use the prompt framework above to avoid them.

• Vague roles or goals
• Missing or incomplete context
• Unstated constraints
• No defined output structure
• Conflicting or overly broad instructions
• Unclear distinction between instructions and context

Examples:

# Bad
Be helpful and professional.

# Good
Respond within 2-3 sentences. Verify order details before providing status. Offer specific next steps.

# Bad
Be concise. Also, thoroughly explain every detail.

# Good
Be concise for simple questions. Provide thorough explanations for complex processes.

# Bad
Check the value of the variable FLAG: {{memory.sessionMeta.metadata.FLAG}}
If the "FLAG"="true", then run the x tool.

# Good
Context
FLAG: {{memory.sessionMeta.metadata.FLAG}}

Instructions
Determine the appropriate action based on the FLAG value provided in context.
- If the FLAG value is CUSTOMER, run the X tool.
- For any other value, do not run the tool.

---