diff --git a/docs/docs/cloud/reference/cli.md b/docs/docs/cloud/reference/cli.md index 01286a5e3..958fa2557 100644 --- a/docs/docs/cloud/reference/cli.md +++ b/docs/docs/cloud/reference/cli.md @@ -51,6 +51,7 @@ The LangGraph CLI requires a JSON configuration file with the following keys: | `node_version` | Specify `node_version: 20` to use LangGraph.js. | | `pip_config_file` | Path to `pip` config file. | | `dockerfile_lines` | Array of additional lines to add to Dockerfile following the import from parent image. | + | `http` | HTTP server configuration with the following fields: | === "JS" diff --git a/docs/docs/how-tos/http/custom_lifespan.md b/docs/docs/how-tos/http/custom_lifespan.md new file mode 100644 index 000000000..a7b2d7d48 --- /dev/null +++ b/docs/docs/how-tos/http/custom_lifespan.md @@ -0,0 +1,82 @@ +# How to add custom lifespan events + +When deploying agents on the LangGraph platform, 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](./custom_routes.md) - you just need to provide your own [`Starlette`](https://www.starlette.io/applications/) app (including [`FastAPI`](https://fastapi.tiangolo.com/), [`FastHTML`](https://fastht.ml/) and other compatible apps). + +Below is an example using FastAPI. + +???+ note "Python only" + + We currently only support custom lifespan events in Python deployments with `langgraph-api>=0.0.26`. + +## Create app + +Starting from an **existing** LangGraph Platform 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. + +```bash +langgraph new --template=new-langgraph-project-python my_new_project +``` + +Once you have a LangGraph project, add the following app code: + +```python +# ./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() + +# highlight-next-line +app = FastAPI(lifespan=lifespan) + +# ... can add custom routes if needed. +``` + +## Configure `langgraph.json` + +Add the following to your `langgraph.json` file. Make sure the path points to the `webapp.py` file you created above. + +```json +{ + "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: + +```bash +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 the managed langgraph 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](./custom_routes.md) or [custom middleware](./custom_middleware.md) to further customize your server's behavior. diff --git a/docs/docs/how-tos/http/custom_lifespan_events.py b/docs/docs/how-tos/http/custom_lifespan_events.py new file mode 100644 index 000000000..e69de29bb diff --git a/docs/docs/how-tos/http/custom_middleware.md b/docs/docs/how-tos/http/custom_middleware.md new file mode 100644 index 000000000..2626e289a --- /dev/null +++ b/docs/docs/how-tos/http/custom_middleware.md @@ -0,0 +1,75 @@ +# How to add custom middleware + +When deploying agents on the LangGraph platform, you can add custom middleware to your server to handle cross-cutting concerns like logging request metrics, injecting or checking headers, and enforcing security policies without modifying core server logic. This works the same way as [adding custom routes](./custom_routes.md) - you just need to provide your own [`Starlette`](https://www.starlette.io/applications/) app (including [`FastAPI`](https://fastapi.tiangolo.com/), [`FastHTML`](https://fastht.ml/) and other compatible apps). + +Adding middleware lets you intercept and modify requests and responses globally across your deployment, whether they're hitting your custom endpoints or the built-in LangGraph Platform APIs. + +Below is an example using FastAPI. + +???+ note "Python only" + + We currently only support custom middleware in Python deployments with `langgraph-api>=0.0.26`. + +## Create app + +Starting from an **existing** LangGraph Platform application, add the following middleware code to your `webapp.py` file. If you are starting from scratch, you can create a new app from a template using the CLI. + +```bash +langgraph new --template=new-langgraph-project-python my_new_project +``` + +Once you have a LangGraph project, add the following app code: + +```python +# ./src/agent/webapp.py +from fastapi import FastAPI, Request +from starlette.middleware.base import BaseHTTPMiddleware + +# highlight-next-line +app = FastAPI() + +class CustomHeaderMiddleware(BaseHTTPMiddleware): + async def dispatch(self, request: Request, call_next): + response = await call_next(request) + response.headers['X-Custom-Header'] = 'Hello from middleware!' + return response + +# Add the middleware to the app +app.add_middleware(CustomHeaderMiddleware) +``` + +## Configure `langgraph.json` + +Add the following to your `langgraph.json` file. Make sure the path points to the `webapp.py` file you created above. + +```json +{ + "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: + +```bash +langgraph dev --no-browser +``` + +Now any request to your server will include the custom header `X-Custom-Header` in its response. + +## Deploying + +You can deploy this app as-is to the managed langgraph cloud or to your self-hosted platform. + +## Next steps + +Now that you've added custom middleware to your deployment, you can use similar techniques to add [custom routes](./custom_routes.md) or define [custom lifespan events](./custom_lifespan.md) to further customize your server's behavior. \ No newline at end of file diff --git a/docs/docs/how-tos/http/custom_routes.md b/docs/docs/how-tos/http/custom_routes.md new file mode 100644 index 000000000..39a1f924f --- /dev/null +++ b/docs/docs/how-tos/http/custom_routes.md @@ -0,0 +1,78 @@ +# How to add custom routes + +When deploying agents on the LangGraph platform, your server automatically exposes routes for creating runs and threads, interacting with the long-term memory store, managing configurable assistants, and other core functionality ([see all default API endpoints](../../cloud/reference/api/api_ref.md)). + +You can add custom routes by providing your own [`Starlette`](https://www.starlette.io/applications/) app (including [`FastAPI`](https://fastapi.tiangolo.com/), [`FastHTML`](https://fastht.ml/) and other compatible apps). You make LangGraph Platform aware of this by providing a path to the app in your `langgraph.json` configuration file. (`"http": {"app": "path/to/app.py:app"}`). + +Defining a custom app object lets you add any routes you'd like, so you can do anything from adding a `/login` endpoint to writing an entire full-stack web-app, all deployed in a single LangGraph deployment. + +Below is an example using FastAPI. + +???+ note "Python only" + + We currently only support custom authentication and authorization in Python deployments with `langgraph-api>=0.0.26`. + +## Create app + +Starting from an **existing** LangGraph Platform application, add the following custom route code to your `webapp.py` file. If you are starting from scratch, you can create a new app from a template using the CLI. + +```bash +langgraph new --template=new-langgraph-project-python my_new_project +``` + +Once you have a LangGraph project, add the following app code: + +```python +# ./src/agent/webapp.py +from fastapi import FastAPI + +# highlight-next-line +app = FastAPI() + + +@app.get("/hello") +def read_root(): + return {"Hello": "World"} + +``` + +## Configure `langgraph.json` + +Add the following to your `langgraph.json` file. Make sure the path points to the `app.py` file you created above. + +```json +{ + "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: + +```bash +langgraph dev --no-browser +``` + +If you navigate to `localhost:2024/hello` in your browser (2024 is the default development port), you should see the `hello` endpoint returning `{"Hello": "World"}`. + + +!!! note "Shadowing default endpoints" + + The routes you create in the app are given priority over the system defaults, meaning you can shadow and redefine the behavior of any default endpoint. + +## Deploying + +You can deploy this app as-is to the managed langgraph cloud or to your self-hsoted platform. + +## Next steps + +Now that you've added a custom route to your deployment, you can use this same technique to further customize how your server behaves, such as defining custom [custom middleware](./custom_middleware.md) and [custom lifespan events](./custom_lifespan.md). \ No newline at end of file diff --git a/docs/docs/how-tos/index.md b/docs/docs/how-tos/index.md index d27eb5ae8..31b9755e4 100644 --- a/docs/docs/how-tos/index.md +++ b/docs/docs/how-tos/index.md @@ -215,6 +215,12 @@ LangGraph applications can be deployed using LangGraph Cloud, which provides a r - [How to add custom authentication](./auth/custom_auth.md) - [How to update the security schema of your OpenAPI spec](./auth/openapi_security.md) +### Modifying the API + +- [How to add custom routes](./http/custom_routes.md) +- [How to add custom middleware](./http/custom_middleware.md) +- [How to add custom lifespan events](./http/custom_lifespan.md) + ### Assistants [Assistants](../concepts/assistants.md) is a configured instance of a template.