Provide use cases + assistant id clarifications in LS deployments docs

Author: katmayb

src/langsmith/assistants.mdx

@@ -3,7 +3,7 @@ title: Assistants
 sidebarTitle: Overview
 ---
 
-**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.
+_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](#when-to-use-assistants) 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.
 
@@ -12,27 +12,116 @@ For example, imagine a general-purpose writing agent built on a common graph arc
 The LangGraph API provides several endpoints for creating and managing assistants and their versions. See the [API reference](https://langchain-ai.github.io/langgraph/cloud/reference/api/api_ref/#tag/assistants) for more details.
 
 <Info>
-Assistants are a [LangSmith](/langsmith/home) concept. They are not available in the open source LangGraph library.
+Assistants are a [LangSmith Deployment](/langsmith/deployments) concept. They are not available in the open source LangGraph library.
 </Info>
 
-## Configuration
+## 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.
+
+```mermaid
+graph TD
+    A["Graph: agent<br/>(deployed)"]
+    A --> B["Customer A Assistant<br/>━━━━━━━━━━━━━<br/>Model: GPT-4<br/>Tone: Legal<br/>Tools: Custom"]
+    A --> C["Customer B Assistant<br/>━━━━━━━━━━━━━<br/>Model: Claude<br/>Tone: Casual<br/>Tools: Standard"]
+    A --> D["Customer C Assistant<br/>━━━━━━━━━━━━━<br/>Model: GPT-3.5<br/>Tone: Formal<br/>Tools: Limited"]
+
+    style A fill:#4A90E2,stroke:#2E5C8A,stroke-width:3px,color:#fff
+    style B fill:#E8F4F8,stroke:#4A90E2,stroke-width:2px
+    style C fill:#E8F4F8,stroke:#4A90E2,stroke-width:2px
+    style D fill:#E8F4F8,stroke:#4A90E2,stroke-width:2px
+```
+
+- **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.
+
+```mermaid
+graph TD
+    A["Graph: writing-agent<br/>(deployed)"]
+    A --> B["Blog Assistant<br/>━━━━━━━━━━━━━<br/>Model: GPT-4<br/>Tone: Formal<br/>Style: Long-form<br/>Tools: SEO optimization"]
+    A --> C["Tweet Assistant<br/>━━━━━━━━━━━━━<br/>Model: GPT-4-mini<br/>Tone: Casual<br/>Style: 280-char limit<br/>Tools: Hashtag suggestions"]
+    A --> D["Email Assistant<br/>━━━━━━━━━━━━━<br/>Model: GPT-4<br/>Tone: Professional<br/>Style: Medium length<br/>Tools: Templates"]
+
+    style A fill:#4A90E2,stroke:#2E5C8A,stroke-width:3px,color:#fff
+    style B fill:#E8F4F8,stroke:#4A90E2,stroke-width:2px
+    style C fill:#E8F4F8,stroke:#4A90E2,stroke-width:2px
+    style D fill:#E8F4F8,stroke:#4A90E2,stroke-width:2px
+```
+
+## How assistants work with deployments
+
+When you deploy a graph with LangSmith Deployment, [Agent Server](/langsmith/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](/langsmith/configuration-cloud)**: Create, list, update, version, and select assistants using the Agent Server/LangGraph SDKs or the [LangSmith UI](https://smith.langchain.com).
+- **One graph, multiple assistants**: A single deployed graph can support multiple assistants, each with different configurations (e.g., prompts, models, tools).
+- **[Versioned](#versioning) 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](#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.
+
+<Note>
+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.
+</Note>
+
+### Configuration
 
 Assistants build on the LangGraph open source concept of [configuration](/oss/langgraph/graph-api#runtime-context).
 
-While configuration is available in the open source LangGraph library, assistants are only present in [LangSmith](/langsmith/home). This is due to the fact that assistants 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.
+While configuration is available in the open source LangGraph library, assistants are only present in [LangSmith Deployment](/langsmith/deployments) because they are tightly coupled to your deployed graph. Upon deployment, [Agent Server](/langsmith/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](https://langchain-ai.github.io/langgraph/cloud/reference/api/api_ref/) and [this how-to](/langsmith/configuration-cloud) for more details on how to create assistants.
 
-## Versioning
+### 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.
+
+<Warning>
+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.
+</Warning>
+
+For more details on how to manage assistant versions, refer to the [Manage assistants guide](/langsmith/configuration-cloud#create-a-new-version-for-your-assistant).
 
-Assistants support versioning to track changes over time.
-Once you've created an assistant, subsequent edits to that assistant will create new versions. See [this how-to](/langsmith/configuration-cloud#create-a-new-version-for-your-assistant) for more details on how to manage assistant versions.
+### Execution
 
-## 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).
 
-A **run** is an invocation of an assistant. Each run may have its own input, configuration, and metadata, which may affect execution and output of the underlying graph. A run can optionally be executed on a [thread](/oss/langgraph/persistence#threads).
+- Each run may have its own input, configuration overrides, and metadata.
+- Runs can be stateless (no thread) or stateful (executed on a [thread](/oss/langgraph/persistence#threads) for conversation persistence).
+- Multiple runs can use the same assistant configuration.
+- The assistant's configuration affects how the underlying graph executes.
 
-LangSmith API provides several endpoints for creating and managing runs. See the [API reference](https://langchain-ai.github.io/langgraph/cloud/reference/api/api_ref/) for more details.
+The LangSmith API provides several endpoints for creating and managing runs. For more details, refer to the [API reference](https://langchain-ai.github.io/langgraph/cloud/reference/api/api_ref/).
 
 ## Video guide