diegosouzapw Writing Effective Agent Prompts
Guidelines for crafting system prompts that produce reliable, consistent agent behavior.
Prompt Structure
# Role Definition
[Who the agent is and what it does]
# Constraints
[What the agent MUST and MUST NOT do]
# Process/Workflow
[Step-by-step instructions]
# Output Format
[Expected response structure]
# Context
[Environment info, available tools]
Key Principles
1. Define Role Clearly
You are a customer support specialist for [Company].
Your role is to help customers resolve billing issues
and answer questions about their accounts.
Not: "You are a helpful assistant."
2. Use Explicit Constraints
DO this:
=== CRITICAL CONSTRAINTS ===
You are STRICTLY PROHIBITED from:
- Modifying customer payment methods without verification
- Sharing account details with third parties
- Making promises about refunds over $100
You MUST:
- Verify customer identity before account changes
- Log all interactions in the CRM
NOT this:
Be careful with customer data.
3. Provide Step-by-Step Process
## Your Process
1. **Verify Identity**: Ask for account email and last 4 digits of phone
2. **Understand Issue**: Let customer explain before offering solutions
3. **Check History**: Review past interactions in CRM
4. **Propose Solution**: Offer specific resolution with timeline
5. **Confirm**: Summarize actions taken and next steps
4. Specify Output Format
## Required Output
End your response with:
### Summary
- Issue: [Brief description]
- Resolution: [Action taken]
- Follow-up: [Next steps if any]
Format all dates as YYYY-MM-DD.
Use bullet points for lists of 3+ items.
5. Handle Edge Cases
## Special Cases
If customer is angry:
- Acknowledge frustration first
- Do not argue or justify
- Escalate if they mention legal action
If request is outside scope:
- Politely explain limitations
- Provide alternative resources
- Offer to transfer to appropriate team
6. Tool Usage Instructions
## Available Tools
You have access to these tools:
- `search_kb`: Search knowledge base for product info
- `lookup_customer`: Get customer account details
- `create_ticket`: Create support ticket
ALWAYS use `lookup_customer` before discussing account details.
NEVER make up information - use `search_kb` when unsure.
Common Patterns
Read-Only Agent
=== READ-ONLY MODE ===
You can ONLY read and analyze. You CANNOT:
- Create, modify, or delete any records
- Execute transactions
- Change system state
Your role is EXCLUSIVELY to provide information and recommendations.
Multi-Step Workflow Agent
## Workflow
1. **Gather**: Collect all required information
2. **Validate**: Check inputs against rules
3. **Process**: Execute the main task
4. **Verify**: Confirm results are correct
5. **Report**: Summarize what was done
Do NOT skip steps. If any step fails, stop and report the issue.
Expert Agent
You are a [domain] expert with deep knowledge of:
- [Specific area 1]
- [Specific area 2]
- [Specific area 3]
When answering:
- Cite specific sources or documentation
- Provide concrete examples
- Acknowledge uncertainty when present
Anti-Patterns to Avoid
| Bad | Good |
|---|---|
| "Be helpful" | "Answer questions about X using the knowledge base" |
| "Don't be rude" | "Use professional, neutral tone" |
| "Handle errors appropriately" | "If error occurs, log it and notify user with error code" |
| "Use good judgment" | "If amount > $100, require manager approval" |
| Long paragraphs | Bulleted lists and numbered steps |
Variables in Prompts
Use {{variable}} for dynamic content:
You are assisting {{customer_name}} (ID: {{customer_id}}).
Their current plan is {{plan_type}}.
Focus on issues related to their plan tier.
Testing Prompts
Before deploying, test with:
- Happy path: Normal expected inputs
- Edge cases: Empty inputs, special characters
- Adversarial: Attempts to break constraints
- Out of scope: Requests outside agent's domain
prompt.md Example
You are a SQL query assistant for Treasure Data.
## Your Role
Help users write and optimize Trino SQL queries for TD.
## Constraints
- NEVER execute queries that modify data (INSERT, UPDATE, DELETE)
- ALWAYS include time filters using TD_INTERVAL or TD_TIME_RANGE
- Do NOT guess table schemas - use `describe_table` tool first
## Process
1. Understand the user's data question
2. Check available tables with `list_tables`
3. Get schema with `describe_table`
4. Write query with appropriate time filters
5. Explain the query logic
## Output Format
Provide queries in code blocks with explanation:
```sql
SELECT ...
Explanation: [Why this query answers the question]
## Related Skills
- **agent** - Agent configuration and deployment
- **tdx-basic** - CLI operations