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

# AgentOS serve: reload is unsupported

> Why AgentOS.serve(reload=True) cannot hot-reload and how to get reload instead

A programmatically built `AgentOS` cannot hot-reload — `serve(reload=True)` warns and serves without reload.

```mermaid theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
graph LR
    subgraph "AgentOS serve(reload=True)"
        Build["🤖 AgentOS(agents=[...])"] --> Serve["⚙️ serve(reload=True)"]
        Serve --> Warn["⚠️ UserWarning"]
        Warn --> Run["✅ Serves without reload"]
    end

    classDef agent fill:#8B0000,stroke:#7C90A0,color:#fff
    classDef process fill:#189AB4,stroke:#7C90A0,color:#fff
    classDef warn fill:#F59E0B,stroke:#7C90A0,color:#fff
    classDef result fill:#10B981,stroke:#7C90A0,color:#fff

    class Build agent
    class Serve process
    class Warn warn
    class Run result
```

## Quick Start

**1. What happens today**

`serve(reload=True)` on a programmatic `AgentOS` emits a `UserWarning` and runs without reload:

```python theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
from praisonai import AgentOS
from praisonaiagents import Agent

assistant = Agent(name="assistant", instructions="Be helpful.")

AgentOS(agents=[assistant]).serve(reload=True)
# UserWarning: reload is unsupported for a programmatically built AgentOS;
# serving without reload.
```

The CLI `praisonai app --reload` prints the same guidance in yellow.

**2. Get reload with a module factory**

Expose your `AgentOS` as a module-level factory and run uvicorn against the import string:

```python theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
# mymodule.py
from praisonai import AgentOS
from praisonaiagents import Agent

def create_app():
    return AgentOS(agents=[Agent(name="assistant", instructions="Be helpful.")]).get_app()
```

```bash theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
uvicorn "mymodule:create_app" --factory --reload
```

***

## Why reload is unsupported

Uvicorn's reload worker runs in a **separate process** and re-imports the target module.

```mermaid theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
sequenceDiagram
    participant Dev as You
    participant Main as Main process
    participant Worker as Reload worker

    Dev->>Main: AgentOS(agents=[...]).serve(reload=True)
    Main->>Main: Build Agent/Team/Flow in memory
    Main->>Worker: Spawn reload worker (fresh process)
    Worker->>Worker: Re-import target module
    Note over Worker: No module-level app — starts empty
    Main-->>Dev: UserWarning + serve without reload
```

A programmatically built `AgentOS(agents=[...])` has **no importable module-level app**. The reload worker would start empty and fail, so `serve(reload=True)` warns and serves without reload rather than crash.

| Path | Reload behaviour |
| - | - |
| `AgentOS.serve(reload=True)` | `UserWarning`, serves without reload |
| `praisonai app --reload` | Yellow guidance line, serves without reload |
| `uvicorn "mymodule:create_app" --factory --reload` | Reload works — uvicorn owns the import |

> [!NOTE]
>
> Non-reload serving is unchanged. `AgentOS(agents=[...]).serve()` works exactly as before.

***

## Common Patterns

### Development with reload

Point uvicorn at your factory so edits to `mymodule.py` reload automatically:

```bash theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
uvicorn "mymodule:create_app" --factory --reload --port 8000
```

### Production without reload

For production, call `serve()` directly — reload is a development-only convenience:

```python theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
from praisonai import AgentOS
from praisonaiagents import Agent

AgentOS(agents=[Agent(name="assistant", instructions="Be helpful.")]).serve(port=8000)
```

***

## Best Practices

> **Use a module factory for live reload**
>
> Expose `create_app()` returning `AgentOS(...).get_app()` and run `uvicorn "mymodule:create_app" --factory --reload`. Uvicorn controls the import, so each edit re-imports cleanly.

> **Don't rely on reload in production**
>
> Reload re-imports on every change and adds overhead. Serve with `AgentOS(...).serve()` (no reload) in production.

> **Prefer CLI serve commands for reloadable files**
>
> `praisonai serve agents --reload`, `praisonai serve unified --reload`, and `praisonai serve recipe --reload` all hot-reload because they load from a file via an app factory. See [Serve](/docs/cli/serve.md).

***

## Related

> **[Serve](/docs/cli/serve.md)**
>
> `--reload` support across CLI serve commands

> **[Recipe Serve Advanced](/docs/features/recipe-serve-advanced.md)**
>
> App-factory pattern for workers and reload


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.