Skip to main content
Assistants allow you to manage configurations (like prompts, LLM selection, tools) separately from your graph’s core logic, enabling rapid changes that don’t alter the graph architecture. It is a way to create multiple specialized versions of the same graph architecture, each optimized for different use cases through configuration variations rather than structural changes. For example, imagine a general-purpose writing agent built on a common graph architecture. While the structure remains the same, different writing styles—such as blog posts and tweets—require tailored configurations to optimize performance. To support these variations, you can create multiple assistants (e.g., one for blogs and another for tweets) that share the underlying graph but differ in model selection and system prompt. assistant versions The LangGraph API provides several endpoints for creating and managing assistants and their versions. See the API reference for more details.
Assistants are a LangSmith Deployment concept. They are not available in the open source LangGraph library.

​
When to use assistants

Assistants are ideal when you need to deploy the same graph logic with different configurations. Common use cases include:
  • User-level personalization
    • Customize model selection, system prompts, or tool availability per user.
    • Store user preferences and apply them automatically to each interaction.
    • Enable users to choose between different AI personalities or expertise levels.
  • Customer or organization-specific configurations
    • Maintain separate configurations for different customers or organizations.
    • Customize behavior for each client without deploying separate infrastructure.
    • Isolate configuration changes to specific customers.
  • Environment-specific configurations
    • Use different models or settings for development, staging, and production.
    • Test configuration changes in staging before promoting to production.
    • Reduce costs in non-production environments with smaller models.
  • A/B testing and experimentation
    • Compare different prompts, models, or parameter settings.
    • Roll out configuration changes gradually to a subset of users.
    • Measure performance differences between configuration variants.
  • Specialized task variants
    • Create domain-specific versions of a general-purpose agent.
    • Optimize configurations for different languages, regions, or industries.
    • Maintain consistent graph logic while varying the execution details.

​
How assistants work with deployments

When you deploy a graph with LangSmith Deployment, Agent Server automatically creates a default assistant tied to that graph’s default configuration. You can then create additional assistants for the same graph, each with its own configuration. Assistants have several key features:
  • Managed via API and UI: Create, list, update, version, and select assistants using the Agent Server/LangGraph SDKs or the LangSmith UI.
  • One graph, multiple assistants: A single deployed graph can support multiple assistants, each with different configurations (e.g., prompts, models, tools).
  • Versioned configurations: Each assistant maintains its own configuration history through versioning. Editing an assistant creates a new version, and you can promote or roll back to any version.
  • Configuration updates without graph changes: Update prompts, model selection, and other settings through assistant configurations, enabling rapid iteration without modifying or redeploying your graph code.
When invoking a run, you can specify either:
  • A graph name (e.g., "agent"): Uses the default assistant for that graph
  • An assistant ID (UUID): Uses a specific assistant configuration
This flexibility allows you to quickly test with default settings or precisely control which configuration is used.

​
Configuration

Assistants build on the LangGraph open source concept of configuration. While configuration is available in the open source LangGraph library, assistants are only present in LangSmith Deployment because they are tightly coupled to your deployed graph. Upon deployment, Agent Server will automatically create a default assistant for each graph using the graph’s default configuration settings. In practice, an assistant is just an instance of a graph with a specific configuration. Therefore, multiple assistants can reference the same graph but can contain different configurations (e.g. prompts, models, tools). The LangSmith Deployment API provides several endpoints for creating and managing assistants. See the API reference and this how-to for more details on how to create assistants.

​
Versioning

Assistants support versioning to track changes over time. Once you’ve created an assistant, subsequent edits will automatically create new versions.
  • Each update creates a new version of the assistant.
  • You can promote any version to be the active version.
  • Rolling back to a previous version is as simple as setting it as active.
  • All versions remain available for reference and rollback.
When updating an assistant, you must provide the entire configuration payload. The update endpoint creates new versions from scratch and does not merge with previous versions. Make sure to include all configuration fields you want to retain.
For more details on how to manage assistant versions, refer to the Manage assistants guide.

​
Execution

A run is an invocation of an assistant. When you execute a run, you specify which assistant to use (either by graph name for the default assistant or by assistant ID for a specific configuration). This diagram shows how a run combines an assistant with a thread to execute the graph:
  • Graph (blue): The deployed code containing your agent’s logic
  • Assistants (light blue): Configuration options (model, prompts, tools)
  • Threads (orange): State containers for conversation history
  • Runs (green): Executions that pair an assistant + thread
Example combinations:
  • Run: A1 + T1: Assistant 1 configuration applied to User A’s conversation
  • Run: A1 + T2: Same assistant serving User B (different conversation)
  • Run: A2 + T1: Different assistant applied to User A’s conversation (configuration switch)
When executing a run:
  • Each run may have its own input, configuration overrides, and metadata.
  • Runs can be stateless (no thread) or stateful (executed on a thread for conversation persistence).
  • Multiple runs can use the same assistant configuration.
  • The assistant’s configuration affects how the underlying graph executes.
The LangSmith API provides several endpoints for creating and managing runs. For more details, refer to the API reference.

​
Video guide

Edit the source of this page on GitHub.
Connect these docs programmatically to Claude, VSCode, and more via MCP for real-time answers.