How to add custom lifespan events

When deploying agents to LangSmith, you often need to initialize resources like database connections when your server starts up, and ensure they’re properly closed when it shuts down. Lifespan events let you hook into your server’s startup and shutdown sequence to handle these critical setup and teardown tasks.

This works the same way as adding custom routes. You just need to provide your own Starlette app (including FastAPI, FastHTML and other compatible apps).

Below is an example using FastAPI.

“Python only” We currently only support custom lifespan events in Python deployments with langgraph-api>=0.0.26.

Create app

Starting from an existing LangSmith application, add the following lifespan code to your webapp.py file. If you are starting from scratch, you can create a new app from a template using the CLI.

langgraph new --template=new-langgraph-project-python my_new_project

Once you have a LangGraph project, add the following app code:

# ./src/agent/webapp.py
from contextlib import asynccontextmanager
from fastapi import FastAPI
from sqlalchemy.ext.asyncio import create_async_engine, AsyncSession
from sqlalchemy.orm import sessionmaker

@asynccontextmanager
async def lifespan(app: FastAPI):
    # for example...
    engine = create_async_engine("postgresql+asyncpg://user:pass@localhost/db")
    # Create reusable session factory
    async_session = sessionmaker(engine, class_=AsyncSession)
    # Store in app state
    app.state.db_session = async_session
    yield
    # Clean up connections
    await engine.dispose()

app = FastAPI(lifespan=lifespan)

# ... can add custom routes if needed.

Configure langgraph.json

Add the following to your langgraph.json configuration file. Make sure the path points to the webapp.py file you created above.

{
  "dependencies": ["."],
  "graphs": {
    "agent": "./src/agent/graph.py:graph"
  },
  "env": ".env",
  "http": {
    "app": "./src/agent/webapp.py:app"
  }
  // Other configuration options like auth, store, etc.
}

Start server

Test the server out locally:

langgraph dev --no-browser

You should see your startup message printed when the server starts, and your cleanup message when you stop it with Ctrl+C.

Deploying

You can deploy your app as-is to cloud or to your self-hosted platform.

Next steps

Now that you’ve added lifespan events to your deployment, you can use similar techniques to add custom routes or custom middleware to further customize your server’s behavior.

---

Connect these docs to Claude, VSCode, and more via MCP for real-time answers.

Edit this page on GitHub or file an issue.