Skip to main content
This page describes how to create, configure, and manage assistants. Assistants allow you to customize your deployed graph’s behavior through configuration—such as model selection, prompts, and tool availability—without changing the underlying graph code. You can work with the SDK or in the LangSmith UI.

Understand assistant configuration

Assistants store context values that customize graph behavior at runtime. You define a context schema in your graph code, then provide specific context values when creating an assistant via the context parameter. Consider this example of a call_model node that reads the model_name from the context:
When you create an assistant, you provide specific values for these configuration fields. The assistant stores this configuration and applies it whenever the graph runs. For more information on configuration in LangGraph, refer to the runtime context documentation.

Create an assistant

Use the assistants.create method to create a new assistant. This method requires:
  • Graph ID: The name of the deployed graph this assistant will use (e.g., "agent").
  • Context: Configuration values matching your graph’s context schema.
  • Name: A descriptive name for the assistant.
The following example creates an assistant with model_name set to openai:
Response:The API returns an assistant object containing:
  • assistant_id: A UUID that uniquely identifies this assistant
  • graph_id: The graph this assistant is configured for
  • context: The configuration values you provided
  • name, metadata, timestamps, and other fields
The assistant_id (a UUID like "62e209ca-9154-432a-b9e9-2d75c7a9219b") uniquely identifies this assistant configuration. You’ll use this ID when running your graph to specify which configuration to apply.
Graph ID vs Assistant IDWhen creating an assistant, you specify a graph ID (graph name like "agent"). This returns an assistant ID (UUID like "62e209ca..."). You can use either when running your graph:
  • Graph ID (e.g., "agent"): Uses the default assistant for that graph
  • Assistant ID (UUID): Uses the specific assistant configuration
See Use an assistant.

Use an assistant

To use an assistant, pass its assistant_id when creating a run. The example below uses the assistant created above:
Response:The stream returns events as the graph executes with your assistant’s configuration:
To run the graph with its default assistant instead, pass the graph ID (for example, "agent") in place of the assistant ID.

Create a new version for your assistant

Updating an assistant creates a new version and sets it as the active version. All future runs that use the assistant ID use the new configuration.
Use the assistants.update method to create a new version of an assistant.
Updates require full configurationYou must provide the entire configuration when updating. The update endpoint creates new versions from scratch and does not merge with previous versions. Include all configuration fields you want to retain.
For example, to add a system prompt to the assistant:

Use a previous assistant version

You can set an earlier version of an assistant as active. All future runs that use the assistant ID then use that version’s configuration.
Use the setLatest method to change which version is active:

Delete an assistant

Deleting an assistant permanently removes it and all of its versions. You cannot delete a single version. To stop using a version, set a different version as active. It also deletes the assistant’s cron jobs and interrupts any of its runs that are in progress. The deployment keeps running. To stop it, delete the deployment.
Use the assistants.delete method to delete an assistant by its UUID. To also delete its threads, set delete_threads (Python) or deleteThreads (JavaScript) to true. This deletes every thread whose metadata assistant_id matches the assistant, along with the runs and checkpoints in those threads:
delete_threads defaults to false. If your deployment uses custom authorization, it deletes only the threads the caller is authorized to access.