Customizing Agent Behaviors
Relevant source files
The following files were used as context for generating this wiki page:
Customizing agent behaviors in the BrightPath AI system is primarily achieved through modifying Markdown-based system prompts located in the agents/ directory. This architecture allows developers to adjust roles, pricing, policies, and response tones without modifying the underlying Python logic. The agents function within a multi-agent pipeline where the output of one agent informs the context of the next.
Sources: README.md:124-124, orchestrator.py:166-218
Agent Configuration Architecture
The system utilizes a file-based configuration for agent personas and logic. Each agent is defined by a .md file that specifies its role, specific responsibilities, business rules, and a strict JSON output schema. The orchestrator.py and app.py scripts load these files and inject them as system prompts into the Claude API calls.
The diagram shows how the system prompt is assembled by reading Markdown files before being sent to the LLM.
Sources: app.py:270-282, orchestrator.py:126-140
Triage Agent Customization
The Triage Agent acts as the initial router. Customizing this agent involves modifying how it classifies inbound messages into categories like sales, customer_service, escalation, or admin. It also handles sentiment detection and urgency assessment.
| Customization Area | Impacted Logic | Target File |
|---|---|---|
| Routing Rules | Changes which next_agent is selected | triage_agent.md |
| Urgency Mapping | Defines what constitutes 'high' vs 'low' urgency | triage_agent.md |
| Flagging Logic | Identifies VIPs, competitor mentions, or upsells | triage_agent.md |
Sources: agents/triage_agent.md:12-30
Specialist Agent Behavioral Logic
The specialist agents (Sales and Customer Service) are customized to follow specific company policies and maintain a consistent brand tone.
Sales Operations Specialist
Behavioral customization for the Sales Agent focuses on lead qualification tiers (Hot, Warm, Cold) and product pricing. By updating the "Products & Pricing" section in sales_agent.md, the agent automatically adjusts the recommendations it makes in its draft responses.
- Lead Tiers: Define thresholds for budget, decision-making authority, and timelines.
- Rules for Engagement: Includes instructions such as never quoting custom pricing and suggesting discovery calls for large groups (31+ people).
Sources: agents/sales_agent.md:12-35
Customer Service Specialist
Customization for the Customer Service agent involves defining strict operational policies for booking changes, refunds, and complaints.
The flow demonstrates the logic defined within the customer_service_agent.md policy section.
Sources: agents/customer_service_agent.md:12-32
Modifying Output Schemas
Each agent is constrained to return only valid JSON. Customizing these schemas allows the system to capture new data points or trigger different downstream actions in orchestrator.py.
Example: Manager Briefing Agent Output
The Manager Briefing Agent is designed to produce Telegram-ready summaries. Its schema includes fields for value_flag and risk_flag, which are used by the UI to render visual alerts.
{
"headline": "one line summary",
"urgency": "high|medium|low",
"telegram_summary": "short punchy message",
"value_flag": "revenue description or null",
"risk_flag": "risk description or null"
}
Sources: agents/manager_briefing_agent.md:20-33, app.py:442-448
Integration with Memory and CRM
Agent behavior is further influenced by the context provided from memory files (memory/) and CRM data (data/crm.json). When customizing behavior, developers must ensure the agent prompt contains instructions on how to interpret this data.
- Context Loading: The
load_memory()function inorchestrator.pycombines multiple Markdown files into a single context block. - Instruction Injection: Agents are instructed via their MD files to check specific memory files (e.g.,
sales_notes.md) before responding.
Sources: orchestrator.py:142-151, agents/sales_agent.md:29-29
Summary of Customization
Customizing agent behavior requires no Python changes. By editing the Markdown files in the agents/ directory, developers can redefine the system's operational logic, policy enforcement, and communication style. These changes are immediately reflected in the pipeline as the orchestrator injects these updated instructions into the next API request to the Claude model.
Sources: README.md:124-124, app.py:345-365