Runs ↗

Documentation Index#

Fetch the complete documentation index at: https://docs.langchain.com/llms.txt Use this file to discover all available pages before exploring further.

An overview of runs in Agent Server, including how to kick off background runs, stateless runs, and cancel runs.

A run is an invocation of an assistant. When you execute a run, you specify which assistant to use—either by graph ID for the default assistant, or by assistant ID for a specific configuration.

flowchart TB
    subgraph deploy[Deployment]
        G[Graph Code<br/>━━━━━━━━━<br/>Deployed logic]
    end

    subgraph config[Configuration]
        A1[Assistant 1<br/>GPT-4, Formal]
        A2[Assistant 2<br/>Claude, Casual]
    end

    subgraph state[State]
        T1[Thread 1<br/>User A]
        T2[Thread 2<br/>User B]
    end

    subgraph runs[Runs]
        A1T1["Run: A1 + T1"]
        A1T2["Run: A1 + T2"]
        A2T1["Run: A2 + T1"]
    end

    A1 -.-> T1
    A1 -.-> T2
    A2 -.-> T1

    A1T1 --> G
    A1T2 --> G
    A2T1 --> G

    style G fill:#DBEAFE,stroke:#2563EB,stroke-width:2px,color:#1E3A8A
    style A1 fill:#B3E0F2,stroke:#4A90E2,stroke-width:2px,color:#1E3A5F
    style A2 fill:#B3E0F2,stroke:#4A90E2,stroke-width:2px,color:#1E3A5F
    style T1 fill:#FFE0B3,stroke:#F59E0B,stroke-width:2px,color:#78350F
    style T2 fill:#FFE0B3,stroke:#F59E0B,stroke-width:2px,color:#78350F
    style A1T1 fill:#B3F2C9,stroke:#10B981,stroke-width:2px,color:#14532D
    style A1T2 fill:#B3F2C9,stroke:#10B981,stroke-width:2px,color:#14532D
    style A2T1 fill:#B3F2C9,stroke:#10B981,stroke-width:2px,color:#14532D

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 Agent Server API provides several endpoints for creating and managing runs. For more details, refer to the API reference.

In this section#

Run your agent asynchronously and poll for results.

Use multiple assistants on a shared thread to combine agent capabilities.

Execute runs without persisting state when conversation history isn’t needed.

Cancel a single run or multiple runs via the API.

Edit this page on GitHub or file an issue.

Connect these docs to Claude, VSCode, and more via MCP for real-time answers.