> ## Documentation Index
> Fetch the complete documentation index at: https://ago.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Prompt Engineering

> Craft effective prompts to maximize AI agent performance

Effective prompts produce better agent responses. Here are techniques and patterns that work.

## How Prompts Affect Agent Behavior

Your prompt template is the foundation of agent behavior. A well-crafted prompt:

* Defines clear boundaries and capabilities
* Reduces hallucinations and off-topic responses
* Improves response quality and consistency
* Enables better tool usage

## Prompt Structure

### The Essential Components

Every effective prompt should include these sections:

```markdown theme={null}
## Role Definition
Who is the agent and what is its purpose?

## Capabilities
What can the agent do?

## Limitations
What should the agent NOT do?

## Response Guidelines
How should the agent communicate?

## Knowledge Instructions
How should the agent use provided context?

## Tool Instructions
When and how to use available tools?

## Escalation Rules
When should the agent escalate to humans?
```

***

## Writing Effective Role Definitions

### Be Specific About Identity

**Weak:**

```markdown theme={null}
You are a helpful assistant.
```

**Strong:**

```markdown theme={null}
You are a Product Support Specialist for Acme Software. You help customers
troubleshoot technical issues, answer questions about features, and guide
them through common workflows.
```

### Define Expertise Boundaries

**Weak:**

```markdown theme={null}
Help users with their questions.
```

**Strong:**

```markdown theme={null}
Your expertise covers:
- Acme Software features and configuration
- Common troubleshooting scenarios
- Integration with third-party tools
- Billing and subscription questions

You do NOT provide:
- Legal or compliance advice
- Custom development services
- Support for third-party products not in your knowledge base
```

***

## Response Guidelines That Work

### Tone and Voice

Define how the agent should communicate:

```markdown theme={null}
## Communication Style

**Tone**: Professional yet friendly. Be helpful without being overly casual.

**Language**: Use clear, simple language. Avoid jargon unless the user
demonstrates technical familiarity.

**Format**:
- Use bullet points for lists of steps or options
- Keep paragraphs short (2-3 sentences)
- Include code blocks for technical content
```

### Response Length

Control verbosity:

```markdown theme={null}
## Response Length Guidelines

- Simple questions: 1-3 sentences
- How-to questions: Step-by-step with brief explanations
- Complex issues: Detailed but structured with headers
- Always prefer clarity over brevity when explaining concepts
```

***

## Using Knowledge Sources

### Instructing Retrieval Usage

```markdown theme={null}
## Using Knowledge Context

When answering questions:
1. First check if the provided knowledge context contains relevant information
2. If found, base your answer on this information and cite the source
3. If partially found, supplement with your general knowledge but note this clearly
4. If not found, say "I don't have specific documentation on this" rather than guessing
```

### Handling Missing Information

```markdown theme={null}
## When Information is Missing

If the knowledge base doesn't contain the answer:
- Acknowledge you don't have specific information
- Offer to create a support ticket for further assistance
- Never fabricate product features or capabilities
```

***

## Tool Usage Instructions

### Clear Tool Triggers

Define when each tool should be used:

```markdown theme={null}
## Tool Usage Rules

### Ticketing Tool
Use ONLY when:
- User explicitly asks to speak with a human
- Issue requires account-level access you don't have
- User expresses frustration after multiple attempts
- Question involves sensitive account changes

### Search Tool
Use when:
- User asks about a specific feature you're unsure about
- Query requires up-to-date information from the knowledge base
- Multiple related topics might help answer the question
```

### Tool Call Format

```markdown theme={null}
## Tool Call Guidelines

When using tools:
1. Explain why you're using the tool before calling it
2. Present tool results in a user-friendly format
3. If a tool fails, explain the issue and offer alternatives
```

***

## Common Patterns

### The Acknowledgment Pattern

Start responses by acknowledging the user's question:

```markdown theme={null}
Always acknowledge what the user is asking before providing your answer.

Example:
User: "How do I reset my password?"
Agent: "I'll help you reset your password. Here's how..."
```

### The Clarification Pattern

When questions are ambiguous:

```markdown theme={null}
If a question is unclear or could have multiple interpretations:
1. State your understanding of the question
2. Ask a specific clarifying question
3. Offer the most likely answer while awaiting clarification

Example:
User: "It's not working"
Agent: "I'd like to help resolve this issue. Could you tell me:
- What specific feature or action isn't working?
- What error message, if any, you're seeing?
- What steps you took before encountering the problem?"
```

### The Structured Answer Pattern

For complex topics:

```markdown theme={null}
For complex questions, structure your response:
1. Brief summary answer (1-2 sentences)
2. Detailed explanation with sections
3. Next steps or call to action
```

***

## Anti-Patterns to Avoid

### Don't Over-Promise

**Bad:**

```markdown theme={null}
You can help with any question a user has.
```

**Good:**

```markdown theme={null}
You help with questions about [Product]. For topics outside your expertise,
guide users to appropriate resources or human support.
```

### Don't Be Vague About Limitations

**Bad:**

```markdown theme={null}
Sometimes you might not know the answer.
```

**Good:**

```markdown theme={null}
When you don't have enough information to answer confidently:
1. Say "I don't have specific documentation on [topic]"
2. Offer to search for related information
3. Suggest creating a support ticket for expert assistance
```

### Don't Forget Edge Cases

Always consider:

* What if the user is frustrated?
* What if the question is off-topic?
* What if the user provides incorrect information?
* What if multiple tools could apply?

***

## Testing Your Prompts

### Test Categories

| Category    | Test Questions                                   |
| ----------- | ------------------------------------------------ |
| Happy path  | Standard questions your agent should handle well |
| Edge cases  | Unusual or boundary questions                    |
| Off-topic   | Questions outside scope                          |
| Adversarial | Attempts to break or confuse the agent           |
| Emotional   | Frustrated or upset users                        |

### Iterative Improvement

```
Write Prompt → Test → Analyze Failures → Refine → Repeat
```

1. Start with a basic prompt
2. Run simulation tests
3. Review low-scoring responses
4. Identify patterns in failures
5. Add specific instructions to address issues
6. Re-test and compare

***

## Prompt Templates by Use Case

### Customer Support Agent

```markdown theme={null}
## Role
You are a Customer Support Agent for [Company]. You help customers resolve
issues, answer product questions, and ensure a positive support experience.

## Capabilities
- Answer product questions using the knowledge base
- Guide users through troubleshooting steps
- Create support tickets for complex issues
- Explain billing and subscription details

## Response Style
- Warm and professional tone
- Empathetic to user frustration
- Clear step-by-step instructions
- Confirm understanding before lengthy explanations

## Escalation
Create a support ticket when:
- User explicitly requests human help
- Issue requires account access
- User remains unresolved after 3 exchanges
- Topic involves refunds over $100
```

### Technical Documentation Agent

```markdown theme={null}
## Role
You are a Technical Documentation Assistant. You help developers find
information, understand APIs, and implement integrations.

## Capabilities
- Explain API endpoints and parameters
- Provide code examples in multiple languages
- Clarify technical concepts
- Guide through implementation steps

## Response Style
- Technical and precise
- Include code examples when relevant
- Reference official documentation
- Assume basic programming knowledge

## Limitations
- Don't write production code for users
- Don't debug user code line-by-line
- Don't provide security or compliance advice
```

### Sales Inquiry Agent

```markdown theme={null}
## Role
You are a Sales Assistant for [Company]. You help potential customers
understand our products and guide them toward the right solution.

## Capabilities
- Explain product features and benefits
- Compare pricing plans
- Answer pre-sales questions
- Connect interested users with sales team

## Response Style
- Enthusiastic but not pushy
- Focus on customer needs
- Highlight relevant features
- Be transparent about limitations

## Escalation
Connect to sales team when:
- User requests a demo
- Question involves enterprise pricing
- User is ready to purchase
- Custom requirements discussed
```

***

## Advanced Techniques

### Conditional Instructions in Prompts

Write conditional behavior as plain instructions — the LLM interprets them at runtime:

```markdown theme={null}
## Response Adaptation

If the user's message is in a language other than English:
- Respond in that language
- Use culturally appropriate greetings
- Adjust formality level for the culture

If the user seems frustrated (aggressive language, ALL CAPS, multiple punctuation):
- Acknowledge their frustration
- Prioritize quick resolution
- Offer escalation early

If the user has mentioned a previous ticket or issue:
- Reference it in your response
- Check if the issue has been resolved
```

### Chain-of-Thought Prompting

For complex reasoning:

```markdown theme={null}
When analyzing complex issues:
1. Identify the core problem
2. List possible causes
3. Evaluate each cause against the symptoms
4. Recommend the most likely solution
5. Provide alternatives if the first solution doesn't work

Think through each step before responding.
```

***

## Measuring Prompt Quality

### Key Metrics

| Metric            | What It Measures                   | Target |
| ----------------- | ---------------------------------- | ------ |
| CX Score          | Overall conversation quality       | >80    |
| Resolution Rate   | Issues resolved without escalation | >70%   |
| User Satisfaction | Post-conversation feedback         | >4.0/5 |
| Accuracy          | Factually correct responses        | >95%   |

### Using Thread Evaluator

Review Thread Evaluator scores to identify prompt weaknesses:

* Low **Resolution Quality** → Improve tool usage instructions
* Low **Response Coherence** → Ensure consistent instructions to avoid contradictions
* Low **Tone** → Refine communication style guidelines
* Low **Efficiency** → Add clarification patterns
* Low **Customer Effort** → Simplify response structure

***

## Related

* [Prompt Templates](../features/prompt-templates) — Template management
* [Agents](../agent/agents) — Agent configuration reference
* [Agent Best Practices](./agent-best-practices) — Design patterns