Agent Orchestration Rules — MedAssist AI
MedAssist AI runs 7 specialized AI agents coordinated by an Agent Orchestrator. Every agent extends BaseAgent, uses OpenAI function calling, and accesses data exclusively through a tool layer — never via direct database queries.
Architecture
User Request
│
▼
Agent Orchestrator
│
├─→ Symptom Analyst Agent
├─→ Report Reader Agent
├─→ Triage Agent
├─→ Voice Agent
├─→ Drug Interaction Agent
├─→ Monitoring Agent
└─→ Follow-Up Agent
The Orchestrator inspects the user intent, selects one or more specialist agents, fans out work, and assembles the final response.
Agent Specifications
1. Symptom Analyst Agent
| Property | Value |
|---|
| Model | GPT-4o |
| Purpose | Analyze patient symptoms, generate differential diagnoses, recommend specialists |
Tools:
| Tool | Description |
|---|
search_medical_kb | Query RAG pipeline (Pinecone + Elasticsearch) for medical knowledge |
query_patient_history | Retrieve patient medical history from PostgreSQL via service layer |
calculate_urgency_score | Compute urgency score (1-10) based on symptom severity |
generate_differential_diagnosis | Produce ranked list of possible diagnoses with confidence scores |
recommend_specialist | Suggest specialist type based on differential diagnosis |
2. Report Reader Agent
| Property | Value |
|---|
| Model | GPT-4o (Vision) |
| Purpose | Parse medical reports/images, extract lab values, identify abnormalities |
Tools:
| Tool | Description |
|---|
extract_text_from_image | OCR extraction from uploaded report images (S3/MinIO) |
parse_lab_values | Extract structured lab values with units and reference ranges |
identify_abnormalities | Flag out-of-range values and clinically significant findings |
explain_report | Generate patient-friendly explanation of report findings |
correlate_with_history | Compare current results against patient's historical data |
3. Triage Agent
| Property | Value |
|---|
| Model | GPT-4o-mini |
| Purpose | Emergency triage, priority assignment, wait-time estimation |
Tools:
| Tool | Description |
|---|
calculate_esi_score | Compute Emergency Severity Index (ESI) level 1-5 |
check_emergency_symptoms | Match against emergency symptom red-flag checklist |
get_wait_times | Retrieve current facility wait times |
assign_priority | Assign and persist triage priority to the encounter |
4. Voice Agent
| Property | Value |
|---|
| Model | Whisper (STT) + TTS |
| Purpose | Voice-based interaction, clinical note generation |
Tools:
| Tool | Description |
|---|
transcribe_audio | Convert audio input to text via Whisper API |
synthesize_speech | Convert text response to audio via TTS API |
generate_clinical_notes | Produce SOAP-format clinical notes from conversation |
5. Drug Interaction Agent
| Property | Value |
|---|
| Model | GPT-4o-mini |
| Purpose | Check drug interactions, verify dosages, suggest alternatives |
Tools:
| Tool | Description |
|---|
check_interactions | Query drug interaction database for conflicts |
verify_dosage | Validate prescribed dosage against guidelines (weight, age, renal function) |
suggest_alternatives | Recommend alternative medications when interactions are found |
check_allergies | Cross-reference medication against patient allergy records |
6. Monitoring Agent
| Property | Value |
|---|
| Model | GPT-4o-mini |
| Purpose | Real-time vitals monitoring, anomaly detection, alerting |
Tools:
| Tool | Description |
|---|
read_vitals | Query InfluxDB for patient vitals (HR, BP, SpO2, temp, RR) |
calculate_news2_score | Compute National Early Warning Score 2 from current vitals |
detect_anomalies | Run anomaly detection on vitals time series |
trigger_alert | Send alert via Redis Pub/Sub + persist to PostgreSQL |
7. Follow-Up Agent
| Property | Value |
|---|
| Model | GPT-4o |
| Purpose | Care plan generation, adherence tracking, follow-up scheduling |
Tools:
| Tool | Description |
|---|
generate_care_plan | Create personalized post-visit care plan |
track_adherence | Monitor patient compliance with care plan |
adjust_care_plan | Modify care plan based on progress and feedback |
schedule_followup | Schedule follow-up appointments and reminders |
BaseAgent Contract
Every agent must extend BaseAgent and implement:
class BaseAgent(ABC):
agent_name: str
model: str
tools: list[dict] # OpenAI function-calling tool definitions
system_prompt: str # Loaded from prompts/ directory
max_tokens: int
timeout: int = 300 # 5 minutes
@abstractmethod
async def run(self, input: AgentInput) -> AgentOutput: ...
def _build_messages(self, input: AgentInput) -> list[dict]: ...
def _execute_tool(self, tool_call: ToolCall) -> ToolResult: ...
def _log_usage(self, tokens_used: TokenUsage) -> None: ...
Tool Layer
Agents never access the database directly. All data access goes through the tool layer:
Agent → Tool Function → Service Layer → Repository → Database
- Each tool function validates its inputs, calls the appropriate service, and returns a structured result.
- Tool functions are defined in
app/agents/tools/ with one module per agent.
- Tool input and output schemas are defined as Pydantic models.
Prompt Management
- All system prompts live in
prompts/ directory as .txt or .jinja2 files.
- Prompts are version-controlled — changes to prompts are reviewed in PRs like code.
- Use Jinja2 templating for dynamic context injection (patient name, vitals, etc.).
- Never hardcode prompts inside agent classes.
Structured Output
All agents return structured output conforming to Pydantic schemas:
SymptomAnalysisResult, ReportAnalysisResult, TriageResult, etc.- Use OpenAI's
response_format (JSON mode) or parse function-call outputs into these schemas.
- Validate output before returning to the user.
Execution Model
- All agent runs execute as Celery tasks (async, non-blocking).
- Timeout: 5 minutes per agent run. If an agent exceeds this, the task is terminated and the user receives a timeout error.
- The Orchestrator may run multiple agents in parallel (e.g., Symptom Analyst + Drug Interaction) using Celery group/chord.
- Track token usage per agent run in PostgreSQL (
agent_usage_logs table): agent_name, model, prompt_tokens, completion_tokens, total_tokens, cost_usd, duration_ms.
Shared Memory
| Layer | Store | TTL | Purpose |
|---|
| Short-term | Redis (agent_ctx:{session_id}) | 30 min | Current conversation context, intermediate results |
| Long-term | Pinecone | Persistent | Patient context embeddings (de-identified) for continuity across sessions |
- When a session starts, load relevant long-term context from Pinecone into the agent's system prompt.
- On session end, summarize and embed key findings back to Pinecone.
- Short-term context is evicted automatically by Redis TTL.
HIPAA & Safety
- De-identify all patient data before sending to OpenAI APIs. Use the PII redaction layer (see
08-security.md).
- Agents must not store PHI in logs, error messages, or Celery task results.
- All agent interactions are logged to
audit_logs for HIPAA compliance.
- The Orchestrator validates that the requesting user has the required role to invoke the agent (e.g., patients cannot invoke the Monitoring Agent directly — only via their own dashboard).