> ## Documentation Index
> Fetch the complete documentation index at: https://docs.swarms.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Hospital Medical Team Swarm

> Learn how to create a hierarchical swarm that simulates a real medical team with a doctor leader coordinating nurses and assistants.

## What This Example Shows

* Creating a hierarchical swarm with leader and worker agents
* Coordinating multiple specialized medical professionals
* Implementing role-based agent responsibilities
* Managing complex multi-agent workflows

## Installation

```bash theme={null}
pip3 install -U swarms-client
```

## Get Your Swarms API Key

1. Visit [https://swarms.world/platform/api-keys](https://swarms.world/platform/api-keys)
2. Create an account or sign in
3. Generate a new API key
4. Store it securely in your environment variables

## Code

```python theme={null}
import json
import os
from swarms_client import SwarmsClient
from dotenv import load_dotenv

# Load environment variables
load_dotenv()

# Initialize the client
client = SwarmsClient(
    api_key=os.getenv("SWARMS_API_KEY"),
)

def create_medical_unit_swarm(client, patient_info):
    """
    Creates and runs a simulated medical unit swarm with a doctor (leader), 
    nurses, and a medical assistant.
    """
    return client.swarms.run(
        name="Hospital Medical Unit",
        description="A simulated hospital unit with a doctor (leader), nurses, and a medical assistant collaborating on patient care.",
        swarm_type="HierarchicalSwarm",
        task=patient_info,
        agents=[
            {
                "agent_name": "Dr. Smith - Attending Physician",
                "description": "The lead doctor responsible for diagnosis, treatment planning, and team coordination.",
                "system_prompt": (
                    "You are Dr. Smith, the attending physician and leader of the medical unit. "
                    "You review all information, make final decisions, and coordinate the team. "
                    "Provide a diagnosis, recommend next steps, and delegate tasks to the nurses and assistant."
                ),
                "model_name": "gpt-4.1",
                "role": "leader",
                "max_loops": 1,
                "max_tokens": 8192,
                "temperature": 0.5,
            },
            {
                "agent_name": "Nurse Alice",
                "description": "A registered nurse responsible for patient assessment, vital signs, and reporting findings to the doctor.",
                "system_prompt": (
                    "You are Nurse Alice, a registered nurse. "
                    "Assess the patient's symptoms, record vital signs, and report your findings to Dr. Smith. "
                    "Suggest any immediate nursing interventions if needed."
                ),
                "model_name": "gpt-4.1",
                "role": "worker",
                "max_loops": 1,
                "max_tokens": 4096,
                "temperature": 0.5,
            },
            {
                "agent_name": "Nurse Bob",
                "description": "A registered nurse assisting with patient care, medication administration, and monitoring.",
                "system_prompt": (
                    "You are Nurse Bob, a registered nurse. "
                    "Assist with patient care, administer medications as ordered, and monitor the patient's response. "
                    "Communicate any changes to Dr. Smith."
                ),
                "model_name": "gpt-4.1",
                "role": "worker",
                "max_loops": 1,
                "max_tokens": 4096,
                "temperature": 0.5,
            },
            {
                "agent_name": "Medical Assistant Jane",
                "description": "A medical assistant supporting the team with administrative tasks and basic patient care.",
                "system_prompt": (
                    "You are Medical Assistant Jane. "
                    "Support the team by preparing the patient, collecting samples, and handling administrative tasks. "
                    "Report any relevant observations to the nurses or Dr. Smith."
                ),
                "model_name": "claude-sonnet-4-20250514",
                "role": "worker",
                "max_loops": 1,
                "max_tokens": 2048,
                "temperature": 0.5,
            },
        ],
    )

# Example patient case
patient_symptoms = """
Patient: 45-year-old female
Chief Complaint: Chest pain and shortness of breath for 2 days

Symptoms:
- Sharp chest pain that worsens with deep breathing
- Shortness of breath, especially when lying down
- Mild fever (100.2°F)
- Dry cough
- Fatigue
"""

# Run the medical team swarm
out = create_medical_unit_swarm(client, patient_symptoms)
print(json.dumps(out, indent=4))
```

## Swarm Architecture Explained

### Agent Roles

* **Dr. Smith**: Written as the senior-physician persona among the agents you list
* **Nurses & Assistant**: The other agents you list, each scoped to one lane of care

### Swarm Type: HierarchicalSwarm

<Warning>
  `HierarchicalSwarm` always builds its own director from `director_model_name` (default `gpt-5.4`) that decomposes the task and dispatches it to every agent in `agents` — Dr. Smith runs as one of the director's workers here, not as a privileged coordinator, and `role: "leader"` on her agent config is just a descriptive string with no special effect on execution. With the default `max_loops: 1` and parallel worker execution, no agent (Dr. Smith included) sees another agent's output before writing its own, so nothing here guarantees results flow back to Dr. Smith for a final synthesis. For a real synthesis pass, either set `"max_loops": 2` on the swarm (the framework's director is handed every first-round output on its second pass and can route the synthesis to Dr. Smith by name/description), or collect the other agents' outputs client-side and issue one more `client.agents.run(...)` (or `/v1/agent/completions`) call using Dr. Smith's system prompt.
</Warning>

This swarm type works like this:

1. The framework's own director agent reads the task and decides which of your listed agents should handle which piece of it
2. The agents you configured each process their assigned piece independently, in parallel
3. The response contains the director's task breakdown plus every agent's independent output — there is no automatic final-synthesis step unless you add one (see the warning above)

## Expected Output

The swarm will provide a coordinated medical assessment including:

* **Nurse Alice's Assessment**: Vital signs, immediate observations
* **Nurse Bob's Care Plan**: Medication and monitoring recommendations
* **Medical Assistant's Support**: Administrative and preparation tasks
* **Dr. Smith's Final Diagnosis**: Comprehensive treatment plan and coordination

## Use Cases

This pattern is ideal for:

* **Medical Teams**: Coordinated patient care and diagnosis
* **Legal Teams**: Multi-expert document review and analysis
* **Research Teams**: Collaborative data analysis and interpretation
* **Support Teams**: Coordinated customer issue resolution
* **Development Teams**: Code review and quality assurance

## Environment Setup

Create a `.env` file in your project directory:

```bash theme={null}
SWARMS_API_KEY=your_api_key_here
```

## Customization Ideas

Adapt this pattern for:

* **Emergency Response**: Fire, police, and medical coordination
* **Project Management**: Team leads coordinating specialists
* **Quality Control**: Inspectors coordinating with technicians
* **Customer Service**: Supervisors managing support agents

## Next Steps

After mastering hierarchical swarms, explore:

* Sequential workflows for step-by-step processes
* Concurrent workflows for parallel execution
* Majority voting for consensus-based decisions
* Agent routing for dynamic task distribution