# Prompt Engineering

Master the art of crafting effective prompts to optimize AI agent behavior and response quality.

## What is Prompt Engineering?

Prompt engineering is the practice of designing, refining, and optimizing the instructions you give to AI agents to achieve desired outcomes. A well-crafted prompt can dramatically improve:

* Response accuracy
* Consistency
* Tone and style
* Task completion
* User satisfaction

## System Prompts vs User Prompts

### System Prompts

**Purpose**: Define the agent's identity, behavior, and constraints

**Location**: Agent configuration (not visible to users)

**Example:**

```
You are a technical support assistant for Acme Software.
You help users troubleshoot technical issues and answer
product questions.

Guidelines:
- Be patient and empathetic
- Provide step-by-step troubleshooting
- Always cite documentation sources
- Escalate to human support when needed

Tone: Professional yet friendly
Format: Clear, structured responses
```

### User Prompts

**Purpose**: The actual question or request from the user

**Location**: User input

**Example:**

```
"How do I reset my password?"
```

## Prompt Structure

### Effective System Prompt Template

```
[IDENTITY]
You are a [role] for [organization/product].

[PURPOSE]
Your purpose is to [primary goal].

[CAPABILITIES]
You can:
- [Capability 1]
- [Capability 2]
- [Capability 3]

[GUIDELINES]
Always:
- [Required behavior 1]
- [Required behavior 2]

Never:
- [Prohibited behavior 1]
- [Prohibited behavior 2]

[TONE & STYLE]
Tone: [Professional/Friendly/Technical]
Style: [Concise/Detailed/Conversational]
Format: [Preferred output format]

[EXAMPLES]
Example 1:
User: "[Sample question]"
You: "[Ideal response]"

[CONSTRAINTS]
- [Limitation 1]
- [Limitation 2]
```

## Prompt Engineering Techniques

### 1. Role Definition

Clearly define who the agent is:

**❌ Vague:**

```
You are helpful.
```

**✅ Specific:**

```
You are a senior customer success manager at TechCorp
with 10 years of experience helping enterprise customers
implement our SaaS platform.
```

**Why it works**: Specificity guides tone, depth, and perspective.

### 2. Task Breakdown

Break complex tasks into steps:

**❌ Generic:**

```
Help users with API integration.
```

**✅ Step-by-Step:**

```
When helping with API integration:

1. Verify prerequisites (API key, required libraries)
2. Provide code example in user's language
3. Explain each parameter
4. Show expected response format
5. List common errors and solutions
6. Offer to troubleshoot specific issues
```

### 3. Output Formatting

Specify desired response structure:

**❌ Unspecified:**

```
Answer questions about pricing.
```

**✅ Formatted:**

```
When answering pricing questions, use this format:

**Plan Name**: [Name]
**Monthly Cost**: [Price]
**Key Features**:
- [Feature 1]
- [Feature 2]
- [Feature 3]

**Best For**: [Use case description]
**Upgrade Path**: [Next tier information]
```

### 4. Few-Shot Examples

Provide examples of desired behavior:

```
Here are examples of how to respond:

Example 1 - Technical Question:
User: "What's the API rate limit?"
You: "Our API rate limit is 100 requests per minute
for Pro accounts and 1,000 requests per minute for
Enterprise accounts. Rate limit headers are included
in every response:

X-RateLimit-Limit: 100
X-RateLimit-Remaining: 95
X-RateLimit-Reset: 1640995200

[Source: API Documentation > Rate Limits]"

Example 2 - Billing Question:
User: "How do I upgrade my plan?"
You: "You can upgrade your plan in 3 simple steps:

1. Go to Settings > Billing
2. Click 'Upgrade Plan'
3. Select your new plan and confirm

Your upgrade takes effect immediately, and you'll be
charged prorated for the remainder of your billing cycle.

[Source: Billing Guide > Plan Upgrades]"
```

### 5. Constraint Setting

Define boundaries and limitations:

```
Important Constraints:

DO:
- Cite sources for all factual information
- Admit when you don't know something
- Offer to escalate complex issues
- Maintain user privacy

DON'T:
- Make up information
- Share pricing unless explicitly documented
- Promise features not yet released
- Access or reference personal user data
```

### 6. Tone Calibration

Specify communication style:

**Technical/Formal:**

```
Tone: Technical and precise
- Use industry terminology
- Provide detailed technical explanations
- Include code examples and API references
- Be thorough and comprehensive
```

**Friendly/Conversational:**

```
Tone: Warm and approachable
- Use simple language
- Add encouraging phrases
- Use analogies and examples
- Keep responses scannable
```

**Professional/Business:**

```
Tone: Professional and business-focused
- Emphasize ROI and business value
- Use industry metrics
- Be concise and action-oriented
- Focus on outcomes
```

### 7. Error Handling

Define behavior for uncertainty:

```
When Uncertain:

If you cannot find relevant information:
"I don't have specific information about [topic] in our
knowledge base. For the most accurate answer, I recommend:

1. Checking [specific resource]
2. Contacting [team/email] directly
3. Visiting [documentation URL]

Would you like help with something else?"

If the question is ambiguous:
"I want to make sure I understand correctly. Are you asking about:
A) [Interpretation 1]
B) [Interpretation 2]

Please let me know so I can provide the most helpful answer."
```

### 8. Context Handling

Guide multi-turn conversations:

```
Conversation Context:

- Remember key details from previous messages
- Reference earlier context naturally
- Track the user's current goal
- Build upon previous answers
- Maintain conversation coherence

Example:
User: "Tell me about the Enterprise plan"
You: [Provides Enterprise plan details]

User: "What about the pricing?"
You: "The Enterprise plan I mentioned costs $299/month
for up to 100 users, with volume discounts available..."
```

## Use Case-Specific Prompts

### Customer Support Agent

```yaml
Identity: |
  You are a tier-1 customer support agent for [Product Name].
  You're known for being patient, empathetic, and solutions-focused.

Primary Goal: |
  Resolve customer issues quickly while ensuring satisfaction.

Response Structure: |
  1. Acknowledge the issue with empathy
  2. Provide clear solution steps
  3. Verify resolution
  4. Offer additional help

Example:
  User: "The app keeps crashing!"
  You: "I understand how frustrating app crashes can be,
  and I'm here to help resolve this quickly.
  
  Let's try these troubleshooting steps:
  1. Clear the app cache (Settings > Apps > [App] > Clear Cache)
  2. Restart your device
  3. Update to the latest version (v2.5.1)
  
  After trying these steps, does the app still crash?
  If so, I can escalate this to our technical team."

Escalation Criteria: |
  Escalate to Tier 2 when:
  - Issue persists after standard troubleshooting
  - Requires code-level investigation
  - Involves billing disputes > $500
  - Customer explicitly requests manager
```

### Technical Documentation Agent

````yaml
Identity: |
  You are a senior developer relations engineer with expertise
  in API design and developer experience.

Primary Goal: |
  Help developers integrate with our platform successfully.

Response Structure: |
  1. Brief explanation
  2. Code example (user's preferred language)
  3. Expected output/response
  4. Common gotchas
  5. Related endpoints/docs

Code Format: |
  Always include:
  - Syntax-highlighted code blocks
  - Comments explaining key lines
  - Error handling
  - Real example data

Example:
  User: "How do I authenticate API requests?"
  You: "API authentication uses Bearer tokens in the
  Authorization header.
  
  ```python
  import requests
  
  headers = {
      'Authorization': 'Bearer YOUR_API_KEY',
      'Content-Type': 'application/json'
  }
  
  response = requests.get(
      'https://api.example.com/v1/users',
      headers=headers
  )
  
  if response.status_code == 200:
      users = response.json()
      print(f'Found {len(users)} users')
  else:
      print(f'Error: {response.status_code}')
````

Expected Response:

```json
{
  "users": [...],
  "total": 42,
  "page": 1
}
```

Common Issues:

* Ensure API key has required scopes
* Check rate limits (100 req/min)
* Keys starting with 'sk\_test\_' are for testing only

\[Source: API Reference > Authentication]"

Language Preference: | Ask for language preference if not specified: "I can provide examples in Python, JavaScript, Ruby, or cURL. Which would you prefer?"

````

### Sales Enablement Agent

```yaml
Identity: |
  You are a sales enablement specialist with deep product
  knowledge and understanding of customer pain points.

Primary Goal: |
  Help sales reps close deals by providing accurate product
  information, competitive intelligence, and value propositions.

Response Structure: |
  1. Direct answer to query
  2. Business value/ROI angle
  3. Competitive differentiator (if relevant)
  4. Supporting data/case study
  5. Next steps/talking points

Value-Focused Language: |
  Always frame responses around:
  - Time savings
  - Cost reduction
  - Revenue impact
  - Risk mitigation
  - Competitive advantage

Example:
  User: "What's the ROI of the Enterprise plan?"
  You: "The Enterprise plan typically delivers 300% ROI
  in the first year for mid-market companies:
  
  **Cost Savings** ($120K/year):
  - 40% reduction in support tickets → $80K saved
  - 50% faster customer onboarding → $40K saved
  
  **Revenue Impact** ($180K/year):
  - 25% increase in user adoption → $150K
  - 30% faster time-to-value → $30K
  
  **Total First-Year Impact**: $300K
  **Enterprise Plan Cost**: $100K
  **Net ROI**: 200% ($200K)
  
  **Customer Example**:
  TechCorp (similar size/industry) achieved these results
  within 6 months of deployment.
  
  **Competitive Advantage**:
  Unlike [Competitor], our Enterprise plan includes 24/7
  support and dedicated success manager.
  
  [Source: ROI Calculator, TechCorp Case Study]"

Pricing Guidance: |
  - Never discount without approval
  - Reference pricing sheet for current rates
  - Emphasize value over price
  - Offer ROI calculator for custom scenarios
````

## Advanced Techniques

### Chain-of-Thought Prompting

Encourage step-by-step reasoning:

```
When solving complex problems, think through step-by-step:

User: "Why is my API call failing?"

Your thought process (internal):
1. Check authentication first
2. Verify endpoint URL
3. Validate request format
4. Check rate limits
5. Review error message

Your response:
"Let's troubleshoot systematically. I'll check the most
common causes:

1. **Authentication** - Verify your API key is valid and
   hasn't expired. Check the Authorization header format.

2. **Endpoint** - Confirm you're using https://api.example.com
   (not http) and the correct version (/v1/)

3. **Request Format** - Ensure Content-Type is application/json
   and body is valid JSON

4. **Rate Limits** - Check if you've exceeded 100 req/min

Could you share the error message? That will help me pinpoint
the exact issue."
```

### Conditional Responses

Adapt based on user type or context:

```
Tailor responses based on user expertise:

If technical user (developer, engineer):
- Use technical terminology
- Provide code examples
- Reference API docs
- Skip basic explanations

If non-technical user (business user, customer):
- Use plain language
- Provide UI screenshots
- Focus on outcomes
- Explain concepts simply

Detect from:
- Question complexity
- Terminology used
- Context from profile
```

### Multi-Modal Responses

Combine different formats:

```
For comprehensive answers, use:

**Text Explanation**: Core information
**Code Example**: Practical implementation
**Diagram**: Visual representation (if available)
**Video**: Tutorial link (if relevant)
**Links**: Additional resources

Example:
"Here's how to set up webhooks:

**Overview**:
Webhooks notify your app of events in real-time.

**Setup Steps**:
1. Configure webhook URL
2. Select events
3. Verify endpoint

**Code Example**:
[Code block]

**Testing**:
[cURL example]

**Diagram**: [Link to webhook flow diagram]
**Video Tutorial**: [Link]
**Docs**: [Link]"
```

## Testing & Iteration

### A/B Testing Prompts

```python
# Version A: Direct
system_prompt_a = """
You are a support agent. Answer questions clearly.
"""

# Version B: Detailed
system_prompt_b = """
You are a senior support agent with 5 years experience.
Provide step-by-step guidance with empathy.
Always cite sources and offer escalation paths.
"""

# Test with same queries
# Compare: satisfaction, accuracy, escalation rate
# Deploy winner
```

### Prompt Metrics

Track these metrics:

* User satisfaction scores
* Response accuracy rate
* Citation quality
* Task completion rate
* Average response time
* Follow-up question rate

### Iterative Refinement

```
Week 1: Deploy initial prompt
↓
Collect feedback and metrics
↓
Week 2: Identify issues
- Too verbose?
- Missing key info?
- Wrong tone?
↓
Refine prompt
↓
Week 3: A/B test refinement
↓
Deploy improved version
↓
Repeat
```

## Common Pitfalls

### ❌ Too Vague

```
Bad: "Be helpful"
Good: "Provide step-by-step solutions with
explanations. Verify understanding before
marking issues resolved."
```

### ❌ Contradictory Instructions

```
Bad:
"Be concise."
"Provide comprehensive explanations."

Good:
"Be comprehensive but well-organized.
Use headings, bullet points, and clear structure
for scannability."
```

### ❌ No Examples

```
Bad: "Answer in a professional tone"
Good: [Provide 2-3 example Q&As demonstrating
the desired tone]
```

### ❌ Ignoring Edge Cases

```
Bad: [No guidance on uncertain situations]
Good: "If uncertain or if information is not in
the knowledge base, say: 'I don't have confirmed
information about this. Let me connect you with...'"
```

## Prompt Library

### Templates by Use Case

**General Support:** \[See Customer Support Agent above]

**Technical/Developer:** \[See Technical Documentation Agent above]

**Sales/Business:** \[See Sales Enablement Agent above]

**HR/Internal:**

```yaml
Identity: HR knowledge assistant
Goal: Help employees with HR policies and procedures
Tone: Friendly, confidential, supportive
Structure: Policy reference + practical guidance
```

**Legal/Compliance:**

```yaml
Identity: Compliance assistant
Goal: Provide accurate policy interpretation
Tone: Formal, precise, cautious
Structure: Policy citation + explanation + disclaimer
```

## Next Steps

* [Agent Configuration](/product/overview/configuration.md) - Apply prompt engineering in settings
* [Memory & Context](/product/overview/memory-context.md) - Maintain conversation context
* [Agent Tools](/product/advanced/agent-tools.md) - Extend capabilities with tools
* [Evaluation Framework](https://github.com/thrivapp/twig-help-docs/blob/staging/monitoring/evals.md) - Test prompt effectiveness


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://help.twig.so/product/overview/prompt-engineering.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.