> ## Documentation Index
> Fetch the complete documentation index at: https://docs.overcut.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Agent Run vs Multi-Agent Session

> Understand the key differences between agent.run and agent.session actions to choose the right approach for your workflow needs.

Understanding the differences between `agent.run` and `agent.session` is crucial for designing effective Overcut workflows. Each action type serves different purposes and has distinct characteristics that make them suitable for specific scenarios.

***

## Overview

Overcut provides two distinct agent action types that serve different workflow needs:

* **`agent.run`**: Single-agent execution for straightforward, non-interactive tasks
* **`agent.session`**: Multi-agent coordination for complex, interactive workflows

The choice between them depends on your task complexity, need for coordination, and whether you require ongoing interaction or iteration.

<CardGroup cols={2}>
  <Card title="Agent Run" icon="play">
    Single agent, focused execution, quick completion
  </Card>

  <Card title="Multi-Agent Session" icon="users">
    Multiple agents, coordination, ongoing interaction
  </Card>
</CardGroup>

***

## Key Differences

### **Execution Model**

#### Agent Run

* **Single agent execution**: One specific agent handles the entire task
* **Direct execution**: Agent works independently without coordination
* **Linear workflow**: Task is completed in a single pass
* **Background operation**: No ongoing conversation or user interaction

#### Multi-Agent Session

* **Multi-agent coordination**: Multiple agents work together under a coordinator
* **Coordinated execution**: Coordinator agent orchestrates the workflow
* **Iterative process**: Tasks can be refined and repeated
* **Interactive session**: Maintains ongoing conversation and user feedback

### **Agent Behavior**

#### Agent Run

* **Works independently** without delegation capabilities
* **Executes tools directly** to complete the assigned task
* **Reports completion** when the task is finished
* **Cannot coordinate** with other agents
* **Operates in background** without user interaction

#### Multi-Agent Session

* **Breaks down complex tasks** into smaller, manageable pieces
* **Delegates subtasks** to specialized agents
* **Reviews results** and provides feedback to agents
* **Manages iteration** and refinement cycles
* **Communicates progress** to users throughout the process

### **Task Complexity**

#### Agent Run

* **Simple, focused tasks**: Single objective with clear requirements
* **No iteration needed**: Task can be completed in one attempt
* **Independent execution**: No coordination between different aspects
* **Quick completion**: Designed for fast, straightforward operations

#### Multi-Agent Session

* **Complex, multi-faceted tasks**: Multiple objectives requiring different expertise
* **Iteration and refinement**: Plans can be adjusted based on results
* **Coordinated execution**: Different agents handle different aspects
* **Extended duration**: Designed for longer, more complex workflows

***

## When to Use Each Action

### **Choose Agent Run When**

* **Task is straightforward** and can be completed by one agent
* **No coordination needed** between different areas of expertise
* **Quick execution** is required without ongoing interaction
* **Single output** is needed for downstream workflow steps
* **Preparation tasks** that provide input for more complex workflows

**Examples:**

* Code analysis and preparation
* Data extraction and parsing
* Simple validation tasks
* Generating plans or summaries
* Single-purpose operations

### **Choose Multi-Agent Session When**

* **Task requires multiple perspectives** or areas of expertise
* **Coordination is essential** between different aspects
* **Iteration and refinement** are needed
* **User interaction** would be beneficial
* **Complex problem-solving** that benefits from collaboration

**Examples:**

* Comprehensive code reviews
* Architecture design and planning
* Multi-repository analysis
* Incident investigation and resolution
* Feature implementation planning

***

## Workflow Design Patterns

### **Pattern 1: Preparation → Execution**

Use `agent.run` to prepare input for complex `agent.session` workflows:

```yaml theme={null}
steps:
  - id: "prepare-analysis"
    name: "Prepare Analysis"
    action: "agent.run"
    params:
      agentId: "senior-developer"
      instruction: "Analyze the code changes and create a structured review plan"
  
  - id: "execute-review"
    name: "Execute Code Review"
    action: "agent.session"
    params:
      goal: "Perform comprehensive code review based on the prepared plan"
      agentIds: ["code-reviewer", "security-expert"]
      instruction: "Follow this review plan: {{outputs.prepare-analysis.message}}"
```

### **Pattern 2: Multi-Stage Processing**

Chain multiple `agent.run` steps for data processing pipelines:

```yaml theme={null}
steps:
  - id: "extract-data"
    name: "Extract Data"
    action: "agent.run"
    params:
      agentId: "data-analyst"
      instruction: "Extract key metrics from the repository analysis"
  
  - id: "analyze-trends"
    name: "Analyze Trends"
    action: "agent.run"
    params:
      agentId: "data-scientist"
      instruction: "Analyze trends in the extracted data: {{outputs.extract-data.message}}"
  
  - id: "generate-report"
    name: "Generate Report"
    action: "agent.run"
    params:
      agentId: "technical-writer"
      instruction: "Create a comprehensive report based on the trend analysis: {{outputs.analyze-trends.message}}"
```

### **Pattern 3: Complex Coordination**

Use `agent.session` for tasks requiring multiple perspectives:

```yaml theme={null}
steps:
  - id: "architecture-design"
    name: "Architecture Design Session"
    action: "agent.session"
    params:
      goal: "Design the system architecture for the new microservices platform"
      agentIds: ["architect", "senior-developer", "security-expert", "devops-engineer"]
      exitCriteria:
        timeLimit:
          maxDurationMinutes: 120
        userSignals:
          explicit: ["/design-complete", "/architecture-ready"]
```

***

## Performance and Resource Considerations

### **Agent Run**

**Advantages:**

* **Faster execution**: Single agent, no coordination overhead
* **Lower resource usage**: No session management or ongoing conversation
* **Predictable timing**: Linear execution with known completion time
* **Easier debugging**: Single execution path to trace

**Limitations:**

* **Single perspective**: Limited to one agent's expertise
* **No iteration**: Cannot refine approach based on results
* **Limited complexity**: Not suitable for multi-faceted tasks

### **Multi-Agent Session**

**Advantages:**

* **Multiple perspectives**: Leverages different areas of expertise
* **Iterative improvement**: Can refine and adjust approach
* **User interaction**: Supports ongoing feedback and guidance
* **Complex problem-solving**: Handles multi-faceted challenges

**Limitations:**

* **Longer execution time**: Coordination and iteration add overhead
* **Higher resource usage**: Session management and ongoing conversation
* **Complex debugging**: Multiple execution paths and agent interactions
* **Potential for coordination issues**: Depends on coordinator effectiveness

***

## Decision Framework

### **Step-by-Step Decision Process**

1. **Assess Task Complexity**
   * Is this a single, focused task?
   * Does it require multiple areas of expertise?
   * Is coordination between different aspects needed?

2. **Consider Iteration Needs**
   * Can the task be completed in one attempt?
   * Would refinement and adjustment be beneficial?
   * Is ongoing user feedback valuable?

3. **Evaluate Resource Constraints**
   * What's the acceptable execution time?
   * Are there resource limitations?
   * What's the priority of the task?

4. **Determine User Interaction**
   * Is ongoing user guidance needed?
   * Would real-time feedback improve results?
   * Is this a collaborative or autonomous task?

***

## Best Practices

### **For Agent Run**

1. **Keep tasks focused**: Single objective with clear requirements
2. **Provide clear instructions**: Detailed, actionable guidance
3. **Choose appropriate agents**: Match agent skills to task requirements
4. **Optimize output**: Structure output for downstream consumption
5. **Handle errors gracefully**: Plan for potential failures

### **For Multi-Agent Session**

1. **Define clear goals**: Specific, measurable objectives
2. **Choose complementary agents**: Diverse expertise without overlap
3. **Set appropriate exit criteria**: Time limits and user signals
4. **Enable user interaction**: Use comment listening and session persistence
5. **Monitor coordination**: Ensure effective delegation and feedback

***

## Next Steps

Now that you understand the differences between `agent.run` and `agent.session`, explore these related topics:

* **[Agent Run Action](/docs/workflows/agent-run)**: Learn about single-agent execution
* **[Multi-Agent Session Action](/docs/workflows/agent-session)**: Learn about multi-agent coordination
* **[Building Blocks](/docs/building-blocks)**: Explore other workflow actions and components
* **[Quick Starts](/docs/quick-starts)**: See complete workflow examples

Ready to design your workflows? Start with `agent.run` for simple tasks, then evolve to `agent.session` when you need coordination and collaboration. The key is matching the action type to your specific requirements and constraints.