deployment

158 notes in this subject, read out of this brain and free to use. This is page 2 of 3.

LangSmith semantic search configuration in langgraph.json

Enable semantic search in langgraph.json by configuring: {'store': {'index': {'embed': 'openai:text-embeddings-3-small', 'dims': 1536, 'fields': ['$']}}} where fields can be specific field names or '$' to embed all fields.

Environment variable setup for Studio connection

Studio requires a LangSmith API key to connect a local agent. Create a .env file in the project root and add LANGSMITH_API_KEY=lsv2... (where lsv2... is your actual API key from https://smith.langchain.com/settings). Ensure the .env file is not committed to version control.

Install LangGraph CLI for local development server

The LangGraph CLI provides a local development server (also called Agent Server) that connects an agent to Studio. For Python (version 3.11 or higher required), install with: pip install --upgrade "langgraph-cli[inmem]". For JavaScript, use: npx @langchain/langgraph-cli.

langgraph.json configuration file structure

The LangGraph CLI uses a langgraph.json configuration file in the app's root directory to locate the agent and manage dependencies. The file must include: dependencies array (typically ["."] for the current directory), graphs object with key-value pairs where the key is the graph name and value is the path to the graph file and export (e.g., "./src/agent.py:agent" for Python or "./src/agent.ts:agent" for TypeScript), and env key pointing to the .env file (e.g., ".env").

Start local development server for Studio

To start the development server and connect an agent to Studio, run: langgraph dev (for Python) or npx @langchain/langgraph-cli dev (for JavaScript). Once running, the agent is accessible via API at http://127.0.0.1:2024 and through the Studio UI at https://smith.langchain.com/studio/?baseUrl=http://127.0.0.1:2024.

Safari localhost connection workaround for Studio

Safari blocks localhost connections to Studio. To work around this limitation, run the langgraph dev command with the --tunnel flag to access Studio via a secure tunnel. Manually add the tunnel URL to allowed origins by clicking 'Connect to a local server' in the Studio UI.

Graph compilation with checkpointer for local server

When running graph with Local_Server, compile without checkpointer to avoid persistence issues during deployment.

Agent Chat UI message rendering

Agent Chat UI has out-of-the-box support for rendering tool calls and tool result messages. Message display can be customized through the 'Hiding Messages in the Chat' configuration.

Agent Chat UI configuration parameters

To connect Agent Chat UI to an agent, you must configure three parameters: Graph ID (enter your graph name, found under graphs in langgraph.json), Deployment URL (your Agent server's endpoint such as http://localhost:2024 for local development or a deployed agent's URL), and LangSmith API key (optional, not required for local Agent server).

Agent Chat UI connection targets

Agent Chat UI can connect to both local agents and deployed agents. After starting Agent Chat UI, it will automatically fetch and display any interrupted threads from your agent after configuration.

langgraph-docs skill workflow for fetching documentation

The langgraph-docs skill uses a three-step workflow: (1) Fetch the documentation index from https://docs.langchain.com/llms.txt to get a structured list of all available documentation with descriptions. (2) Select 2-4 most relevant URLs from the index, prioritizing implementation questions (specific how-to guides), conceptual questions (core concept pages), end-to-end examples (tutorials), and API details (reference docs). (3) Fetch and apply the selected URLs using fetch_url, then complete the user's request using the documentation content. If fetch_url fails or returns empty content, retry once; if it fails again, inform the user and suggest checking https://langchain-ai.github.io/langgraph/ directly.

langgraph-docs skill documentation homepage

The primary LangGraph documentation homepage is https://langchain-ai.github.io/langgraph/.

OAuth provider setup process

To set up an OAuth provider: (1) Select a unique provider_id (e.g., "github-local-dev"); (2) Create a new OAuth application in your provider's developer console; (3) Set the callback URL to https://smith.langchain.com/host-oauth-callback/{provider_id} for LangSmith Cloud or https://{your-langsmith-instance}/host-oauth-callback/{provider_id} for self-hosted; (4) Call client.create_oauth_provider() with provider_id, name, client_id, client_secret, auth_url, and token_url.

Agent Auth installation

Install langchain-auth package using pip install langchain-auth for Python or npm install @langchain/auth for JavaScript.

Agent Auth client initialization

Initialize the Agent Auth client using Client(api_key="you••••••ey") in Python or new Client({apiKey: 'you••••••ey'}) in JavaScript.

Self-hosted LangSmith Agent Auth configuration

For self-hosted LangSmith instances, specify the API URL using the /api-host path on your instance. Set LANGSMITH_API_URL environment variable to "https://your-langsmith-instance.com/api-host" or pass api_url parameter to Client constructor.

OAuth provider creation API

Use client.create_oauth_provider() to register an OAuth provider. Parameters: provider_id (unique identifier), name (display name), client_id, client_secret, auth_url, token_url. In JavaScript use client.createOAuthProvider() with camelCase parameters.

Server graph function export in langgraph.json

The graph function that handles distributed tracing should be exported in langgraph.json under the graphs section. For example: {"graphs": {"agent": "./src/agent.py:graph"}}

Agent Server customization features

Agent Server supports customization through caching, custom stores and checkpointers, lifespan hooks, middleware, custom routes, encryption, and configurable headers and logs.

Agent Server operational features

Agent Server supports CI/CD pipelines, TTL configuration for state and thread management, and semantic search capabilities.

Agent Server auth and access control

Agent Server provides authentication, resource-level access enforcement, and connection to external OAuth2 identity providers for securing the server.

Agent Server three primitives

The Agent Server runtime operates with three primitives: assistants for configuration, threads for state, and runs for workloads.

Agent Server core capabilities

Agent Server provides capabilities for working with assistants, threads, runs, and cron jobs. It supports streaming to users, pausing for human review, handling concurrent input, and connecting via MCP and A2A.

Agent Server application structure

Agent Server applications involve structuring the app, configuring dependencies for Python and JavaScript, supporting monorepos, and connecting agents with RemoteGraph, semantic search, TTLs, and CI/CD.

Deployment authorization warning at server start

Deployments now see a structured warning at server start listing every uncovered dispatch path along with a default-deny snippet to copy. The warning is silent for deployments that register a global @auth.on handler or that only use @auth.authenticate without any resource-level handlers.

Agent Server release cadence: latest, rc, stable

Agent Server (langgraph-api) maintains three release streams: latest (published every morning with dev tag, e.g. 0.9.0.dev1), rc (published every three weeks with rc tag, e.g. 0.9.0rc1), and stable (published every three weeks from rc with minor/patch bumps, e.g. 0.9.0). Deployments use the newest stable version by default and are automatically updated. To pin to a specific version, set api_version in langgraph.json.

Enable Redis run-queue trace logs with environment variable

Set LSD_RUN_QUEUE_TRACE_LOG environment variable to true (default false) or use coreApi.runQueueTraceLog config flag to enable verbose Redis run-queue trace logs.

FIPS variants of Wolfi Python and JS server images available

FIPS variants of Wolfi Python and JS server images are available (for example 3.13-wolfi-fips, 22-wolfi-fips), built with the Go FIPS 140 cryptographic module and FIPS-hardened OpenSSL for Node.

Redis Cluster pub/sub TLS connection fixed

Fixed Redis Cluster pub/sub failing to connect on TLS-only clusters when REDIS_CLUSTER=true, which previously attempted to dial port 0.

Queue runs query field selection explicit for backwards compatibility

Made queue runs query field selection explicit for backwards compatibility, so new run schema fields can be added without breaking older server versions during rollbacks.

loopback webhook targets denied by default (GHSA-2c9q-c2q9-qgqv)

Loopback webhook targets are now denied by default to fix an authentication-bypass primitive. The webhooks.url.disable_loopback policy now defaults to true, blocking relative-URL webhooks and localhost/127.x/::1/host.docker.internal absolute URLs. Set webhooks.url.disable_loopback: false in langgraph.json to opt back in when you control the routes.

POST /runs authorizes assistant via assistants.read event (GHSA-jfj5-wrj9-63x4)

POST /runs and POST /threads/{thread_id}/runs now authorize the attached assistant via the assistants.read auth event instead of assistants.search. This fixes a cross-user authorization bypass vulnerability. Client-supplied run/cron metadata is no longer forwarded into the assistants.read auth event payload. Breaking change: any @auth.on.assistants.search handler previously invoked during run creation is no longer called there — ensure you have an equivalent @auth.on.assistants.read handler.

Run queue polling moved from Postgres to Redis

In v0.8.0, run queue polling logic moved from Postgres to Redis to reduce database load and improve performance. The queue polling now goes through Redis and then fetches run details from Postgres. This is not a breaking change, but there may be a brief window where threads are scheduled non-chronologically immediately after upgrading. Run execution order is still guaranteed within each thread.

Custom encryption for thread.config and checkpoints

Enhanced custom encryption by parallelizing metadata and config processes, added encryption for thread.config and some checkpoints, improving tests and schema consistency.

LANGGRAPH_AES_JSON_KEYS enables AES encryption for JSON fields

Added LANGGRAPH_AES_JSON_KEYS configuration to enable AES encryption for specified JSON fields using a key name allowlist.

Go assistants implementation now default

Switched to using the Go assistants implementation by default for improved performance.

Agent card discovery via .well-known/agent-card.json

Mounted .well-known/agent-card.json under /a2a/{assistant_id}/ for A2A agent discovery.

GET /runs/crons/{cron_id} endpoint added

Added cron retrieval by ID endpoint GET /runs/crons/{cron_id}.

Cron pausing with is_enabled field

Added support for pausing crons with a new is_enabled field, allowing only enabled crons to be executed.

Optional timezone field for crons

Added optional timezone field to crons, allowing next_run_date computation in user's specified timezone, defaulting to UTC.

HTTP_MAX_REQUEST_BODY_BYTES limits request size

Added HTTP_MAX_REQUEST_BODY_BYTES config to limit HTTP request body size to 300MB, returning a 413 error for oversized requests to prevent memory exhaustion.

Support for custom certificate and key files for HTTPS

Allow passing custom certificate and key files (ssl_certfile, ssl_keyfile) to run the dev server over HTTPS.

Prefer: return=minimal on PATCH /threads/{id}

Added support for Prefer: return=minimal on PATCH /threads/{id} to improve efficiency by returning a 204 status with no body.

Redis connection health checks implementation

Agent server v0.4.43 implemented a health check for Redis connections to prevent them from idling out. This is used to maintain reliable connections in production deployments.

Avoid synchronous blocking operations in agents

Avoid synchronous blocking operations in agent code and prefer asynchronous operations. Long synchronous operations can block the main event loop, causing longer request and run execution times and potential timeouts. If an assistant requires synchronous blocking operations, run those in asyncio.to_thread() or equivalent.

Enable queue workers for production deployment

By default, the API server manages the queue and does not use queue workers. Enable queue workers by setting queue.enabled to true. This offloads queue management from the API server to dedicated queue workers, reducing load on the API server and allowing it to focus on handling requests.

Calculate available jobs capacity formula

Available jobs capacity is calculated as: available_jobs = number_of_queue_workers * N_JOBS_PER_WORKER. Throughput per second is then: throughput_per_second = available_jobs / average_run_execution_time_seconds. The minimum number of queue workers to provision is: number_of_queue_workers = throughput_per_second * average_run_execution_time_seconds / N_JOBS_PER_WORKER.

Request vs run concurrency definition

Request concurrency is how many API requests (creating runs, reading thread state, streaming results) the deployment serves at once. Request concurrency scales horizontally with the number of API server replicas. Run concurrency is how many runs execute at once. A single queue worker executes up to N_JOBS_PER_WORKER runs concurrently (default 10). Run concurrency is capped at the number of queue workers multiplied by N_JOBS_PER_WORKER.

Read load components and factors

Read load is driven by: getting results of a run, getting state of a thread, searching for runs, threads, cron jobs and assistants, and retrieving checkpoints and long term memory. Components handling read load are: API server (handles request and direct retrieval of data from database), Postgres (handles storage of all data including run, thread, assistant, cron job, checkpointing and long term memory), and Redis (handles storage of ephemeral data about on-going runs including streaming messages from queue workers to api servers).

Write load components and factors

Write load is driven by: creation of new runs, creation of new checkpoints during run execution, writing to long term memory, creation of new threads, creation of new assistants, and deletion of runs, checkpoints, threads, assistants and cron jobs. Components handling write load are: API server (handles initial request and persistence to database), Queue worker (handles execution of runs), Redis (handles storage of ephemeral data about on-going runs), and Postgres (handles storage of all data including run, thread, assistant, cron job, checkpointing and long term memory).

Use /join API to monitor run completion instead of polling

Avoid polling the state of a run by using the /join API endpoint. This method returns the final state of the run once the run is complete. If you need to monitor the output of a run in real-time, use the /stream API endpoint instead, which streams the run output including the final state.

Set TTL on threads for automatic data cleanup

Set a TTL on threads to automatically clean up old data. Runs and checkpoints are automatically deleted when the associated thread is deleted.

Low reads low writes configuration

For low read/write load (approximately 5 read/5 write requests per second), use the default LangSmith Deployment configuration. No custom resource configuration is needed.

Medium reads medium writes example configuration

For medium reads, medium writes (50 read/50 write requests per second): API servers: 3 replicas with 1 CPU and 2Gi memory requests, 2 CPU and 4Gi limits; Queue workers: 5 replicas with 1 CPU and 2Gi memory requests, 2 CPU and 4Gi limits; N_JOBS_PER_WORKER: 10 (default); Redis: 2Gi memory; Postgres: 4 CPU and 16Gi memory requests, 8 CPU and 32Gi limits.

High reads high writes example configuration

For high reads, high writes (500 read/500 write requests per second): API servers: 15 replicas with 1 CPU and 2Gi memory requests, 2 CPU and 4Gi limits; Queue workers: 10 replicas with 1 CPU and 2Gi memory requests, 2 CPU and 4Gi limits; N_JOBS_PER_WORKER: 50; Redis: 2Gi memory; Postgres: 8 CPU and 32Gi memory requests, 16 CPU and 64Gi limits.

Autoscaling configuration for bursty traffic

For bursty traffic, enable autoscaling. Example for high reads and high writes: API servers with autoscaling enabled, minReplicas 15, maxReplicas 25; Queue workers with autoscaling enabled, minReplicas 10, maxReplicas 20.

Enable queue workers in Helm configuration

Enable queue workers by setting queue.enabled to true in the Helm configuration yaml.

Use filtering to reduce read load

Agent Server provides a search API for each resource type. These APIs implement pagination by default and offer many filtering options. Use filtering to reduce the number of resources returned per request and improve read performance.

N_JOBS_PER_WORKER tuning guidelines

The default value of N_JOBS_PER_WORKER is 10. If assistant is CPU bounded, the default value of 10 is likely sufficient; lower N_JOBS_PER_WORKER if excessive CPU usage or delays occur. If assistant is memory bounded or queue workers approach memory limits, lower N_JOBS_PER_WORKER to reduce concurrent runs per worker. If assistant is IO bounded, increase N_JOBS_PER_WORKER to handle more concurrent runs per worker. There is no upper limit to N_JOBS_PER_WORKER. Setting it too high in bursty traffic environments can lead to uneven worker utilization, increased run execution times, and high memory usage.

Production requirements for deployed LangGraph agent

Two production requirements for setting up a deployed LangGraph agent are: a database for persistence (PostgreSQL by default) and a task queue (Redis by default). The database stores core resource data (assistants, threads, runs, cron jobs), checkpoints (short-term memory), and store data (long-term memory). Redis handles signaling, cancellation, and streaming pub/sub between API servers and queue workers.

Give your agent this brain