Prompts

Your agent’s prompt is its brain—the instructions that shape how it talks, thinks, and helps customers. Chanl’s prompt library helps you build, test, and share effective prompts that actually work.

Why Prompt Management Matters

Writing a good agent prompt is hard. Managing dozens of them across multiple agents is harder. The prompt library helps you:

Find what works - Access proven prompts from the community
Test before deploying - Validate new prompts with scenarios
Track improvements - See how prompt changes affect performance
Reuse across agents - Don’t reinvent the wheel

Example: You need a customer service prompt. Instead of starting from scratch, grab the “Empathetic Support Agent” from the library, customize it for your business, test with 5 scenarios, and deploy in 20 minutes.

How Prompts Work

A prompt tells your agent:

Who it is - Identity and role (e.g., “You are a helpful customer service agent”)
How to talk - Tone, style, personality
What to do - Goals, tasks, procedures
What not to do - Boundaries, restrictions

Good Prompt → Consistent Behavior → Better Customer Experiences

Accessing the Prompt Library

Via UI
Via API

Navigate to Prompts in the sidebar to see:

Your workspace prompts (custom ones you’ve created)
Global library (curated, high-performing prompts)
Filter by category, industry, or tags
View performance metrics for each prompt

# List all available prompts
curl https://api.chanl.ai/v1/prompts \
  -H "Authorization: Bearer YOUR_API_KEY"

Response:

{
  "prompts": [
    {
      "id": "prompt_abc123",
      "name": "Empathetic Customer Service",
      "category": "customer-service",
      "source": "global",
      "tags": ["empathy", "support", "high-performance"],
      "avgScore": 91.3,
      "usageCount": 487
    }
  ]
}

Prompt Library Categories

Customer Service Prompts

Empathetic Support Agent

Best for: Customer service calls where empathy mattersCore instructions:

Acknowledge customer emotions first
Use phrases like “I understand” and “I can see why”
Focus on resolution, not just response
End with confirmation of satisfaction

Performance: 91% average score across 500+ simulations

curl https://api.chanl.ai/v1/prompts/empathetic-support \
  -H "Authorization: Bearer YOUR_API_KEY"

Efficient Problem Solver

Best for: High-volume support requiring quick resolutionsCore instructions:

Get to the problem immediately
Use closed questions for faster qualification
Provide step-by-step solutions
Minimize small talk

Performance: 87% average score, 30% faster than baseline

Technical Troubleshooter

Best for: Complex technical support issuesCore instructions:

Ask diagnostic questions systematically
Explain technical concepts simply
Verify each step before moving forward
Document resolution for customer

Performance: 89% average score, 15% lower escalation rate

Sales Prompts

Consultative Sales Agent

Best for: Solution-oriented sales conversationsCore instructions:

Start with needs discovery
Ask about pain points and goals
Present solutions, not just features
Handle objections with empathy

Performance: 84% average score, 23% higher conversion

Direct Sales Closer

Best for: Transactional sales with clear offeringsCore instructions:

Lead with value proposition
Create urgency appropriately
Ask for commitment multiple times
Address price concerns directly

Performance: 81% average score, fastest time-to-close

Compliance-Focused Prompts

TCPA Compliant Outbound

Best for: Outbound sales calls requiring regulatory complianceCore instructions:

Start with identification and purpose
Provide call recording disclosure
Obtain verbal consent before continuing
Document opt-out requests immediately

Performance: 96% compliance rate across audits

HIPAA Healthcare Agent

Best for: Healthcare interactions handling patient informationCore instructions:

Verify identity before discussing details
Never mention PHI in recordings without consent
Follow data minimization principles
Provide privacy notices as required

Performance: 98% compliance rate

Creating Your Own Prompts

Start with a Template

Customize an existing prompt instead of starting from scratch:

Via UI
Via API

Find a prompt similar to what you need
Click “Duplicate to Workspace”
Customize for your business
Test with scenarios
Save to your library

# Duplicate and customize a prompt
curl -X POST https://api.chanl.ai/v1/prompts \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "basePromptId": "empathetic-support",
    "name": "Acme Customer Service Agent",
    "content": "You are a helpful customer service agent for Acme Corp...",
    "tags": ["customer-service", "acme", "production"]
  }'

Writing an Effective Prompt

Follow this structure:

1. Identity & Role
   "You are [role] for [company]..."

2. Core Personality
   "You are [traits: empathetic, professional, efficient]..."

3. Primary Goal
   "Your goal is to [main objective]..."

4. Key Behaviors
   - Always [important behavior]
   - Never [prohibited behavior]
   - When [situation], do [action]

5. Communication Style
   "Use [tone] language. [Length] responses. [Style] explanations."

6. Escalation Rules
   "Transfer to human when [conditions]..."

7. Compliance Requirements
   "You must [regulatory requirement]..."

Example: Custom Support Prompt

You are a customer service agent for TechCo, a B2B software company.

You are empathetic, knowledgeable, and solution-focused. You care about helping customers succeed with our product.

Your goal is to resolve customer issues quickly while maintaining a positive relationship.

Key behaviors:
- Acknowledge frustration before jumping to solutions
- Ask clarifying questions to understand the root cause
- Provide step-by-step instructions
- Confirm resolution before ending call
- Never blame the customer or make excuses

Communication style:
Use conversational, professional language. Keep responses under 3 sentences unless providing detailed instructions. Explain technical concepts in simple terms.

Escalation rules:
Transfer to human when:
- Customer explicitly requests it
- Issue requires code changes or engineering
- Customer is threatening legal action
- You've attempted 3 solutions without success

Tools available:
- lookup_account: Get customer account details
- check_service_status: Verify system status
- create_ticket: Log issues for engineering

Always look up the account before discussing specific issues.

Testing Prompts

Before deploying a new prompt, test it:

const chanl = require('@chanl/sdk');

// Create test scenario for new prompt
async function testPrompt(promptId, agentId) {
  // Apply prompt to agent
  await chanl.agents.updatePrompt(agentId, promptId);

  // Run test scenarios
  const scenario = await chanl.scenarios.create({
    name: `Prompt Test: ${promptId}`,
    prompt: 'Customer has billing question about recent charge',
    personas: ['polite', 'frustrated', 'confused'],
    agents: [agentId],
    scorecard: 'customer-service-quality'
  });

  // Wait for results
  const results = await chanl.scenarios.waitForCompletion(scenario.id);

  return {
    avgScore: results.avgScore,
    strengths: results.topCategories,
    weaknesses: results.bottomCategories,
    recommendation: results.avgScore >= 85 ? 'Deploy' : 'Needs improvement'
  };
}

// Test new prompt
const results = await testPrompt('prompt_new123', 'agent_abc');
console.log(results);
/*
{
  avgScore: 87,
  strengths: ['Communication', 'Empathy'],
  weaknesses: ['Problem Resolution'],
  recommendation: 'Deploy'
}
*/

A/B Testing Prompts

Compare two prompts to find the better one:

const chanl = require('@chanl/sdk');

async function comparePrompts(promptA, promptB, agentId) {
  // Create two test agents with different prompts
  const agentA = await chanl.agents.duplicate(agentId, {
    name: 'Test Agent A',
    promptId: promptA
  });

  const agentB = await chanl.agents.duplicate(agentId, {
    name: 'Test Agent B',
    promptId: promptB
  });

  // Run same scenarios on both
  const comparison = await chanl.scenarios.create({
    name: 'Prompt A/B Test',
    prompt: 'Customer service scenarios',
    personas: ['polite', 'frustrated', 'analytical'],
    agents: [agentA.id, agentB.id],
    scorecard: 'customer-service'
  });

  const results = await chanl.scenarios.waitForCompletion(comparison.id);

  return {
    winner: results.agents[agentA.id].avgScore > results.agents[agentB.id].avgScore ? 'A' : 'B',
    scoreA: results.agents[agentA.id].avgScore,
    scoreB: results.agents[agentB.id].avgScore,
    difference: Math.abs(results.agents[agentA.id].avgScore - results.agents[agentB.id].avgScore)
  };
}

const results = await comparePrompts('prompt_v1', 'prompt_v2', 'agent_abc');
console.log(`Winner: Prompt ${results.winner}`);
console.log(`Score difference: ${results.difference} points`);

Tracking Prompt Performance

Monitor how prompts perform over time:

# Get performance metrics for a prompt
curl https://api.chanl.ai/v1/prompts/prompt_abc123/analytics?days=30 \
  -H "Authorization: Bearer YOUR_API_KEY"

Response shows comprehensive performance data:

{
  "promptId": "prompt_abc123",
  "name": "Empathetic Support Agent",
  "timeRange": "30 days",
  "usage": {
    "totalCalls": 1247,
    "totalSimulations": 89,
    "activeAgents": 5
  },
  "performance": {
    "avgScore": 88.3,
    "trend": "improving",
    "scoresByCategory": {
      "Communication": 92,
      "Problem Resolution": 87,
      "Compliance": 91
    }
  },
  "comparison": {
    "vsWorkspaceAvg": "+6.2",
    "vsGlobalAvg": "+3.1"
  },
  "topScenarios": [
    "Billing inquiry - 94 avg score",
    "Refund request - 89 avg score"
  ],
  "strugglingScenarios": [
    "Technical troubleshooting - 78 avg score"
  ]
}

Prompt Variables

Make prompts reusable with variables:

// Create prompt with variables
const prompt = await chanl.prompts.create({
  name: 'Customizable Support Agent',
  content: `You are a customer service agent for {{company_name}}.

Your primary goal is to {{primary_goal}}.

When greeting customers, say "{{greeting}}"

Use a {{tone}} tone throughout the conversation.

Company-specific info:
- Return policy: {{return_policy}}
- Support hours: {{support_hours}}
- Escalation number: {{escalation_number}}`,
  variables: [
    {
      name: 'company_name',
      type: 'string',
      required: true
    },
    {
      name: 'primary_goal',
      type: 'string',
      default: 'resolve customer issues quickly and professionally'
    },
    {
      name: 'tone',
      type: 'enum',
      options: ['professional', 'friendly', 'casual'],
      default: 'professional'
    }
  ]
});

// Use prompt with custom values
await chanl.agents.updatePrompt('agent_abc123', prompt.id, {
  variables: {
    company_name: 'Acme Corp',
    primary_goal: 'help customers get the most value from our product',
    greeting: 'Thanks for calling Acme! How can I help you today?',
    tone: 'friendly',
    return_policy: '30 days, no questions asked',
    support_hours: '24/7',
    escalation_number: '1-800-555-0123'
  }
});

Version Control

Track prompt changes over time:

# View prompt history
curl https://api.chanl.ai/v1/prompts/prompt_abc123/versions \
  -H "Authorization: Bearer YOUR_API_KEY"

{
  "versions": [
    {
      "version": "v3",
      "createdAt": "2024-01-15T10:00:00Z",
      "createdBy": "user@company.com",
      "changes": "Added explicit escalation criteria",
      "avgScore": 88.3,
      "status": "active"
    },
    {
      "version": "v2",
      "createdAt": "2024-01-10T14:30:00Z",
      "createdBy": "user@company.com",
      "changes": "Simplified language, reduced jargon",
      "avgScore": 85.1,
      "status": "archived"
    },
    {
      "version": "v1",
      "createdAt": "2024-01-01T09:00:00Z",
      "createdBy": "user@company.com",
      "changes": "Initial version",
      "avgScore": 82.4,
      "status": "archived"
    }
  ]
}

Rollback to Previous Version

curl -X POST https://api.chanl.ai/v1/prompts/prompt_abc123/rollback \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "version": "v2"
  }'

Within Your Workspace

Make prompts available to your team:

# Create shared prompt
curl -X POST https://api.chanl.ai/v1/prompts \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Team Support Agent",
    "content": "You are a helpful support agent...",
    "visibility": "workspace",
    "tags": ["support", "shared", "approved"]
  }'

Contributing to Global Library

Submit high-performing prompts to help the community:

# Submit prompt for global library
curl -X POST https://api.chanl.ai/v1/prompts/prompt_abc123/submit-global \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "category": "customer-service",
    "description": "Empathetic support agent optimized for frustrated customers",
    "performanceData": {
      "avgScore": 91.3,
      "totalTests": 487,
      "industries": ["retail", "technology"]
    }
  }'

Best Practices

Start with Proven Prompts

Don’t reinvent the wheel. Use library prompts as starting points and customize for your needs.

Test Before Production

Always run scenarios before deploying a new prompt. Test with diverse personas and edge cases.

Make One Change at a Time

When optimizing prompts, change one thing at a time so you know what improved performance.

Use Clear, Specific Language

Vague instructions like “be helpful” don’t work. Specify exact behaviors: “Ask 3 questions to diagnose the issue.”

Include Examples

Show the agent what good looks like with example conversations or phrases.

Monitor Performance

Track prompt scores over time. If performance drops, investigate what changed.

Version Everything

Document why you made changes. Makes it easy to understand what worked and what didn’t.

Common Prompt Patterns

Adding Personality

❌ "Be friendly"
✅ "Use a warm, conversational tone. Include phrases like 'I'd be happy to help' and 'Great question!' Start with enthusiasm."

Handling Difficult Customers

❌ "Deal with angry customers"
✅ "When customer expresses frustration:
1. Acknowledge their feeling: 'I understand this is frustrating'
2. Apologize if appropriate: 'I'm sorry this happened'
3. Focus on solution: 'Let me help fix this right away'
4. Never get defensive or blame them"

Setting Boundaries

❌ "Don't do things outside your scope"
✅ "You can: [list specific capabilities]
You cannot: [list limitations]
When asked to do something you cannot do, respond: 'I'm not able to do that, but I can connect you with someone who can. Would you like me to transfer you?'"

Troubleshooting

Prompt not improving scores

Problem: Made changes but scores aren’t getting betterInvestigate:

Review failing transcripts - is agent following instructions?
Check if prompt is too long or complex
Test with fewer personas to isolate issues
Compare against baseline prompt performance
Verify scorecard criteria align with prompt goals

Inconsistent agent behavior

Problem: Agent follows prompt sometimes but not alwaysSolutions:

Make instructions more explicit and direct
Lower model temperature (0.5-0.7)
Add examples of desired behavior
Remove conflicting instructions
Put most important rules first

Agent ignoring parts of prompt

Problem: Agent follows some instructions but skips othersSolutions:

Shorten prompt (very long prompts get ignored)
Emphasize critical rules: “ALWAYS [behavior]” or “NEVER [behavior]”
Move important instructions to beginning
Test if multiple instructions conflict
Consider splitting complex behavior across multiple prompts

What’s Next?

Manage Agents

Apply your prompts to agents and test them

Run Scenarios

Validate prompt performance with test scenarios

Add Tools

Give your agents capabilities to match prompt instructions

Fine-Tune Models

Train custom models on conversations with best prompts

Overview

Test

Observe

Optimize

Prompts

Prompts

Why Prompt Management Matters

How Prompts Work

Accessing the Prompt Library

Prompt Library Categories

Customer Service Prompts

Sales Prompts

Compliance-Focused Prompts

Creating Your Own Prompts

Start with a Template

Writing an Effective Prompt

Example: Custom Support Prompt

Testing Prompts

A/B Testing Prompts

Tracking Prompt Performance

Prompt Variables

Version Control

Rollback to Previous Version

Within Your Workspace

Contributing to Global Library

Best Practices

Common Prompt Patterns

Adding Personality

Handling Difficult Customers

Setting Boundaries

Troubleshooting

What’s Next?

Manage Agents

Run Scenarios

Add Tools

Fine-Tune Models

Overview

Test

Observe

Optimize

​Prompts

​Why Prompt Management Matters

​How Prompts Work

​Accessing the Prompt Library

​Prompt Library Categories

​Customer Service Prompts

​Sales Prompts

​Compliance-Focused Prompts

​Creating Your Own Prompts

​Start with a Template

​Writing an Effective Prompt

​Example: Custom Support Prompt

​Testing Prompts

​A/B Testing Prompts

​Tracking Prompt Performance

​Prompt Variables

​Version Control

​Rollback to Previous Version

​Sharing Prompts

​Within Your Workspace

​Contributing to Global Library

​Best Practices

​Common Prompt Patterns

​Adding Personality

​Handling Difficult Customers

​Setting Boundaries

​Troubleshooting

​What’s Next?

Manage Agents

Run Scenarios

Add Tools

Fine-Tune Models

Prompts

Why Prompt Management Matters

How Prompts Work

Accessing the Prompt Library

Prompt Library Categories

Customer Service Prompts

Sales Prompts

Compliance-Focused Prompts

Creating Your Own Prompts

Start with a Template

Writing an Effective Prompt

Example: Custom Support Prompt

Testing Prompts

A/B Testing Prompts

Tracking Prompt Performance

Prompt Variables

Version Control

Rollback to Previous Version

Sharing Prompts

Within Your Workspace

Contributing to Global Library

Best Practices

Common Prompt Patterns

Adding Personality

Handling Difficult Customers

Setting Boundaries

Troubleshooting

What’s Next?