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

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:

1. Happy path: Normal expected inputs
2. Edge cases: Empty inputs, special characters
3. Adversarial: Attempts to break constraints
4. 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