types

Status of a run execution.

Strategy for handling multiple concurrent tasks.

Behavior when encountering conflicts.

Behavior when an entity doesn't exist.

Status of a thread.

Type for arbitrary metadata attached to entities.

Allows storing custom key-value pairs with any entity. Keys must be strings, values can be any JSON-serializable type.

metadata = {
    "created_by": "user123",
    "priority": 1,
    "tags": ["important", "urgent"]
}

Type for authentication functions.

An authenticator can return either:

1. A string (user_id)
2. A dict containing {"identity": str, "permissions": list[str]}
3. An object with identity and permissions properties

Permissions can be used downstream by your authorization logic to determine access permissions to different resources.

The authenticate decorator will automatically inject any of the following parameters by name if they are included in your function signature:

User objects must at least expose the identity property.

The dictionary representation of a user.

The base ASGI user protocol

A user object that's populated from authenticated requests from the LangGraph studio.

Note: Studio auth can be disabled in your langgraph.json config.

{
  "auth": {
    "disable_studio_auth": true
  }
}

You can use isinstance checks in your authorization handlers (@auth.on) to control access specifically for developers accessing the instance from the LangGraph Studio UI.

@auth.on
async def allow_developers(ctx: Auth.types.AuthContext, value: Any) -> None:
    if isinstance(ctx.user, Auth.types.StudioUser):
        return None
    ...
    return False

Base class for authentication context.

Provides the fundamental authentication information needed for authorization decisions.

Complete authentication context with resource and action information.

Extends BaseAuthContext with specific resource and action being accessed, allowing for fine-grained access control decisions.

Time-to-live configuration for a thread.

Matches the OpenAPI schema where TTL is represented as an object with an optional strategy and a time value in minutes.

Parameters for creating a new thread.

create_params = {
    "thread_id": UUID("123e4567-e89b-12d3-a456-426614174000"),
    "metadata": {"owner": "user123"},
    "if_exists": "do_nothing"
}

Parameters for reading thread state or run information.

This type is used in three contexts:

1. Reading thread, thread version, or thread state information: Only thread_id is provided
2. Reading run information: Both thread_id and run_id are provided

Parameters for updating a thread or run.

Called for updates to a thread, thread version, or run cancellation.

Parameters for deleting a thread.

Called for deletes to a thread, thread version, or run

Parameters for searching threads.

Called for searches to threads or runs.

Payload for creating a run.

create_params = {
    "assistant_id": UUID("123e4567-e89b-12d3-a456-426614174000"),
    "thread_id": UUID("123e4567-e89b-12d3-a456-426614174001"),
    "run_id": UUID("123e4567-e89b-12d3-a456-426614174002"),
    "status": "pending",
    "metadata": {"owner": "user123"},
    "prevent_insert_if_inflight": True,
    "multitask_strategy": "reject",
    "if_not_exists": "create",
    "after_seconds": 10,
    "kwargs": {"key": "value"},
    "action": "interrupt"
}

Payload for creating an assistant.

create_params = {
    "assistant_id": UUID("123e4567-e89b-12d3-a456-426614174000"),
    "graph_id": "graph123",
    "config": {"tags": ["tag1", "tag2"]},
    "context": {"key": "value"},
    "metadata": {"owner": "user123"},
    "if_exists": "do_nothing",
    "name": "Assistant 1"
}

Payload for reading an assistant.

read_params = {
    "assistant_id": UUID("123e4567-e89b-12d3-a456-426614174000"),
    "metadata": {"owner": "user123"}
}

Payload for updating an assistant.

update_params = {
    "assistant_id": UUID("123e4567-e89b-12d3-a456-426614174000"),
    "graph_id": "graph123",
    "config": {"tags": ["tag1", "tag2"]},
    "context": {"key": "value"},
    "metadata": {"owner": "user123"},
    "name": "Assistant 1",
    "version": 1
}

Payload for deleting an assistant.

delete_params = {
    "assistant_id": UUID("123e4567-e89b-12d3-a456-426614174000")
}

Payload for searching assistants.

search_params = {
    "graph_id": "graph123",
    "metadata": {"owner": "user123"},
    "limit": 10,
    "offset": 0
}

Payload for creating a cron job.

create_params = {
    "payload": {"key": "value"},
    "schedule": "0 0 * * *",
    "cron_id": UUID("123e4567-e89b-12d3-a456-426614174000"),
    "thread_id": UUID("123e4567-e89b-12d3-a456-426614174001"),
    "user_id": "user123",
    "end_time": datetime(2024, 3, 16, 10, 0, 0)
}

Payload for deleting a cron job.

delete_params = {
    "cron_id": UUID("123e4567-e89b-12d3-a456-426614174000")
}

Payload for reading a cron job.

read_params = {
    "cron_id": UUID("123e4567-e89b-12d3-a456-426614174000")
}

Payload for updating a cron job.

update_params = {
    "cron_id": UUID("123e4567-e89b-12d3-a456-426614174000"),
    "payload": {"key": "value"},
    "schedule": "0 0 * * *"
}

Payload for searching cron jobs.

search_params = {
    "assistant_id": UUID("123e4567-e89b-12d3-a456-426614174000"),
    "thread_id": UUID("123e4567-e89b-12d3-a456-426614174001"),
    "limit": 10,
    "offset": 0
}

Operation to retrieve a specific item by its namespace and key.

This dict is mutable — auth handlers can modify namespace to enforce access scoping (e.g., prepending the user's identity).

Operation to search for items within a specified namespace hierarchy.

This dict is mutable — auth handlers can modify namespace to enforce access scoping (e.g., prepending the user's identity).

Operation to list and filter namespaces in the store.

This dict is mutable — auth handlers can modify namespace (the prefix) to enforce access scoping (e.g., prepending the user's identity).

Operation to store, update, or delete an item in the store.

This dict is mutable — auth handlers can modify namespace to enforce access scoping (e.g., prepending the user's identity).

Operation to delete an item from the store.

This dict is mutable — auth handlers can modify namespace to enforce access scoping (e.g., prepending the user's identity).

Namespace for type definitions of different API operations.

This class organizes type definitions for create, read, update, delete, and search operations across different resources (threads, assistants, crons).

from langgraph_sdk import Auth

auth = Auth()

@auth.on
def handle_all(params: Auth.on.value):
    raise Exception("Not authorized")

@auth.on.threads.create
def handle_thread_create(params: Auth.on.threads.create.value):
    # Handle thread creation
    pass

@auth.on.assistants.search
def handle_assistant_search(params: Auth.on.assistants.search.value):
    # Handle assistant search
    pass

Response type for authorization handlers.

The result of a handler can be:

• None | True: accept the request.
• False: reject the request with a 403 error
• FilterType: filter to apply