The Customer Service Agent
Relevant source files
The following files were used as context for generating this wiki page:
The Customer Service Agent is a specialized AI component within the BrightPath AI Operations System designed to handle post-sale customer interactions. It functions as the second stage in a three-agent pipeline, receiving routed requests from the Triage Agent to resolve queries related to bookings, refunds, invoices, and complaints.
This agent operates by synthesizing internal company policies, customer history, and CRM data to generate empathetic, professional, and policy-compliant responses. Its primary goal is to automate routine service tasks while identifying high-risk escalations that require human intervention.
Sources: README.md:9-12, agents/customer_service_agent.md:3-12
Architecture and Pipeline Integration
The Customer Service Agent is invoked as a "Specialist Agent" within the system orchestrator. It does not interact with the user directly but processes messages that have been pre-classified by the Triage Agent.
Data Flow and Input
When a message is categorized as customer_service or escalation, the system passes a rich context object to the Customer Service Agent. This context includes:
- System Prompt: The role and policy definitions from
agents/customer_service_agent.md. - Memory Context: Content from
company_context.md,customer_history.md, andopen_tasks.md. - CRM Data: Live contact information from
data/crm.json. - Triage Notes: Key fields extracted by the Triage Agent (e.g., urgency, sentiment, extracted names).
Sources: app.py:461-468, orchestrator.py:270-279, agents/triage_agent.md:15-20
Interaction Flow
The following sequence diagram illustrates the agent's position in the message processing lifecycle:
The flow ensures that every response is grounded in the latest customer data and company rules.
Sources: app.py:439-490, orchestrator.py:238-310
Core Operational Logic
The agent's decision-making is governed by four primary policy areas defined in its configuration. It uses these rules to determine if a policy applies and if an exception is required.
Policy Guidelines
| Policy Area | Rule Summary | VIP/Partner Exception |
|---|---|---|
| Booking Changes | Free if >7 days; £50 fee if 3-6 days; No refund if <48h (credit only). | Changes allowed up to 24h before with no fee. |
| Refunds | 100% if >14 days; 50% if 7-13 days; 0% within 7 days. | Medical emergencies handled with documentation. |
| Invoices | Sent within 24h; 30-day payment terms. | Flag overdue (>30 days) to admin. |
| Complaints | Always acknowledge and apologize. Escalated if regarding trainers/content. | 3+ complaints trigger a Priority Account Review. |
Sources: agents/customer_service_agent.md:14-41
Tone and Persona
The agent is instructed to maintain a "warm, professional, and solution-focused" tone. It is explicitly forbidden from becoming defensive and must use first names for VIP customers to provide a personal touch.
Sources: agents/customer_service_agent.md:43-50
Technical Implementation
In the codebase, the agent is called via the run_cs_agent (Streamlit) or run_customer_service_agent (Orchestrator) functions. Both functions utilize the Anthropic SDK to interface with Claude.
Implementation Snippet
# From app.py:467-470
def run_cs_agent(message, triage, memory):
system = f"{load_agent('customer_service_agent')}\n\n--- MEMORY ---\n{memory}\n\n--- CRM ---\n{load_crm()}\n\n--- TRIAGE ---\n{json.dumps(triage, indent=2)}"
return call_claude(system, f"Original message:\n\n{message}")
Sources: app.py:467-470, orchestrator.py:223-235
Structured Output Schema
The agent must return a valid JSON object. This structure allows the orchestrator to automatically log events and update the database without manual parsing.
| Field | Type | Description |
|---|---|---|
issue_type | string | One of: booking_change, refund, invoice, complaint, faq, escalation. |
policy_applies | boolean | Whether a standard policy covers the request. |
draft_response | string | The full email/message text for the customer. |
internal_action | string | Description of required back-office work. |
open_task | string | A task to be added to the system's open_tasks.md. |
escalate_to_manager | boolean | Flag to trigger human oversight. |
Sources: agents/customer_service_agent.md:52-68
Memory and State Management
The Customer Service Agent plays a key role in evolving the system's "memory" by providing the data used in memory_utils.py.
Automated Memory Updates
When specific scenarios occur, the orchestrator triggers updates to the Markdown memory files based on the agent's findings:
- Scenario 11 (Repeat Complaint): Updates
customer_history.mdanddecision_log.mdwhen the 3-complaint threshold is hit. - Scenario 13 (Overdue Invoice): Adds an entry to
open_tasks.mdto chase payment when a customer with an outstanding balance makes a new enquiry. - Scenario 18 (New Booking vs. Slow Payer): Logs the decision to hold a booking until an overdue invoice (e.g., INV-2026-047) is settled.
Sources: memory_utils.py:100-112, memory_utils.py:129-143, memory_utils.py:207-220
Decision Logic Flow
The flowchart below represents the logic the agent follows when processing a booking change request:
Conclusion
The Customer Service Agent serves as the primary engine for BrightPath’s operational consistency. By strictly adhering to predefined policies and maintaining a live link to customer history, it ensures that even complex requests—such as VIP exceptions or multi-complaint escalations—are handled according to business requirements. Its output integrates directly with the database and manager briefing systems to maintain high visibility on all customer service activity.