> ## 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.

# Multi-Agent Session Action

> Learn how to use the agent.session action to create interactive, multi-agent workflows with coordination, iteration, and user feedback capabilities.

The `agent.session` action creates an interactive, multi-agent session where multiple AI agents collaborate to achieve complex goals. It features a coordinator agent that orchestrates the work, delegates tasks to specialized agents, and maintains an ongoing conversation that can include user feedback and iteration.

***

## Overview

The `agent.session` action is designed for complex, multi-step tasks that require coordination between different agents, iteration, and ongoing user interaction. Unlike `agent.run`, it maintains an active session where agents can work together, break down complex problems, and adapt their approach based on feedback and results.

<CardGroup cols={2}>
  <Card title="Multi-Agent Coordination" icon="users">
    Multiple agents work together with a coordinator orchestrating the workflow.
  </Card>

  <Card title="Interactive Sessions" icon="comments">
    Maintains ongoing conversation with options for user feedback and iteration.
  </Card>

  <Card title="Complex Task Handling" icon="puzzle">
    Breaks down complex problems into smaller, manageable chunks.
  </Card>

  <Card title="Flexible Execution" icon="arrows-rotate">
    Supports iteration, refinement, and adaptive problem-solving approaches.
  </Card>
</CardGroup>

***

## When to Use Multi-Agent Session

### **Perfect For**

* **Complex, multi-step tasks** that require different types of expertise
* **Interactive workflows** that benefit from user feedback and iteration
* **Collaborative problem-solving** where multiple agents need to work together
* **Tasks requiring coordination** between different aspects (frontend, backend, testing)
* **Iterative development** where plans need to be refined based on results

### **Not Suitable For**

* **Simple, single-purpose tasks** that can be completed by one agent
* **Quick, straightforward operations** that don't require coordination
* **Tasks with clear, linear execution** paths

***

## Basic Usage

### Simple Multi-Agent Session

The most basic usage creates a session with multiple agents:

```yaml theme={null}
steps:
  - id: "collaborative-task"
    name: "Collaborative Task"
    action: "agent.session"
    params:
      goal: "Complete the specified task using multiple agents"
      agentIds: ["senior-developer", "product-manager"]
```

### With Exit Criteria

Define when the session should complete:

```yaml theme={null}
steps:
  - id: "code-review-session"
    name: "Code Review Session"
    action: "agent.session"
    params:
      goal: "Perform comprehensive code review"
      agentIds: ["code-reviewer", "security-expert", "performance-expert"]
      exitCriteria:
        timeLimit:
          maxDurationMinutes: 30
        userSignals:
          explicit: ["/done", "review-complete"]
```

### With Session Management Options

Control session behavior and user interaction:

```yaml theme={null}
steps:
  - id: "feature-planning"
    name: "Feature Planning Session"
    action: "agent.session"
    params:
      goal: "Plan and design the new feature implementation"
      agentIds: ["product-manager", "senior-developer", "architect"]
      keepSessionOpenForComments: true
      listenToComments: true
```

***

## Parameters

### Required Parameters

<ParamField path="goal" type="string" required>
  The main objective or goal for the session. This should clearly describe what the agents are trying to accomplish together.
</ParamField>

<ParamField path="agentIds" type="array" required>
  Array of agent IDs that will participate in the session. These agents will collaborate under the coordination of a coordinator agent.
</ParamField>

<ParamField path="instruction" type="string" required>
  Specific instructions for the coordinator agent to follow. This can include instructions on how to break down the goal into smaller tasks, how to delegate tasks to the other agents, how to handle user comments, and how to handle the session overall.
</ParamField>

### Optional Parameters

<ParamField path="exitCriteria.timeLimit.maxDurationMinutes" type="number" required={false}>
  Maximum session duration in minutes. Default: 10 minutes.
</ParamField>

<ParamField path="exitCriteria.userSignals.explicit" type="array" required={false}>
  Array of explicit user commands that will complete the session (e.g., \["/done", "/complete", "thanks"]).
</ParamField>

<ParamField path="listenToComments" type="boolean" required={false}>
  Whether the session should listen for and respond to user comments. Default: true.
</ParamField>

<ParamField path="keepSessionOpenForComments" type="boolean" required={false}>
  Whether to keep the session open for comments after completion. Default: false.
</ParamField>

***

## Exit Criteria Configuration

### Time Limits

Set maximum session duration:

```yaml theme={null}
exitCriteria:
  timeLimit:
    maxDurationMinutes: 45  # Session will complete after 45 minutes
```

### User Signals

Define explicit commands that complete the session.
These commands can be added to a comment on the issue or PR, to   signal to the coordinator agent that the session is complete, or to complete the session.

```yaml theme={null}
exitCriteria:
  userSignals:
    explicit: ["/done", "/complete", "thanks", "good job"]
```

### Combined Criteria

Use both time and user signals:

```yaml theme={null}
exitCriteria:
  timeLimit:
    maxDurationMinutes: 60
  userSignals:
    explicit: ["/done", "/finish", "complete"]
```

***

## How It Works

### 1. Session Initialization

The system creates a multi-agent session with:

* **Coordinator agent** that manages the overall workflow
* **Specialized agents** with different skills and expertise
* **Session context** that maintains state and conversation history

### 2. Goal Analysis and Planning

The coordinator agent:

* **Analyzes the goal** and breaks it down into manageable tasks
* **Identifies which agents** are best suited for each task
* **Creates an execution plan** with clear steps and dependencies

### 3. Task Delegation and Execution

The coordinator:

* **Delegates specific tasks** to appropriate agents
* **Manages task dependencies** and execution order
* **Coordinates results** between different agents
* **Handles task failures** and retries

### 4. Iteration and Refinement

The session supports:

* **Iterative execution** where plans are refined based on results
* **User feedback** that can influence the approach
* **Adaptive problem-solving** that adjusts to new information

### 5. Session Completion

The session completes when:

* **All tasks are finished** and the goal is achieved
* **Time limit is reached** (if configured)
* **User signals completion** (if configured)
* **Exit criteria are met**

***

## Complete Examples

### Code Review Workflow

Multi-agent code review with different expertise areas:

```yaml theme={null}
steps:
  - id: "clone-repo"
    name: "Clone Repository"
    action: "git.clone"
    params:
      repoFullName: "{{trigger.repository.fullName}}"
      branch: "{{trigger.pullRequest.headBranch}}"
  
  - id: "code-review-session"
    name: "Code Review Session"
    action: "agent.session"
    params:
      goal: "Perform comprehensive code review covering security, performance, maintainability, and testing"
      agentIds: ["code-reviewer", "security-expert", "performance-expert", "qa-engineer"]
      exitCriteria:
        timeLimit:
          maxDurationMinutes: 45
        userSignals:
          explicit: ["/done", "review-complete", "thanks"]
      keepSessionOpenForComments: true
      listenToComments: true
```

### Feature Implementation Planning

Collaborative feature planning across multiple domains:

```yaml theme={null}
steps:
  - id: "feature-planning-session"
    name: "Feature Planning Session"
    action: "agent.session"
    params:
      goal: "Plan and design the new user authentication feature, including frontend, backend, database, and security considerations"
      agentIds: ["product-manager", "frontend-developer", "backend-developer", "security-expert", "database-architect"]
      exitCriteria:
        timeLimit:
          maxDurationMinutes: 90
        userSignals:
          explicit: ["/complete", "plan-ready", "done"]
      keepSessionOpenForComments: true
      listenToComments: true
```

### Bug Investigation and Resolution

Multi-agent bug investigation with different perspectives:

```yaml theme={null}
steps:
  - id: "bug-investigation"
    name: "Bug Investigation Session"
    action: "agent.session"
    params:
      goal: "Investigate the reported bug, identify root cause, and create a comprehensive fix plan"
      agentIds: ["debugging-expert", "frontend-developer", "backend-developer", "qa-engineer", "senior-developer"]
      exitCriteria:
        timeLimit:
          maxDurationMinutes: 60
        userSignals:
          explicit: ["/resolved", "investigation-complete", "fix-ready"]
```

## Integration with Other Actions

### Following Repository Identification

Use `repo.identify` to determine which repositories to work with:

```yaml theme={null}
steps:
  - id: "identify-repos"
    name: "Identify Repositories"
    action: "repo.identify"
    params:
      maxResults: 3
      minConfidence: 0.7
  
  - id: "multi-repo-analysis"
    name: "Multi-Repository Analysis"
    action: "agent.session"
    params:
      goal: "Analyze the identified repositories for cross-dependencies and integration points"
      agentIds: ["architect", "senior-developer", "devops-engineer"]
      instruction: "Focus on repositories: {{outputs.identify-repos.[0].repoFullName}}, {{outputs.identify-repos.[1].repoFullName}}"
```

### Preparation with Agent Run

Use `agent.run` to prepare input for complex sessions:

```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}}"
```

***

## Best Practices

### 1. Choose the Right Agent Mix

* **Diverse expertise**: Include agents with different skills and perspectives
* **Role clarity**: Ensure each agent has a clear, distinct role
* **Complementary skills**: Agents should work together, not duplicate each other
* **Specialized knowledge**: Use domain-specific agents for technical areas

### 2. Define Clear Goals

* **Specific objectives**: Make goals concrete and measurable
* **Scope boundaries**: Define what's included and what's not
* **Success criteria**: Clarify how you'll know when the goal is achieved
* **Context information**: Provide relevant background and constraints

### 3. Configure Appropriate Exit Criteria

* **Time limits**: Set realistic timeframes for complex tasks
* **User signals**: Define clear commands for manual completion
* **Progress indicators**: Consider how to track completion progress
* **Fallback mechanisms**: Plan for unexpected completion scenarios

### 4. Optimize Session Management

* **User interaction**: Enable comment listening for better collaboration
* **Session persistence**: Use keepSessionOpenForComments for post-completion feedback
* **Iteration support**: Allow for refinement and improvement cycles
* **Error handling**: Plan for agent failures and session recovery

***

## Next Steps

Now that you understand the `agent.session` action, explore these related topics:

* **[Interactive Sessions Reference](/docs/reference/interactive-sessions)**: Deep dive into session behavior, comment routing, and configuration options
* **[Agent Run Action](/docs/workflows/agent-run)**: Learn about single-agent, non-interactive execution
* **[Agent Differences](/docs/workflows/agent-differences)**: Understand when to use each agent action type
* **[Building Blocks](/docs/building-blocks)**: Explore other workflow actions and components
* **[Execute CI Workflow](/docs/workflows/ci-execute-workflow)**: Trigger external CI jobs as part of multi-agent sessions
* **[Quick Starts](/docs/quick-starts)**: See complete workflow examples

Ready to create collaborative workflows? Start with `agent.session` for complex, multi-agent tasks that require coordination, iteration, and user interaction.