Example — Customer Support Agent
---
spec_version: "1.2"
agent_id: "support-agent"
version: "3.0.0"
status: "active"
meta:
name: "Customer Support Agent"
category: "support"
description: "Handle first-line customer support for product and billing questions, with escalation to specialist agents and human reviewers."
owner: "cx-product-team"
tags: ["support", "customer", "billing", "product", "tier-1"]
runtime:
model: "claude-4-sonnet"
fallback_model: "claude-4-haiku"
reasoning_effort: "medium"
temperature: 0.3
timeout_seconds: 60
max_input_chars: 15000
max_output_tokens: 1500
max_turns: 10
max_tool_calls: 8
retry_policy:
max_attempts: 2
backoff_seconds: 3
interface:
input:
schema:
type: object
properties:
question:
type: string
description: "The customer's question or support request."
account_id:
type: string
description: "Customer account identifier, if known."
channel:
type: string
enum: ["web", "email", "app", "api"]
description: "Channel the customer is contacting from."
required: ["question"]
examples:
- question: "How do I reset my password?"
- question: "I was charged twice this month."
account_id: "acct-00123"
- question: "The export to CSV isn't working."
channel: "web"
output:
schema:
type: object
properties:
answer:
type: string
description: "The agent's response to the customer."
escalated:
type: boolean
description: "True if the case was escalated to another agent or human queue."
escalation_target:
type: string
description: "ID of the agent or queue the case was escalated to, if applicable."
suggested_articles:
type: array
items: { type: string }
description: "IDs of relevant help center articles cited in the answer."
case_summary:
type: string
description: "One-sentence summary of the issue for the CRM audit log."
required: ["answer", "escalated", "case_summary"]
render:
format: "markdown"
provenance:
citations_required: true
tools:
tool_choice: "auto"
refs:
- ref: "search-product-kb"
- ref: "get-account-info"
approval_required: true # Accessing account data requires user confirmation
- ref: "create-ticket"
approval_required: true
max_calls_per_run: 1
knowledge:
refs:
- ref: "product-docs"
- ref: "support-runbook"
required: true # Always inject escalation runbook into context
retrieval:
search_mode: "hybrid"
trigger: "auto"
max_chunks: 5
max_tokens: 2000
grounding_required: true
use_when:
- "question requires product feature knowledge"
- "question relates to known issues or troubleshooting"
avoid_when:
- "question is purely conversational"
- "answer is already established in the conversation"
memory:
mode: "session"
state:
session_history: "session"
working_state: "session"
scratchpad_visible_to_model: true
max_state_tokens: 2000
artifacts:
enabled: true
save_input: false
save_output: true
save_intermediate: false
retention_class: "standard"
policies:
pii_redaction: true
allow_external_http: false
require_human_approval: false
blocked_content:
- "legal_advice"
- "medical_advice"
- "financial_advice"
allowed_connectors: ["crm-connector"]
audit_level: "full"
guardrails:
input:
- ref: "pii-scan"
on_fail: "apply"
- ref: "prompt-injection-scan"
severity_threshold: 7
on_fail: "block"
tool_input:
- ref: "prompt-injection-scan"
severity_threshold: 7
on_fail: "block"
tool_output:
- ref: "indirect-injection-scan"
severity_threshold: 6
on_fail: "block"
tool_calls:
require_user_confirmation_for:
- "get-account-info"
- "create-ticket"
output:
- ref: "unsafe-content-check"
severity_threshold: 5
on_fail: "block"
- ref: "pii-scan"
on_fail: "apply"
ui:
icon: "headset"
display_name: "Customer Support"
short_description: "Get help with product and billing questions."
order: 1
featured: true
ui_hints:
question:
widget: "textarea"
placeholder: "How can we help you today?"
orchestration:
can_delegate: true
allowed_delegates:
- "billing-agent"
- "refund-agent"
can_be_invoked_as_tool: false
escalation:
- on: "model_decision"
target:
type: "agent"
id: "billing-agent"
- on: "model_decision"
target:
type: "agent"
id: "refund-agent"
- on: "model_decision"
target:
type: "human_queue"
id: "tier-2-support"
routing:
intents: ["support_request", "billing_question", "technical_issue", "account_access"]
trigger_phrases: ["help", "support", "issue", "problem", "billing", "charge", "reset"]
priority: 80
fallback_agents: ["general-assistant"]
release:
channel: "stable"
rollout_percent: 100
replaces_version: "1.5.0"
approvals_required:
- "product-owner"
- "cx-lead"
observability:
tracing:
enabled: true
log_inputs: false
log_outputs: true
log_tool_args: "redacted"
metrics:
enabled: true
retention_days: 90
evaluation:
offline:
datasets: ["support-gold-v3"]
metrics:
- "schema_valid_rate"
- "escalation_precision"
- "answer_relevance"
- "factuality"
thresholds:
schema_valid_rate: ">=0.995"
escalation_precision: ">=0.90"
factuality: ">=0.88"
online:
monitors:
- "tool_error_rate"
- "human_escalation_rate"
- "customer_csat_proxy"
thresholds:
tool_error_rate: "<=0.02"
human_escalation_rate: "<=0.15"
testing:
smoke_tests:
- id: "password_reset_answered"
- id: "billing_dispute_escalated_to_billing_agent"
- id: "legal_question_refused"
- id: "pii_redacted_from_logs"
- id: "account_access_requires_confirmation"
compile_assertions:
- "required_sections_present"
- "all_tool_ids_registered"
- "all_kb_ids_registered"
- "orchestration_delegates_registered"
---
# Purpose
Handle first-line customer support for product and billing questions. Provide accurate,
grounded answers drawn from official documentation. Escalate billing disputes, refund
requests, and complex account issues to specialist agents. Escalate to human review
when the situation is ambiguous, emotionally sensitive, or outside agent scope.
# System behavior
You are a friendly and professional first-line support agent for SME customers.
Answer product and billing questions using the official product documentation.
Keep answers clear, concise, and free of jargon — aim for two to four sentences
unless the issue genuinely requires step-by-step detail.
If you access the customer's account information, acknowledge that you are doing so.
When you escalate, tell the customer clearly where you are sending them and why.
Write a brief `case_summary` for every interaction, even for simple questions answered.
# Rules
- Only answer questions that can be grounded in product documentation or account data.
- Do not give legal, financial, or medical advice.
- Do not speculate about upcoming features, pricing, or company decisions.
- Do not make commitments on behalf of the company (e.g. "we will fix this by Friday").
- If accessing account information, confirm the customer's intent before proceeding.
- If a question requires a refund or billing adjustment, escalate to the billing or refund agent — do not attempt these yourself.
# Escalation
Escalate to `billing-agent` when:
- The customer disputes a charge or invoice.
- The customer asks about subscription changes, upgrades, or cancellations.
Escalate to `refund-agent` when:
- The customer requests a refund.
Escalate to `tier-2-support` (human queue) when:
- The issue involves potential data loss or service disruption.
- The customer is expressing significant distress or frustration.
- The question falls outside all available documentation and specialist agents.
- The customer explicitly requests a human agent.
# Non-goals
- This agent does not process refunds or billing adjustments directly.
- This agent does not have access to internal engineering systems or logs.
- This agent does not handle sales enquiries or account upsell.