Skip to main content
ClinicalPilot uses a multi-agent debate architecture. Each agent produces specialized output, which is synthesized into the final SOAP note.

ClinicalAgentOutput

Output from the Clinical Agent (differential diagnosis, risk scoring).
differentials
array
Ranked list of differential diagnoses (see Differential structure)
risk_scores
object
Clinical risk scores calculated (e.g., HEART Score, Wells PE, CHADS2-VASc)
soap_draft
string
Initial SOAP note draft from Clinical Agent
reasoning_trace
string
Step-by-step clinical reasoning trace
confidence
string
Confidence level: "high", "medium", "low"

Example

{
  "differentials": [
    {
      "diagnosis": "Acute Myocardial Infarction",
      "likelihood": "most likely",
      "reasoning": "Classic presentation with crushing chest pain radiating to arm",
      "confidence": "high",
      "supporting_evidence": ["Typical cardiac symptoms", "CV risk factors"]
    }
  ],
  "risk_scores": {
    "HEART Score": "6 — High risk"
  },
  "soap_draft": "S: 45yo M with HTN, DM2 presents with chest pain...\nO: BP 160/95, HR 110...",
  "reasoning_trace": "1. Patient presents with classic cardiac chest pain\n2. Risk factors include HTN, DM2, male, age 45\n3. HEART Score = 6 (high risk)\n4. Differential: STEMI vs NSTEMI vs unstable angina",
  "confidence": "high"
}

LiteratureAgentOutput

Output from the Literature Agent (evidence retrieval via PubMed).
evidence
array
Relevant literature hits from PubMed search
summary
string
Summary of evidence findings
contradictions
array
Contradictions or uncertainties found in literature
confidence
string
Confidence in evidence quality: "high", "medium", "low"

Example

{
  "evidence": [
    {
      "title": "HEART score for the assessment of patients with chest pain in the emergency department",
      "authors": "Backus BE, et al.",
      "journal": "Neth Heart J",
      "year": "2013",
      "pmid": "23415484",
      "snippet": "The HEART score is a simple and effective tool to risk-stratify patients with chest pain...",
      "relevance": "high"
    }
  ],
  "summary": "Strong evidence supports use of HEART Score for risk stratification in chest pain. AHA/ACC guidelines recommend immediate ECG and troponin for suspected ACS.",
  "contradictions": [],
  "confidence": "high"
}

SafetyAgentOutput

Output from the Safety Agent (medication safety, drug interactions).
flags
array
Safety flags identified
medication_review
string
Overall medication safety assessment
dosing_alerts
array
Dosing-specific alerts (renal/hepatic adjustment, weight-based dosing)
population_warnings
array
Population-specific warnings (pregnancy, pediatric, elderly, lactation)

Example

{
  "flags": [
    {
      "category": "drug-drug",
      "severity": "moderate",
      "description": "Aspirin may increase risk of hypoglycemia when combined with Metformin",
      "mechanism": "Aspirin enhances insulin secretion and glucose uptake",
      "recommendation": "Monitor blood glucose closely if initiating aspirin therapy",
      "drugs_involved": ["Aspirin", "Metformin"]
    },
    {
      "category": "drug-disease",
      "severity": "major",
      "description": "Beta-blockers may mask hypoglycemia symptoms in diabetic patients",
      "mechanism": "Beta-blockade suppresses tachycardia and tremor associated with hypoglycemia",
      "recommendation": "Educate patient on non-adrenergic hypoglycemia symptoms (sweating, confusion)",
      "drugs_involved": ["Metoprolol"]
    }
  ],
  "medication_review": "Current medications (Metformin, Lisinopril) are appropriate for HTN and DM2. Aspirin therapy recommended for ACS. Monitor for drug interactions with proposed treatment plan.",
  "dosing_alerts": [
    "Metformin: Check renal function before contrast imaging (risk of lactic acidosis)"
  ],
  "population_warnings": []
}

CriticOutput

Output from the Critic Agent (quality control, consensus building).
ehr_contradictions
array
Contradictions found between agent outputs and patient EHR data
evidence_gaps
array
Missing evidence or data needed for confident diagnosis
safety_misses
array
Safety concerns missed by other agents
overall_assessment
string
Critic’s overall assessment of the debate quality and consensus
consensus_reached
boolean
Whether agents reached consensus (true) or disagreement persists (false)
dissent_log
array
Record of dissenting opinions across agents

Example

{
  "ehr_contradictions": [],
  "evidence_gaps": [
    "ECG not yet available - critical for STEMI diagnosis",
    "Troponin pending - needed to confirm myocardial injury"
  ],
  "safety_misses": [
    "Clinical Agent did not initially consider aortic dissection - important given hypertension"
  ],
  "overall_assessment": "Strong consensus on ACS as primary diagnosis. Appropriate risk stratification with HEART Score. Safety agent correctly identified drug interactions. Recommend proceeding with SOAP synthesis while flagging need for ECG and troponin.",
  "consensus_reached": true,
  "dissent_log": [
    "Clinical Agent initially prioritized GERD in differential - overruled by evidence supporting cardiac etiology"
  ]
}

DebateState

Complete state of multi-agent debate across all rounds.
round_number
integer
Current debate round (max 2 rounds in production)
clinical_outputs
array
List of ClinicalAgentOutput objects (one per round)
literature_outputs
array
List of LiteratureAgentOutput objects (one per round)
safety_outputs
array
List of SafetyAgentOutput objects (one per round)
critic_outputs
array
List of CriticOutput objects (one per round)
final_consensus
boolean
Whether final consensus was reached
flagged_for_human
boolean
Whether case was flagged for human physician review (no consensus or critical uncertainty)

Example

{
  "round_number": 1,
  "clinical_outputs": [
    {
      "differentials": [...],
      "risk_scores": {...},
      "soap_draft": "...",
      "reasoning_trace": "...",
      "confidence": "high"
    }
  ],
  "literature_outputs": [
    {
      "evidence": [...],
      "summary": "...",
      "contradictions": [],
      "confidence": "high"
    }
  ],
  "safety_outputs": [
    {
      "flags": [...],
      "medication_review": "...",
      "dosing_alerts": [...],
      "population_warnings": []
    }
  ],
  "critic_outputs": [
    {
      "ehr_contradictions": [],
      "evidence_gaps": [...],
      "safety_misses": [...],
      "overall_assessment": "...",
      "consensus_reached": true,
      "dissent_log": [...]
    }
  ],
  "final_consensus": true,
  "flagged_for_human": false
}

MedErrorPanel

Output from the Medication Error Prevention Panel (runs in parallel with main pipeline).
drug_interactions
array
Drug-drug interactions identified
contraindications
array
Drug-disease contraindications
dosing_alerts
array
Dosing-specific alerts
population_flags
array
Population-specific warnings
summary
string
Overall medication safety summary

Example

{
  "drug_interactions": [
    {
      "drug_a": "Aspirin",
      "drug_b": "Lisinopril",
      "severity": "moderate",
      "description": "NSAIDs may reduce antihypertensive effect of ACE inhibitors",
      "mechanism": "Inhibition of prostaglandin synthesis",
      "recommendation": "Monitor blood pressure closely"
    }
  ],
  "contraindications": [],
  "dosing_alerts": [
    {
      "drug": "Metformin",
      "alert_type": "renal",
      "description": "Adjust dose for eGFR 30-45 mL/min, avoid if <30",
      "recommendation": "Check serum creatinine and eGFR before continuing"
    }
  ],
  "population_flags": [],
  "summary": "Moderate drug interaction between Aspirin and Lisinopril. Monitor BP. Metformin requires renal function check."
}
All agent outputs are stored in DebateState and used by the synthesizer to generate the final SOAP note. The Critic Agent ensures quality control and flags cases that need human review.

Build docs developers (and LLMs) love