Federated from workspace · PRD-001 · Dental Clinic Revenue Operating System/docs/technical/CLINIC_AGENT_ORCHESTRATION.md Do not edit canonical truth here — update the source repo, then re-run npm run docs:sync.

---

Clinic Agent Orchestration Layer

Status: Phase 1 implemented (2026-07-04)
Authority: AI module · App\Modules\AI\Application\Orchestration\ClinicAgent

Problem statement

The Clinic Agent previously routed messages through English keyword intent detection, then either:

• returned static workflow templates (legacy-intent), or
• dumped a daily operational snapshot (0 appointments today).

That is intent-based chatbot architecture, not modern agent architecture.

Target architecture

User message
    ↓
Conversation Manager (session state + DB thread)
    ↓
Context Builder (role, permissions, clinic snapshot, page)
    ↓
Goal Planner (what is the user trying to accomplish?)
    ↓
Task Planner (ordered steps + missing information)
    ↓
Tool Router (which tools, which arguments)
    ↓
Reasoning Engine (LLM with orchestration context)
    ↓
Tool Execution (observation loop)
    ↓
Reflection & Validation
    ↓
Response Composer

The LLM is one component. Business truth, permissions, and tool execution remain platform-owned.

Implemented components (Phase 1)

Component	Class	Responsibility
Orchestrator	ClinicAgentOrchestrator	Pipeline entry, LLM + deterministic fallback
Context Builder	ClinicAgentContextBuilder	Role, permissions, clinic snapshot
Goal Planner	ClinicAgentGoalPlanner	Goal type + missing information + follow-up memory
Task Planner	ClinicAgentTaskPlanner	Step plan with tool bindings
Tool Router	ClinicAgentToolRouter	Tool ranking and argument assembly
Session State	ClinicAgentSessionStateStore	Goal, entity references, active plan
Prompt Builder	ClinicAgentOrchestrationPromptBuilder	Injects plan into LLM system prompt
Reflection	ClinicAgentReflectionValidator	Blocks ungrounded snapshot hallucinations
Deterministic Executor	ClinicAgentDeterministicExecutor	Tool plan execution when LLM unavailable

Removed anti-patterns (Phase 1)

• legacy-intent execution path — removed from ClinicOperationsAgentService
• Direct shouldAnswerFromClinicData() LLM bypass — all operational turns go through orchestrator
• Static workflow dump without tools — workflows now include tool execution plan

Roadmap

Phase	Capability	Status
1	Orchestration layer + remove legacy-intent	Done
2	LLM goal classifier (structured JSON)	Planned
3	Skill graph (register_patient, create_lead, book_appointment)	Planned
4	Full conversation state machine UI	Planned
5	Entity memory + pronoun resolution	Partial (session state)
6	Dedicated reasoning pass before tools	Planned
7	Stronger reflection against business policies	Partial
8	RAG over admin help + clinic docs	Planned

Configuration

• ai.copilot.agent_enabled — LLM path on/off (deterministic orchestration still runs)
• ai.copilot.fallback_to_rules — when LLM fails, run deterministic tool plan
• ai.copilot.max_tool_rounds — LLM tool loop cap

Testing

Feature tests: ClinicAgentConversationRoutingTest, ClinicAgentTest

Verify orchestration metadata on responses:

$response->metadata['orchestration'] === true
$response->metadata['goal']['type'] // e.g. register_patient