Pipeline Orchestration

Relevant source files

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

• orchestrator.py
• app.py
• memory_utils.py
• agents/triage_agent.md
• agents/manager_briefing_agent.md
• README.md

The Pipeline Orchestration system in BrightPath is a multi-agent workflow designed to automate the processing of inbound customer communications. Every message entering the system passes through a sequential three-agent pipeline powered by Claude LLM models, which classifies the intent, executes specialist logic based on company policy, and generates a manager-facing briefing.

Sources: README.md:10-16, orchestrator.py:246-248

The orchestration layer manages state transitions between agents, maintains a persistent memory through file-based updates, and logs all interactions to a SQLite database for auditability and task tracking. It serves as the bridge between raw user input and the internal business logic defined in Markdown-based agent prompts.

Sources: README.md:20-25, app.py:149-166

Core Architecture

The orchestration architecture is built on a "Triage-Specialist-Briefing" pattern. It utilizes two distinct interfaces: a terminal-based CLI and a web-based Streamlit dashboard, both invoking the same underlying logic.

Sequential Processing Flow

The system processes messages in three distinct stages, passing the output of previous agents as context to the next.

The diagram shows the sequential flow from classification to specialized action and final reporting.
Sources: README.md:10-16, orchestrator.py:246-298, app.py:321-365

Agent Roles and Data Structures

Agent	Responsibility	Output Type	Primary Source
Triage Agent	Classification, sentiment, urgency detection, and routing.	JSON (Metadata)	triage_agent.md
Sales Agent	Lead qualification, CRM updates, and response drafting.	JSON (Actions/Draft)	sales_agent.md
CS Agent	Policy application (refunds/bookings) and issue resolution.	JSON (Actions/Draft)	customer_service_agent.md
Manager Briefing	Summary generation and human-action flagging.	JSON (Summary/Flags)	manager_briefing_agent.md

Sources: orchestrator.py:192-232, agents/triage_agent.md:4-10, agents/manager_briefing_agent.md:4-10

Pipeline Stages

1. Triage and Routing

The run_triage function initiates the pipeline. It provides the LLM with the inbound message, current memory files, and CRM data. The agent returns a JSON object containing a category and next_agent.

def run_triage(message: str, memory: str) -> dict:
    system = f"{load_agent('triage_agent')}\n\n--- MEMORY ---\n{memory}\n\n--- CRM ---\n{load_crm()}"
    return call_claude(system, f"Inbound message:\n\n{message}", "Triage Agent")

Sources: orchestrator.py:192-202, app.py:243-245

2. Specialist Execution

Based on the triage category, the orchestrator routes the message to either the sales_agent or customer_service_agent. If the category is admin, the orchestrator bypasses standard specialists to build a rich "Admin Context" from the database and memory files.
Sources: orchestrator.py:260-275, app.py:339-350

3. Manager Briefing and Notification

The final stage generates a summary intended for a human manager, specifically formatted for Telegram delivery. This agent identifies "Value Flags" (revenue opportunities) or "Risk Flags" (escalations).

Data Persistence and Memory Updates

Database Schema

The orchestrator maintains three primary tables in brightpath.db to track state across the pipeline.

Table	Purpose	Key Fields
events	Audit log of all pipeline runs	message, category, urgency, triage_out, agent_out
tasks	Action items for humans	task, priority, status, source
crm_log	Records of CRM modifications	contact, action, notes

Sources: orchestrator.py:44-77, app.py:149-166

File-Based Memory System

The system utilizes a "write-back" mechanism where agent decisions update Markdown files in the /memory directory. This ensures future pipeline runs have context on previous interactions.

Key utility functions in memory_utils.py include:

• update_customer_history(): Appends interaction logs to specific customer sections.
• add_open_task(): Injects new tasks into open_tasks.md under priority headers.
• update_decision_log(): Logs the technical reasoning for agent actions.

Sources: memory_utils.py:27-75, README.md:126-133

Technical Implementation Details

The orchestration logic is centralized in process_message (CLI) and run_pipeline (UI).

• LLM Configuration: The system uses claude-sonnet-4-5 for complex reasoning (Triage/Specialist) and claude-haiku for fast summary generation (Briefing).
• Context Injection: On every run, the orchestrator dynamically loads Markdown content from the /agents and /memory folders to construct the system prompt.
• Error Handling: JSON responses from the LLM are validated and stripped of markdown code fences before being parsed into Python dictionaries.

Sources: orchestrator.py:32-34, orchestrator.py:169-183, app.py:133-146

Summary

The Pipeline Orchestration system transforms unstructured inbound messages into actionable business data. By chaining specialized agents and maintaining a hybrid persistence layer (SQL + Markdown), the system provides a robust framework for automated customer operations while ensuring human oversight through the Manager Briefing stage.

Sources: README.md:10-25, orchestrator.py:298-315