From daf20b610bae1eea82a6e73085688e8c0f331bd6 Mon Sep 17 00:00:00 2001 From: Lauren Hirata Singh Date: Mon, 12 May 2025 02:11:08 -0400 Subject: [PATCH] docs: General language cleanup (#4649) - README updates based on feedback - Auth tutorial cleanup --- README.md | 52 +++++---- docs/docs/agents/prebuilt.md | 6 +- .../langgraph_standalone_container.md | 6 +- docs/docs/concepts/pregel.md | 2 +- docs/docs/llms-txt-overview.md | 4 +- docs/docs/tutorials/auth/add_auth_server.md | 102 ++++++++---------- docs/docs/tutorials/auth/getting_started.md | 100 +++++++++-------- docs/docs/tutorials/auth/resource_auth.md | 63 ++++------- docs/docs/tutorials/deployment.md | 4 +- docs/mkdocs.yml | 31 +++--- libs/langgraph/README.md | 52 +++++---- 11 files changed, 199 insertions(+), 223 deletions(-) diff --git a/README.md b/README.md index ae8f0084f..4425ca270 100644 --- a/README.md +++ b/README.md @@ -13,44 +13,50 @@ [![Open Issues](https://img.shields.io/github/issues-raw/langchain-ai/langgraph)](https://github.com/langchain-ai/langgraph/issues) [![Docs](https://img.shields.io/badge/docs-latest-blue)](https://langchain-ai.github.io/langgraph/) -> [!NOTE] -> Looking for the JS version? See the [JS repo](https://github.com/langchain-ai/langgraphjs) and the [JS docs](https://langchain-ai.github.io/langgraphjs/). - -LangGraph is a low-level orchestration framework for building controllable agents. While [LangChain](https://python.langchain.com/docs/introduction/) provides integrations and composable components to streamline LLM application development, the LangGraph library enables agent orchestration — offering customizable architectures, long-term memory, and human-in-the-loop to reliably handle complex tasks. +Trusted by companies shaping the future of agents – including Klarna, Replit, Elastic, and more – LangGraph is a powerful low-level orchestration framework for building, managing, and deploying long-running, stateful agents. ## Get started -First, install LangGraph: +Install LangGraph: ``` pip install -U langgraph ``` -There are two ways to get started with LangGraph: +Then, create an agent [using prebuilt components](https://langchain-ai.github.io/langgraph/agents/agents/): -- [Use prebuilt components](https://langchain-ai.github.io/langgraph/agents/agents/): Construct agentic systems quickly and reliably without the need to implement orchestration, memory, or human feedback handling from scratch. -- [Use LangGraph](https://langchain-ai.github.io/langgraph/tutorials/introduction/): Customize your architectures, use long-term memory, and implement human-in-the-loop to reliably handle complex tasks. +```python +# pip install -qU "langchain[anthropic]" to call the model -Once you have a LangGraph application and are ready to move into production, use [LangGraph Platform](https://langchain-ai.github.io/langgraph/cloud/quick_start/) to test, debug, and deploy your application. +from langgraph.prebuilt import create_react_agent -## What LangGraph provides +def get_weather(city: str) -> str: # (1)! + """Get weather for a given city.""" + return f"It's always sunny in {city}!" -LangGraph provides low-level supporting infrastructure that sits underneath *any* workflow or agent. It does not abstract prompts or architecture, and provides three central benefits: +agent = create_react_agent( + model="anthropic:claude-3-7-sonnet-latest", # (2)! + tools=[get_weather], # (3)! + prompt="You are a helpful assistant" # (4)! +) -### Persistence +# Run the agent +agent.invoke( + {"messages": [{"role": "user", "content": "what is the weather in sf"}]} +) +``` -LangGraph has a [persistence layer](https://langchain-ai.github.io/langgraph/concepts/persistence/), which offers a number of benefits: +For more information, see the [Quickstart](https://langchain-ai.github.io/langgraph/agents/agents/). Or, to learn how to build an [agent workflow](https://langchain-ai.github.io/langgraph/concepts/low_level/) with a customizable architecture, long-term memory, and other complex task handling, see the [LangGraph basics tutorials](https://langchain-ai.github.io/langgraph/tutorials/get-started/1-build-basic-chatbot/). -- [Memory](https://langchain-ai.github.io/langgraph/concepts/memory/): LangGraph persists arbitrary aspects of your application's state, supporting memory of conversations and other updates within and across user interactions; -- [Human-in-the-loop](https://langchain-ai.github.io/langgraph/concepts/human_in_the_loop/): Because state is checkpointed, execution can be interrupted and resumed, allowing for decisions, validation, and corrections via human input. +## Core benefits -### Streaming +LangGraph provides low-level supporting infrastructure for *any* long-running, stateful workflow or agent. LangGraph does not abstract prompts or architecture, and provides the following central benefits: -LangGraph provides support for [streaming](https://langchain-ai.github.io/langgraph/concepts/streaming/) workflow / agent state to the user (or developer) over the course of execution. LangGraph supports streaming of both events ([such as feedback from a tool call](https://langchain-ai.github.io/langgraph/how-tos/streaming.ipynb#updates)) and [tokens from LLM calls](https://langchain-ai.github.io/langgraph/how-tos/streaming-tokens.ipynb) embedded in an application. - -### Debugging and deployment - -LangGraph provides an easy onramp for testing, debugging, and deploying applications via [LangGraph Platform](https://langchain-ai.github.io/langgraph/concepts/langgraph_platform/). This includes [Studio](https://langchain-ai.github.io/langgraph/concepts/langgraph_studio/), an IDE that enables visualization, interaction, and debugging of workflows or agents. This also includes numerous [options](https://langchain-ai.github.io/langgraph/tutorials/deployment/) for deployment. +- [Durable execution](https://langchain-ai.github.io/langgraph/concepts/durable_execution/): Build agents that persist through failures and can run for extended periods, automatically resuming from exactly where they left off. +- [Human-in-the-loop](https://langchain-ai.github.io/langgraph/concepts/human_in_the_loop/): Seamlessly incorporate human oversight by inspecting and modifying agent state at any point during execution. +- [Comprehensive memory](https://langchain-ai.github.io/langgraph/concepts/memory/): Create truly stateful agents with both short-term working memory for ongoing reasoning and long-term persistent memory across sessions. +- [Debugging with LangSmith](http://www.langchain.com/langsmith): Gain deep visibility into complex agent behavior with visualization tools that trace execution paths, capture state transitions, and provide detailed runtime metrics. +- [Production-ready deployment](https://langchain-ai.github.io/langgraph/concepts/deployment_options/): Deploy sophisticated agent systems confidently with scalable infrastructure designed to handle the unique challenges of stateful, long-running workflows. ## LangGraph’s ecosystem @@ -58,6 +64,10 @@ While LangGraph can be used standalone, it also integrates seamlessly with any L - [LangSmith](http://www.langchain.com/langsmith) — Helpful for agent evals and observability. Debug poor-performing LLM app runs, evaluate agent trajectories, gain visibility in production, and improve performance over time. - [LangGraph Platform](https://langchain-ai.github.io/langgraph/concepts/#langgraph-platform) — Deploy and scale agents effortlessly with a purpose-built deployment platform for long running, stateful workflows. Discover, reuse, configure, and share agents across teams — and iterate quickly with visual prototyping in [LangGraph Studio](https://langchain-ai.github.io/langgraph/concepts/langgraph_studio/). +- [LangChain](https://python.langchain.com/docs/introduction/) – Provides integrations and composable components to streamline LLM application development. + +> [!NOTE] +> Looking for the JS version of LangGraph? See the [JS repo](https://github.com/langchain-ai/langgraphjs) and the [JS docs](https://langchain-ai.github.io/langgraphjs/). ## Additional resources diff --git a/docs/docs/agents/prebuilt.md b/docs/docs/agents/prebuilt.md index 8ebd5c17b..6f15cb45e 100644 --- a/docs/docs/agents/prebuilt.md +++ b/docs/docs/agents/prebuilt.md @@ -1,10 +1,10 @@ [//]: # (This file is automatically generated using a script in docs/_scripts. Do not edit this file directly!) -# Community Agents +# Community agents If you’re looking for other prebuilt libraries, explore the community-built options below. These libraries can extend LangGraph's functionality in various ways. -## 📚 Available Libraries +## 📚 Available libraries [//]: # (This file is automatically generated using a script in docs/_scripts. Do not edit this file directly!) | Name | GitHub URL | Description | Weekly Downloads | Stars | @@ -23,7 +23,7 @@ below. These libraries can extend LangGraph's functionality in various ways. | **langgraph-reflection** | [langchain-ai/langgraph-reflection](https://github.com/langchain-ai/langgraph-reflection) | LangGraph agent that runs a reflection step. | -12345 | ![GitHub stars](https://img.shields.io/github/stars/langchain-ai/langgraph-reflection?style=social) | **langgraph-codeact** | [langchain-ai/langgraph-codeact](https://github.com/langchain-ai/langgraph-codeact) | LangGraph implementation of CodeAct agent that generates and executes code instead of tool calling. | -12345 | ![GitHub stars](https://img.shields.io/github/stars/langchain-ai/langgraph-codeact?style=social) -## ✨ Contributing Your Library +## ✨ Contributing your library Have you built an awesome open-source library using LangGraph? We'd love to feature your project on the official LangGraph documentation pages! 🏆 diff --git a/docs/docs/concepts/langgraph_standalone_container.md b/docs/docs/concepts/langgraph_standalone_container.md index 2d121a390..94da8c957 100644 --- a/docs/docs/concepts/langgraph_standalone_container.md +++ b/docs/docs/concepts/langgraph_standalone_container.md @@ -33,7 +33,9 @@ The Standalone Container deployment option supports deploying data plane infrast ## Lite vs. Enterprise -The Standalone Container deployment option supports the both [server versions](../concepts/langgraph_server.md#langgraph-server): +The Standalone Container deployment option supports both of the [server versions](../concepts/langgraph_server.md#langgraph-server): - The `Lite` version is free, but has limited features. -- The `Enterprise` version has custom pricing and is fully featured. For more details on feature difference, see [LangGraph Server](../concepts/langgraph_server.md#server-versions). +- The `Enterprise` version has custom pricing and is fully featured. + +For more details on feature difference, see [LangGraph Server](../concepts/langgraph_server.md#server-versions). diff --git a/docs/docs/concepts/pregel.md b/docs/docs/concepts/pregel.md index 9ff2a855e..3c8b01cac 100644 --- a/docs/docs/concepts/pregel.md +++ b/docs/docs/concepts/pregel.md @@ -3,7 +3,7 @@ search: boost: 2 --- -# LangGraph's Runtime (Pregel) +# LangGraph runtime [Pregel][langgraph.pregel.Pregel] implements LangGraph's runtime, managing the execution of LangGraph applications. diff --git a/docs/docs/llms-txt-overview.md b/docs/docs/llms-txt-overview.md index 7874f90f2..913cb8aa9 100644 --- a/docs/docs/llms-txt-overview.md +++ b/docs/docs/llms-txt-overview.md @@ -1,6 +1,4 @@ -# LLMs-txt Overview - -## Overview +# llms.txt Below you can find a list of documentation files in the [`llms.txt`](https://llmstxt.org/) format, specifically `llms.txt` and `llms-full.txt`. These files allow large language models (LLMs) and agents to access programming documentation and APIs, particularly useful within integrated development environments (IDEs). diff --git a/docs/docs/tutorials/auth/add_auth_server.md b/docs/docs/tutorials/auth/add_auth_server.md index 05c9fad6f..4cb977130 100644 --- a/docs/docs/tutorials/auth/add_auth_server.md +++ b/docs/docs/tutorials/auth/add_auth_server.md @@ -1,23 +1,13 @@ -# Connecting an Authentication Provider (Part 3/3) +# Connect an authentication provider -!!! note "This is part 3 of our authentication series:" +In the [the last tutorial](resource_auth.md), you added [resource authorization](../../tutorials/auth/resource_auth.md) to give users private conversations. However, you are still using hard-coded tokens for authentication, which is not secure. Now you'll replace those tokens with real user accounts using [OAuth2](../auth/getting_started.md). - 1. [Basic Authentication](getting_started.md) - Control who can access your bot - 2. [Resource Authorization](resource_auth.md) - Let users have private conversations - 3. Production Auth (you are here) - Add real user accounts and validate using OAuth2 - -In the [Making Conversations Private](resource_auth.md) tutorial, we added [resource authorization](../../tutorials/auth/resource_auth.md) to give users private conversations. However, we were still using hard-coded tokens for authentication, which is not secure. Now we'll replace those tokens with real user accounts using [OAuth2](../auth/getting_started.md). - -We'll keep the same [`Auth`](../../cloud/reference/sdk/python_sdk_ref.md#langgraph_sdk.auth.Auth) object and [resource-level access control](../../concepts/auth.md#single-owner-resources), but upgrade our authentication to use Supabase as our identity provider. While we use Supabase in this tutorial, the concepts apply to any OAuth2 provider. You'll learn how to: +You'll keep the same [`Auth`](../../cloud/reference/sdk/python_sdk_ref.md#langgraph_sdk.auth.Auth) object and [resource-level access control](../../concepts/auth.md#single-owner-resources), but upgrade authentication to use Supabase as your identity provider. While Supabase is used in this tutorial, the concepts apply to any OAuth2 provider. You'll learn how to: 1. Replace test tokens with real JWT tokens 2. Integrate with OAuth2 providers for secure user authentication 3. Handle user sessions and metadata while maintaining our existing authorization logic -## Requirements - -You will need to set up a Supabase project to use its authentication server for this tutorial. You can do so [here](https://supabase.com/dashboard). - ## Background OAuth2 involves three main roles: @@ -45,53 +35,57 @@ sequenceDiagram LangGraph Backend->>Client: Serve request (e.g., run agent or graph) ``` -In the following example, we'll use Supabase as our auth server. The LangGraph application will provide the backend for your app, and we will write test code for the client app. -Let's get started! +## Prerequisites -## Setting Up Authentication Provider {#setup-auth-provider} +Before you start this tutorial, ensure you have: -First, let's install the required dependencies. Start in your `custom-auth` directory and ensure you have the `langgraph-cli` installed: +- The [bot from the second tutorial](resource_auth.md) running without errors. +- A [Supabase project](https://supabase.com/dashboard) to use its authentication server. + + +## 1. Install dependencies + +Install the required dependencies. Start in your `custom-auth` directory and ensure you have the `langgraph-cli` installed: ```bash cd custom-auth pip install -U "langgraph-cli[inmem]" ``` -Next, we'll need to fech the URL of our auth server and the private key for authentication. -Since we're using Supabase for this, we can do this in the Supabase dashboard: +## 2. Set up the authentication provider {#setup-auth-provider} + +Next, fetch the URL of your auth server and the private key for authentication. +Since you're using Supabase for this, you can do this in the Supabase dashboard: 1. In the left sidebar, click on t️⚙ Project Settings" and then click "API" -2. Copy your project URL and add it to your `.env` file +1. Copy your project URL and add it to your `.env` file -```shell -echo "SUPABASE_URL=your-project-url" >> .env -``` -3. Next, copy your service role secret key and add it to your `.env` file -```shell -echo "SUPABASE_SERVICE_KEY=your-service-role-key" >> .env -``` -4. Finally, copy your "anon public" key and note it down. This will be used later when we set up our client code. + ```shell + echo "SUPABASE_URL=your-project-url" >> .env + ``` +1. Copy your service role secret key and add it to your `.env` file: -```bash -SUPABASE_URL=your-project-url -SUPABASE_SERVICE_KEY=your-service-role-key -``` + ```shell + echo "SUPABASE_SERVICE_KEY=your-service-role-key" >> .env + ``` +1. Copy your "anon public" key and note it down. This will be used later when you set up our client code. -## Implementing Token Validation + ```bash + SUPABASE_URL=your-project-url + SUPABASE_SERVICE_KEY=your-service-role-key + ``` -In the previous tutorials, we used the [`Auth`](../../cloud/reference/sdk/python_sdk_ref.md#langgraph_sdk.auth.Auth) object to: +## 3. Implement token validation -1. Validate hard-coded tokens in the [authentication tutorial](getting_started.md) -2. Add resource ownership in the [authorization tutorial](resource_auth.md) +In the previous tutorials, you used the [`Auth`](../../cloud/reference/sdk/python_sdk_ref.md#langgraph_sdk.auth.Auth) object to [validate hard-coded tokens](getting_started.md) and [add resource ownership](resource_auth.md). -Now we'll upgrade our authentication to validate real JWT tokens from Supabase. The key changes will all be in the [`@auth.authenticate`](../../cloud/reference/sdk/python_sdk_ref.md#langgraph_sdk.auth.Auth.authenticate) decorated function: +Now you'll upgrade your authentication to validate real JWT tokens from Supabase. The main changes will all be in the [`@auth.authenticate`](../../cloud/reference/sdk/python_sdk_ref.md#langgraph_sdk.auth.Auth.authenticate) decorated function: -1. Instead of checking against a hard-coded list of tokens, we'll make an HTTP request to Supabase to validate the token -2. We'll extract real user information (ID, email) from the validated token +- Instead of checking against a hard-coded list of tokens, you'll make an HTTP request to Supabase to validate the token. +- You'll extract real user information (ID, email) from the validated token. +- The existing resource authorization logic remains unchanged. -And we'll keep our existing resource authorization logic unchanged - -Let's update `src/security/auth.py` to implement this: +Update `src/security/auth.py` to implement this: ```python hl_lines="8-9 20-30" title="src/security/auth.py" import os @@ -146,11 +140,9 @@ async def add_owner(ctx, value): The most important change is that we're now validating tokens with a real authentication server. Our authentication handler has the private key for our Supabase project, which we can use to validate the user's token and extract their information. -Let's test this with a real user account! +## 4. Test authentication flow -## Testing Authentication Flow - -Let's test out our new authentication flow. You can run the following code in a file or notebook. You will need to provide: +Let's test out the new authentication flow. You can run the following code in a file or notebook. You will need to provide: - A valid email address - A Supabase project URL (from [above](#setup-auth-provider)) @@ -198,14 +190,9 @@ await sign_up(email1, password) await sign_up(email2, password) ``` -Then run the code. - -!!! tip "About test emails" - We'll create two test accounts by adding "+1" and "+2" to your email. For example, if you use "myemail@gmail.com", we'll create "myemail+1@gmail.com" and "myemail+2@gmail.com". All emails will be delivered to your original address. - ⚠️ Before continuing: Check your email and click both confirmation links. Supabase will will reject `/login` requests until after you have confirmed your users' email. -Now let's test that users can only see their own data. Make sure the server is running (run `langgraph dev`) before proceeding. The following snippet requires the "anon public" key that you copied from the Supabase dashboard while [setting up the auth provider](#setup-auth-provider) previously. +Now test that users can only see their own data. Make sure the server is running (run `langgraph dev`) before proceeding. The following snippet requires the "anon public" key that you copied from the Supabase dashboard while [setting up the auth provider](#setup-auth-provider) previously. ```python async def login(email: str, password: str): @@ -264,13 +251,14 @@ The output should look like this: ✅ User 2 blocked from User 1's thread: Client error '404 Not Found' for url 'http://localhost:2024/threads/d6af3754-95df-4176-aa10-dbd8dca40f1a' ``` -Perfect! Our authentication and authorization are working together: +Your authentication and authorization are working together: + 1. Users must log in to access the bot 2. Each user can only see their own threads -All our users are managed by the Supabase auth provider, so we don't need to implement any additional user management logic. +All users are managed by the Supabase auth provider, so you don't need to implement any additional user management logic. -## Congratulations! 🎉 +## Next steps You've successfully built a production-ready authentication system for your LangGraph application! Let's review what you've accomplished: @@ -280,10 +268,6 @@ You've successfully built a production-ready authentication system for your Lang 4. Implemented proper authorization to ensure users can only access their own data 5. Created a foundation that's ready to handle your next authentication challenge 🚀 -This completes our authentication tutorial series. You now have the building blocks for a secure, production-ready LangGraph application. - -## What's Next? - Now that you have production authentication, consider: 1. Building a web UI with your preferred framework (see the [Custom Auth](https://github.com/langchain-ai/custom-auth) template for an example) diff --git a/docs/docs/tutorials/auth/getting_started.md b/docs/docs/tutorials/auth/getting_started.md index 6669be1cb..cb7a8bdf7 100644 --- a/docs/docs/tutorials/auth/getting_started.md +++ b/docs/docs/tutorials/auth/getting_started.md @@ -1,32 +1,25 @@ -# Setting up Custom Authentication (Part 1/3) - -!!! note "This is part 1 of our authentication series:" - - 1. Basic Authentication (you are here) - Control who can access your bot - 2. [Resource Authorization](resource_auth.md) - Let users have private conversations - 3. [Production Auth](add_auth_server.md) - Add real user accounts and validate using OAuth2 - -!!! tip "Prerequisites" - - This guide assumes basic familiarity with the following concepts: - - * [**Authentication & Access Control**](../../concepts/auth.md) - * [**LangGraph Platform**](../../concepts/langgraph_platform.md) - -!!! note "Python only" - - We currently only support custom authentication and authorization in Python deployments with `langgraph-api>=0.0.11`. Support for LangGraph.JS will be added soon. - - -???+ note "Support by deployment type" - - Custom auth is supported for all deployments in the **managed LangGraph Cloud**, as well as **Enterprise** self-hosted plans. It is not supported for **Lite** self-hosted plans. +# Set up custom authentication In this tutorial, we will build a chatbot that only lets specific users access it. We'll start with the LangGraph template and add token-based security step by step. By the end, you'll have a working chatbot that checks for valid tokens before allowing access. -## Setting up our project +This is part 1 of our authentication series: -First, let's create a new chatbot using the LangGraph starter template: +1. Set up custom authentication (you are here) - Control who can access your bot +2. [Make conversations private](resource_auth.md) - Let users have private conversations +3. [Connect an authentication provider](add_auth_server.md) - Add real user accounts and validate using OAuth2 for production + +This guide assumes basic familiarity with the following concepts: + +* [**Authentication & Access Control**](../../concepts/auth.md) +* [**LangGraph Platform**](../../concepts/langgraph_platform.md) + +!!! note + + Custom auth is only available for LangGraph Cloud SaaS deployments or Enterprise Self-Hosted deployments. + +## 1. Create your app + +Create a new chatbot using the LangGraph starter template: ```bash pip install -U "langgraph-cli[inmem]" @@ -34,37 +27,40 @@ langgraph new --template=new-langgraph-project-python custom-auth cd custom-auth ``` -The template gives us a placeholder LangGraph app. Let's try it out by installing the local dependencies and running the development server. +The template gives us a placeholder LangGraph app. Try it out by installing the local dependencies and running the development server: + ```shell pip install -e . langgraph dev ``` -If everything works, the server should start and open the studio in your browser. +The server will start and open the studio in your browser: + +``` > - 🚀 API: http://127.0.0.1:2024 > - 🎨 Studio UI: https://smith.langchain.com/studio/?baseUrl=http://127.0.0.1:2024 > - 📚 API Docs: http://127.0.0.1:2024/docs > > This in-memory server is designed for development and testing. > For production use, please use LangGraph Cloud. +``` -The graph should run, and if you were to self-host this on the public internet, anyone could access it! +If you were to self-host this on the public internet, anyone could access it! ![No auth](./img/no_auth.png) -Now that we've seen the base LangGraph app, let's add authentication to it! -???+ tip "Placeholder token" - - In part 1, we will start with a hard-coded token for illustration purposes. - We will get to a "production-ready" authentication scheme in part 3, after mastering the basics. +## 2. Add authentication +Now that you have a base LangGraph app, add authentication to it. -## Adding Authentication +!!! note + + In this tutorial, you will start with a hard-coded token for example purposes. You will get to a "production-ready" authentication scheme in the third tutorial. The [`Auth`](../../cloud/reference/sdk/python_sdk_ref.md#langgraph_sdk.auth.Auth) object lets you register an authentication function that the LangGraph platform will run on every request. This function receives each request and decides whether to accept or reject. -Create a new file `src/security/auth.py`. This is where our code will live to check if users are allowed to access our bot: +Create a new file `src/security/auth.py`. This is where your code will live to check if users are allowed to access your bot: ```python hl_lines="10 15-16" title="src/security/auth.py" from langgraph_sdk import Auth @@ -98,12 +94,12 @@ async def get_current_user(authorization: str | None) -> Auth.types.MinimalUserD } ``` -Notice that our [authentication](../../cloud/reference/sdk/python_sdk_ref.md#langgraph_sdk.auth.Auth.authenticate) handler does two important things: +Notice that your [authentication](../../cloud/reference/sdk/python_sdk_ref.md#langgraph_sdk.auth.Auth.authenticate) handler does two important things: 1. Checks if a valid token is provided in the request's [Authorization header](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Authorization) 2. Returns the user's [identity](../../cloud/reference/sdk/python_sdk_ref.md#langgraph_sdk.auth.types.MinimalUserDict) -Now tell LangGraph to use our authentication by adding the following to the [`langgraph.json`](../../cloud/reference/cli.md#configuration-file) configuration: +Now tell LangGraph to use authentication by adding the following to the [`langgraph.json`](../../cloud/reference/cli.md#configuration-file) configuration: ```json hl_lines="7-9" title="langgraph.json" { @@ -118,28 +114,28 @@ Now tell LangGraph to use our authentication by adding the following to the [`la } ``` -## Testing Our "Secure" Bot +## 3. Test your bot -Let's start the server again to test everything out! +Start the server again to test everything out: ```bash langgraph dev --no-browser ``` -??? note "Custom auth in the studio" +If you didn't add the `--no-browser`, the studio UI will open in the browser. You may wonder, how is the studio able to still connect to our server? By default, we also permit access from the LangGraph studio, even when using custom auth. This makes it easier to develop and test your bot in the studio. You can remove this alternative authentication option by setting `disable_studio_auth: "true"` in your auth configuration: - If you didn't add the `--no-browser`, the studio UI will open in the browser. You may wonder, how is the studio able to still connect to our server? By default, we also permit access from the LangGraph studio, even when using custom auth. This makes it easier to develop and test your bot in the studio. You can remove this alternative authentication option by - setting `disable_studio_auth: "true"` in your auth configuration: - ```json - { - "auth": { - "path": "src/security/auth.py:auth", - "disable_studio_auth": "true" - } +```json +{ + "auth": { + "path": "src/security/auth.py:auth", + "disable_studio_auth": "true" } - ``` +} +``` -Now let's try to chat with our bot. If we've implemented authentication correctly, we should only be able to access the bot if we provide a valid token in the request header. Users will still, however, be able to access each other's resources until we add [resource authorization handlers](../../concepts/auth.md#resource-specific-handlers) in the next section of our tutorial. +## 4. Chat with your bot + +You should now only be able to access the bot if you provide a valid token in the request header. Users will still, however, be able to access each other's resources until you add [resource authorization handlers](../../concepts/auth.md#resource-specific-handlers) in the next section of the tutorial. ![Authentication, no authorization handlers](./img/authentication.png) @@ -181,10 +177,10 @@ You should see that: Congratulations! You've built a chatbot that only lets "authenticated" users access it. While this system doesn't (yet) implement a production-ready security scheme, we've learned the basic mechanics of how to control access to our bot. In the next tutorial, we'll learn how to give each user their own private conversations. -## What's Next? +## Next steps Now that you can control who accesses your bot, you might want to: -1. Continue the tutorial by going to [Making Conversations Private (Part 2/3)](resource_auth.md) to learn about resource authorization. +1. Continue the tutorial by going to [Make cnversations private](resource_auth.md) to learn about resource authorization. 2. Read more about [authentication concepts](../../concepts/auth.md). 3. Check out the [API reference](../../cloud/reference/sdk/python_sdk_ref.md) for more authentication details. \ No newline at end of file diff --git a/docs/docs/tutorials/auth/resource_auth.md b/docs/docs/tutorials/auth/resource_auth.md index 54e3b8322..267e00f25 100644 --- a/docs/docs/tutorials/auth/resource_auth.md +++ b/docs/docs/tutorials/auth/resource_auth.md @@ -1,43 +1,20 @@ -# Making Conversations Private (Part 2/3) +# Make conversations private -!!! note "This is part 2 of our authentication series:" - - 1. [Basic Authentication](getting_started.md) - Control who can access your bot - 2. Resource Authorization (you are here) - Let users have private conversations - 3. [Production Auth](add_auth_server.md) - Add real user accounts and validate using OAuth2 - -In this tutorial, we will extend our chatbot to give each user their own private conversations. We'll add [resource-level access control](../../concepts/auth.md#single-owner-resources) so users can only see their own threads. +In this tutorial, you will extend [the chatbot created in the last tutorial](getting_started.md) to give each user their own private conversations. You'll add [resource-level access control](../../concepts/auth.md#single-owner-resources) so users can only see their own threads. ![Authorization handlers](./img/authorization.png) -???+ tip "Placeholder token" - - As we did in [part 1](getting_started.md), for this section, we will use a hard-coded token for illustration purposes. - We will get to a "production-ready" authentication scheme in part 3, after mastering the basics. +## Prerequisites -## Understanding Resource Authorization +Before you start this tutorial, ensure you have the [bot from the first tutorial](getting_started.md) running without errors. -In the last tutorial, we controlled who could access our bot. But right now, any authenticated user can see everyone else's conversations! Let's fix that by adding [resource authorization](../auth/resource_auth.md). +## 1. Add resource authorization -First, make sure you have completed the [Basic Authentication](getting_started.md) tutorial and that your secure bot can be run without errors: - -```bash -cd custom-auth -pip install -e . -langgraph dev --no-browser -``` - -> - 🚀 API: http://127.0.0.1:2024 -> - 🎨 Studio UI: https://smith.langchain.com/studio/?baseUrl=http://127.0.0.1:2024 -> - 📚 API Docs: http://127.0.0.1:2024/docs - -## Adding Resource Authorization - -Recall that in the last tutorial, the [`Auth`](../../cloud/reference/sdk/python_sdk_ref.md#langgraph_sdk.auth.Auth) object let us register an [authentication function](../../concepts/auth.md#authentication), which the LangGraph platform uses to validate the bearer tokens in incoming requests. Now we'll use it to register an **authorization** handler. +Recall that in the last tutorial, the [`Auth`](../../cloud/reference/sdk/python_sdk_ref.md#langgraph_sdk.auth.Auth) object lets you register an [authentication function](../../concepts/auth.md#authentication), which LangGraph Platform uses to validate the bearer tokens in incoming requests. Now you'll use it to register an **authorization** handler. Authorization handlers are functions that run **after** authentication succeeds. These handlers can add [metadata](../../concepts/auth.md#filter-operations) to resources (like who owns them) and filter what each user can see. -Let's update our `src/security/auth.py` and add one authorization handler that is run on every request: +Update your `src/security/auth.py` and add one authorization handler to run on every request: ```python hl_lines="29-39" title="src/security/auth.py" from langgraph_sdk import Auth @@ -114,7 +91,7 @@ async def add_owner( # } # } - # Do 2 things: + # Does 2 things: # 1. Add the user's ID to the resource's metadata. Each LangGraph resource has a `metadata` dict that persists with the resource. # this metadata is useful for filtering in read and update operations # 2. Return a filter that lets users only see their own resources @@ -131,14 +108,14 @@ The handler receives two parameters: 1. `ctx` ([AuthContext](../../cloud/reference/sdk/python_sdk_ref.md#langgraph_sdk.auth.types.AuthContext)): contains info about the current `user`, the user's `permissions`, the `resource` ("threads", "crons", "assistants"), and the `action` being taken ("create", "read", "update", "delete", "search", "create_run") 2. `value` (`dict`): data that is being created or accessed. The contents of this dict depend on the resource and action being accessed. See [adding scoped authorization handlers](#scoped-authorization) below for information on how to get more tightly scoped access control. -Notice that our simple handler does two things: +Notice that the simple handler does two things: 1. Adds the user's ID to the resource's metadata. 2. Returns a metadata filter so users only see resources they own. -## Testing Private Conversations +## 2. Test private conversations -Let's test our authorization. If we have set things up correctly, we should expect to see all ✅ messages. Be sure to have your development server running (run `langgraph dev`): +Test your authorization. If you have set things up correctly, you will see all ✅ messages. Be sure to have your development server running (run `langgraph dev`): ```python from langgraph_sdk import get_client @@ -191,7 +168,7 @@ print(f"✅ Alice sees {len(alice_threads)} thread") print(f"✅ Bob sees {len(bob_threads)} thread") ``` -Run the test code and you should see output like this: +Output: ```bash ✅ Alice created assistant: fc50fb08-78da-45a9-93cc-1d3928a3fc37 @@ -209,9 +186,9 @@ This means: 2. Users can't see each other's threads 3. Listing threads only shows your own -## Adding scoped authorization handlers {#scoped-authorization} +## 3. Add scoped authorization handlers {#scoped-authorization} -The broad `@auth.on` handler matches on all [authorization events](../../concepts/auth.md#supported-resources). This is concise, but it means the contents of the `value` dict are not well-scoped, and we apply the same user-level access control to every resource. If we want to be more fine-grained, we can also control specific actions on resources. +The broad `@auth.on` handler matches on all [authorization events](../../concepts/auth.md#supported-resources). This is concise, but it means the contents of the `value` dict are not well-scoped, and the same user-level access control is applied to every resource. If you want to be more fine-grained, you can also control specific actions on resources. Update `src/security/auth.py` to add handlers for specific resource types: @@ -284,7 +261,7 @@ async def authorize_store(ctx: Auth.types.AuthContext, value: dict): assert namespace[0] == ctx.user.identity, "Not authorized" ``` -Notice that instead of one global handler, we now have specific handlers for: +Notice that instead of one global handler, you now have specific handlers for: 1. Creating threads 2. Reading threads @@ -315,7 +292,7 @@ alice_thread = await alice.threads.create() print(f"✅ Alice created thread: {alice_thread['thread_id']}") ``` -And then run the test code again: +Output: ```bash ✅ Alice created thread: dcea5cd8-eb70-4a01-a4b6-643b14e8f754 @@ -329,12 +306,12 @@ For more information check: https://developer.mozilla.org/en-US/docs/Web/HTTP/St ✅ Alice correctly denied access to searching assistants: ``` -Congratulations! You've built a chatbot where each user has their own private conversations. While this system uses simple token-based authentication, the authorization patterns we've learned will work with implementing any real authentication system. In the next tutorial, we'll replace our test users with real user accounts using OAuth2. +Congratulations! You've built a chatbot where each user has their own private conversations. While this system uses simple token-based authentication, these authorization patterns will work with implementing any real authentication system. In the next tutorial, you'll replace your test users with real user accounts using OAuth2. ## What's Next? Now that you can control access to resources, you might want to: -1. Move on to [Production Auth](add_auth_server.md) to add real user accounts -2. Read more about [authorization patterns](../../concepts/auth.md#authorization) -3. Check out the [API reference](../../cloud/reference/sdk/python_sdk_ref.md#langgraph_sdk.auth.Auth) for details about the interfaces and methods used in this tutorial +1. Move on to [Connect an authentication provider](add_auth_server.md) to add real user accounts. +2. Read more about [authorization patterns](../../concepts/auth.md#authorization). +3. Check out the [API reference](../../cloud/reference/sdk/python_sdk_ref.md#langgraph_sdk.auth.Auth) for details about the interfaces and methods used in this tutorial. diff --git a/docs/docs/tutorials/deployment.md b/docs/docs/tutorials/deployment.md index b05d76089..9042d98b3 100644 --- a/docs/docs/tutorials/deployment.md +++ b/docs/docs/tutorials/deployment.md @@ -8,7 +8,7 @@ search: There are two free options for deploying LangGraph applications via the LangGraph Server: - [Local](./langgraph-platform/local-server.md): Deploy for local testing and development. -- Standalone Container (Lite): A limited version of Standalone Container for deployments unlikely to see more that 1 million node executions per year and that do not need crons and other enterprise features. Standalone Container (Lite) deployment option is free with a LangSmith API key. +- [Standalone Container (Lite)](../concepts/langgraph_standalone_container.md): A limited version of Standalone Container for deployments unlikely to see more that 1 million node executions per year and that do not need crons and other enterprise features. Standalone Container (Lite) deployment option is free with a LangSmith API key. ## Other deployment options @@ -19,4 +19,4 @@ Additionally, you can deploy to production with [LangGraph Platform](../concepts - [Self-Hosted Control Plane(Beta)](../concepts/langgraph_self_hosted_control_plane.md): Create deployments from a self-hosted [Control Plane UI](../concepts/langgraph_control_plane.md#control-plane-ui) and deploy LangGraph Servers to **your** cloud. *You manage everything.* - [Standalone Container](../concepts/langgraph_standalone_container.md): Deploy LangGraph Server Docker images however you like. -For more information, see [Deployment options](../concepts/deployment_options.md) +For more information, see [Deployment options](../concepts/deployment_options.md). diff --git a/docs/mkdocs.yml b/docs/mkdocs.yml index f245416fc..9ee7b9684 100644 --- a/docs/mkdocs.yml +++ b/docs/mkdocs.yml @@ -124,6 +124,7 @@ nav: - Workflows & agents: tutorials/workflows.md - Graphs: - Overview: concepts/low_level.md + - Runtime overview: concepts/pregel.md - Use the Graph API: how-tos/graph-api.ipynb - Streaming: - Overview: concepts/streaming.md @@ -156,13 +157,6 @@ nav: - Functional API: - Overview: concepts/functional_api.md - how-tos/use-functional-api.md - - concepts/pregel.md - - Other: - # We want to push async higher (need to check the content inside it) - # and convert it into a concept rather than a how-to page. - - how-tos/async.ipynb - - how-tos/run-id-langsmith.ipynb - - how-tos/autogen-integration.ipynb - LangGraph Platform: - Overview: concepts/langgraph_platform.md @@ -232,17 +226,17 @@ nav: - Webhooks: - Overview: cloud/concepts/webhooks.md - cloud/how-tos/webhooks.md - - Cron Jobs: + - Cron jobs: - Overview: cloud/concepts/cron_jobs.md - cloud/how-tos/cron_jobs.md - - Server Customization: + - Server customization: - how-tos/http/custom_lifespan.md - how-tos/http/custom_middleware.md - how-tos/http/custom_routes.md - Deployment: - Overview: concepts/deployment_options.md - - Data Plane: concepts/langgraph_data_plane.md - - Control Plane: concepts/langgraph_control_plane.md + - Data plane: concepts/langgraph_data_plane.md + - Control plane: concepts/langgraph_control_plane.md - Deployment options: - Cloud SaaS: - Overview: concepts/langgraph_cloud.md @@ -256,8 +250,8 @@ nav: - Standalone Container: - Overview: concepts/langgraph_standalone_container.md - Deploy Standalone Container: cloud/deployment/standalone_container.md - - Scalability and resilience: concepts/scalability_and_resilience.md - - Plans and pricing: concepts/plans.md + - Scalability & resilience: concepts/scalability_and_resilience.md + - Plans & pricing: concepts/plans.md - Reference: - reference/index.md @@ -289,23 +283,28 @@ nav: - Agentic RAG: tutorials/rag/langgraph_agentic_rag.ipynb - Agent Supervisor: tutorials/multi_agent/agent_supervisor.ipynb - SQL agent: tutorials/sql-agent.ipynb + - Run a graph asynchronously: how-tos/async.ipynb + # We want to push async higher (need to check the content inside it) + # and convert it into a concept rather than a how-to page. + - Graph runs in LangSmith: how-tos/run-id-langsmith.ipynb - LangGraph Platform: - Authentication: - tutorials/auth/getting_started.md - tutorials/auth/resource_auth.md - tutorials/auth/add_auth_server.md - Rebuild graph at runtime: cloud/deployment/graph_rebuild.md - - how-tos/use-remote-graph.md - - how-tos/autogen-langgraph-platform.ipynb + - Use RemoteGraph: how-tos/use-remote-graph.md + - Deploy CrewAI, AutoGen, and other frameworks: how-tos/autogen-langgraph-platform.ipynb + # combine with how-tos/autogen-integration.ipynb - Front-end and generative UI: - Integrate LangGraph into a React app: cloud/how-tos/use_stream_react.md - Implement generative UI with LangGraph: cloud/how-tos/generative_ui_react.md - Resources: - concepts/faq.md - - agents/prebuilt.md # NOTE: prebuilt.md is auto-generated by `make build-prebuilt` - Template applications: concepts/template_applications.md # TODO: make tutorial - llms.txt: llms-txt-overview.md + - agents/prebuilt.md # NOTE: prebuilt.md is auto-generated by `make build-prebuilt` - Troubleshooting: - Errors: - troubleshooting/errors/index.md diff --git a/libs/langgraph/README.md b/libs/langgraph/README.md index ae8f0084f..4425ca270 100644 --- a/libs/langgraph/README.md +++ b/libs/langgraph/README.md @@ -13,44 +13,50 @@ [![Open Issues](https://img.shields.io/github/issues-raw/langchain-ai/langgraph)](https://github.com/langchain-ai/langgraph/issues) [![Docs](https://img.shields.io/badge/docs-latest-blue)](https://langchain-ai.github.io/langgraph/) -> [!NOTE] -> Looking for the JS version? See the [JS repo](https://github.com/langchain-ai/langgraphjs) and the [JS docs](https://langchain-ai.github.io/langgraphjs/). - -LangGraph is a low-level orchestration framework for building controllable agents. While [LangChain](https://python.langchain.com/docs/introduction/) provides integrations and composable components to streamline LLM application development, the LangGraph library enables agent orchestration — offering customizable architectures, long-term memory, and human-in-the-loop to reliably handle complex tasks. +Trusted by companies shaping the future of agents – including Klarna, Replit, Elastic, and more – LangGraph is a powerful low-level orchestration framework for building, managing, and deploying long-running, stateful agents. ## Get started -First, install LangGraph: +Install LangGraph: ``` pip install -U langgraph ``` -There are two ways to get started with LangGraph: +Then, create an agent [using prebuilt components](https://langchain-ai.github.io/langgraph/agents/agents/): -- [Use prebuilt components](https://langchain-ai.github.io/langgraph/agents/agents/): Construct agentic systems quickly and reliably without the need to implement orchestration, memory, or human feedback handling from scratch. -- [Use LangGraph](https://langchain-ai.github.io/langgraph/tutorials/introduction/): Customize your architectures, use long-term memory, and implement human-in-the-loop to reliably handle complex tasks. +```python +# pip install -qU "langchain[anthropic]" to call the model -Once you have a LangGraph application and are ready to move into production, use [LangGraph Platform](https://langchain-ai.github.io/langgraph/cloud/quick_start/) to test, debug, and deploy your application. +from langgraph.prebuilt import create_react_agent -## What LangGraph provides +def get_weather(city: str) -> str: # (1)! + """Get weather for a given city.""" + return f"It's always sunny in {city}!" -LangGraph provides low-level supporting infrastructure that sits underneath *any* workflow or agent. It does not abstract prompts or architecture, and provides three central benefits: +agent = create_react_agent( + model="anthropic:claude-3-7-sonnet-latest", # (2)! + tools=[get_weather], # (3)! + prompt="You are a helpful assistant" # (4)! +) -### Persistence +# Run the agent +agent.invoke( + {"messages": [{"role": "user", "content": "what is the weather in sf"}]} +) +``` -LangGraph has a [persistence layer](https://langchain-ai.github.io/langgraph/concepts/persistence/), which offers a number of benefits: +For more information, see the [Quickstart](https://langchain-ai.github.io/langgraph/agents/agents/). Or, to learn how to build an [agent workflow](https://langchain-ai.github.io/langgraph/concepts/low_level/) with a customizable architecture, long-term memory, and other complex task handling, see the [LangGraph basics tutorials](https://langchain-ai.github.io/langgraph/tutorials/get-started/1-build-basic-chatbot/). -- [Memory](https://langchain-ai.github.io/langgraph/concepts/memory/): LangGraph persists arbitrary aspects of your application's state, supporting memory of conversations and other updates within and across user interactions; -- [Human-in-the-loop](https://langchain-ai.github.io/langgraph/concepts/human_in_the_loop/): Because state is checkpointed, execution can be interrupted and resumed, allowing for decisions, validation, and corrections via human input. +## Core benefits -### Streaming +LangGraph provides low-level supporting infrastructure for *any* long-running, stateful workflow or agent. LangGraph does not abstract prompts or architecture, and provides the following central benefits: -LangGraph provides support for [streaming](https://langchain-ai.github.io/langgraph/concepts/streaming/) workflow / agent state to the user (or developer) over the course of execution. LangGraph supports streaming of both events ([such as feedback from a tool call](https://langchain-ai.github.io/langgraph/how-tos/streaming.ipynb#updates)) and [tokens from LLM calls](https://langchain-ai.github.io/langgraph/how-tos/streaming-tokens.ipynb) embedded in an application. - -### Debugging and deployment - -LangGraph provides an easy onramp for testing, debugging, and deploying applications via [LangGraph Platform](https://langchain-ai.github.io/langgraph/concepts/langgraph_platform/). This includes [Studio](https://langchain-ai.github.io/langgraph/concepts/langgraph_studio/), an IDE that enables visualization, interaction, and debugging of workflows or agents. This also includes numerous [options](https://langchain-ai.github.io/langgraph/tutorials/deployment/) for deployment. +- [Durable execution](https://langchain-ai.github.io/langgraph/concepts/durable_execution/): Build agents that persist through failures and can run for extended periods, automatically resuming from exactly where they left off. +- [Human-in-the-loop](https://langchain-ai.github.io/langgraph/concepts/human_in_the_loop/): Seamlessly incorporate human oversight by inspecting and modifying agent state at any point during execution. +- [Comprehensive memory](https://langchain-ai.github.io/langgraph/concepts/memory/): Create truly stateful agents with both short-term working memory for ongoing reasoning and long-term persistent memory across sessions. +- [Debugging with LangSmith](http://www.langchain.com/langsmith): Gain deep visibility into complex agent behavior with visualization tools that trace execution paths, capture state transitions, and provide detailed runtime metrics. +- [Production-ready deployment](https://langchain-ai.github.io/langgraph/concepts/deployment_options/): Deploy sophisticated agent systems confidently with scalable infrastructure designed to handle the unique challenges of stateful, long-running workflows. ## LangGraph’s ecosystem @@ -58,6 +64,10 @@ While LangGraph can be used standalone, it also integrates seamlessly with any L - [LangSmith](http://www.langchain.com/langsmith) — Helpful for agent evals and observability. Debug poor-performing LLM app runs, evaluate agent trajectories, gain visibility in production, and improve performance over time. - [LangGraph Platform](https://langchain-ai.github.io/langgraph/concepts/#langgraph-platform) — Deploy and scale agents effortlessly with a purpose-built deployment platform for long running, stateful workflows. Discover, reuse, configure, and share agents across teams — and iterate quickly with visual prototyping in [LangGraph Studio](https://langchain-ai.github.io/langgraph/concepts/langgraph_studio/). +- [LangChain](https://python.langchain.com/docs/introduction/) – Provides integrations and composable components to streamline LLM application development. + +> [!NOTE] +> Looking for the JS version of LangGraph? See the [JS repo](https://github.com/langchain-ai/langgraphjs) and the [JS docs](https://langchain-ai.github.io/langgraphjs/). ## Additional resources