Custom Lifespan

Customize the lifespan of your AgentOS app to handle startup and shutdown logic.

You will often want to run code before your AgentOS app starts or before it shuts down.

This can be done by providing a custom lifespan function via the lifespan parameter.

A lifespan function looks like this:

@asynccontextmanager
async def lifespan(app):
    # This will run before your app starts
    log_info("Starting My FastAPI App")

    yield

    # This will run before your app shuts down
    log_info("Stopping My FastAPI App")

FastAPI Lifespan

The custom lifespan function you provide will be used as the lifespan context manager for the FastAPI app used by your AgentOS. Remember to decorate it with @asynccontextmanager as shown in the examples.

See the FastAPI documentation for more information about the lifespan context manager.

If you are using a custom FastAPI app, you don't need to worry about overwriting its lifespan.

The lifespan you provide will wrap the existing lifespan of the app, letting you combine both.

Common Use Cases

Lifespan control is useful to handle typical startup and shutdown tasks, such as:

  • Resource Initialization: databases, third-party services, caches... or anything else needed by your app.
  • Cleanup: Close connections, store data or release resources before shutdown.
  • Health Checks: Verify dependencies are available before serving requests
  • Background Tasks: Start/stop background processes

Example

Code

custom_lifespan.py
from contextlib import asynccontextmanager

from agno.agent import Agent
from agno.db.postgres import PostgresDb
from agno.models.anthropic import Claude
from agno.os import AgentOS
from agno.utils.log import log_info

# Setup the database
db = PostgresDb(db_url="postgresql+psycopg://ai:ai@localhost:5532/ai")

# Setup basic agents, teams and workflows
agno_support_agent = Agent(
    id="example-agent",
    name="Example Agent",
    model=Claude(id="claude-sonnet-4-5"),
    db=db,
    markdown=True,
)


@asynccontextmanager
async def lifespan(app):
    log_info("Starting My FastAPI App")
    yield
    log_info("Stopping My FastAPI App")


agent_os = AgentOS(
    description="Example app with custom lifespan",
    agents=[agno_support_agent],
    lifespan=lifespan,
)


app = agent_os.get_app()

if __name__ == "__main__":
    """Run your AgentOS.

    You can test your AgentOS at:
    http://localhost:7777/docs

    """
    # Don't use reload=True here. It can cause issues with the lifespan
    agent_os.serve(app="custom_lifespan:app")

Set up your virtual environment

uv venv --python 3.12
source .venv/bin/activate

Set Environment Variables

export ANTHROPIC_API_KEY=your_anthropic_api_key

Install dependencies

uv pip install -U agno anthropic "fastapi[standard]" uvicorn sqlalchemy psycopg

Setup PostgreSQL Database

# Using Docker
docker run -d \
  --name agno-postgres \
  -e POSTGRES_DB=ai \
  -e POSTGRES_USER=ai \
  -e POSTGRES_PASSWORD=ai \
  -p 5532:5432 \
  pgvector/pgvector:pg17

Run Example with Python

fastapi run custom_lifespan.py --port 7777