Adding New Specialist Agents

Relevant source files

The following files were used as context for generating this wiki page:

• orchestrator.py
• app.py
• agents/triage_agent.md
• agents/sales_agent.md
• agents/customer_service_agent.md
• README.md

Introduction

The BrightPath AI Operations System utilizes a three-agent pipeline to process inbound messages: a Triage Agent, a Specialist Agent (e.g., Sales or Customer Service), and a Manager Briefing Agent. Specialist agents are the core "brain" of the system, responsible for reading memory, applying company policies, drafting responses, and logging actions to the database.

Adding a new specialist agent allows the system to handle additional domains or complex business logic beyond current sales and service capabilities. This process involves defining the agent's persona and rules in a Markdown file and integrating the routing logic into the orchestrator.
Sources: README.md:12-16, app.py:539-586

Architecture Overview

The system architecture follows a sequential delegation pattern. The Triage Agent acts as the router, determining which specialist should handle the request based on the message content and existing memory.

This diagram illustrates how the Triage Agent selects the appropriate specialist before the Manager Briefing Agent finalizes the summary.
Sources: app.py:540-580, orchestrator.py:247-290

Step 1: Create the Agent Prompt Definition

New agents are defined as Markdown files located in the agents/ directory. These files serve as the system prompt for Claude and must follow a specific structure to ensure compatibility with the Python backend.

Required Markdown Sections

Section	Description
Role	Definition of the agent's persona and primary function.
Responsibilities	List of specific tasks the agent must perform.
Policies / Rules	Business logic, pricing, or procedural constraints.
Output Format	A strict JSON schema that the agent must return.

Standard Output Schema

Specialist agents must return a JSON object. While specific fields vary, they typically include:

• draft_response: The actual message intended for the customer.
• internal_action: A description of what needs to happen in the backend.
• open_task: (Optional) A string describing a task for the open_tasks.md file or database.
• agent_notes: Technical observations for logging.

Sources: agents/sales_agent.md:41-55, agents/customer_service_agent.md:41-57

Step 2: Update Triage Routing

To make the system aware of the new agent, you must modify agents/triage_agent.md. The Triage Agent must be instructed to identify the new category and set the next_agent field to the filename of your new specialist.

1. Modify Categories: Add the new domain to the Classification Categories list.
2. Update JSON Schema: Ensure the next_agent field description includes the new agent filename.

{
  "category": "sales|customer_service|escalation|admin|complex|new_category",
  "next_agent": "sales_agent|customer_service_agent|new_specialist_agent"
}

Sources: agents/triage_agent.md:14-20, agents/triage_agent.md:43-56

Step 3: Integrate with Orchestration Logic

The system's execution logic in app.py and orchestrator.py must be updated to handle the new agent's execution.

Modifying the Pipeline Runner

In app.py, the run_pipeline function (or process_message in orchestrator.py) handles the branching logic for Step 2 of the pipeline.

# Example modification in app.py
with st.spinner(f"Step 2 — {agent_label} processing..."):
    if category == "sales":
        agent_result = run_sales_agent(message, triage, memory)
    elif category == "new_category":
        agent_result = run_new_specialist_agent(message, triage, memory)
    else:
        agent_result = run_cs_agent(message, triage, memory)

Sources: app.py:560-575, orchestrator.py:270-285

Creating the Agent Call Function

You must define a Python function to load the agent's Markdown file and call the Anthropic API.

def run_new_specialist_agent(message, triage, memory):
    system = f"{load_agent('new_specialist_agent')}\n\n--- MEMORY ---\n{memory}\n\n--- CRM ---\n{load_crm()}"
    return call_claude(system, f"Original message:\n\n{message}")

Sources: app.py:471-480, orchestrator.py:214-225

Data Flow for New Agents

The following sequence diagram tracks how a message moves from Triage to a new specialist agent.

The Specialist Agent receives both the original message and the Triage Agent's analysis, ensuring it has full context for its response.
Sources: app.py:539-598, orchestrator.py:247-310

Conclusion

Adding a new specialist agent is a three-step process: defining the AI's behavior in a Markdown file, updating the Triage Agent's classification logic, and adding the execution branch in the Python orchestration layer. This modular design allows BrightPath to scale its operations to handle various administrative and operational domains without redesigning the core pipeline.
Sources: README.md:144-147, orchestrator.py:247-310