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 thecontext parameter.
Consider this example of a call_model node that reads the model_name from the context:
Create an assistant
- SDK
- UI
Use the Response:The API returns an assistant object containing: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.
model_name set to openai:assistant_id: A UUID that uniquely identifies this assistantgraph_id: The graph this assistant is configured forcontext: The configuration values you providedname,metadata, timestamps, and other fields
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
Use an assistant
- SDK
- UI
To use an assistant, pass its 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,
assistant_id when creating a run. The example below uses the assistant created above:"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.- SDK
- UI
Use the
assistants.update method to create a new version of an assistant.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.- SDK
- UI
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.- SDK
- UI
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.Connect these docs to your agent of choice via MCP for real-time answers.

