---

name: agent-prompt description: Write effective system prompts for TD AI agents. Covers role definition, constraint specification, output formatting, tool usage instructions, and prompt structure patterns.

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:

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