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.

Multi-Agent Coordination

Multiple agents work together with a coordinator orchestrating the workflow.

Interactive Sessions

Maintains ongoing conversation with options for user feedback and iteration.

Complex Task Handling

Breaks down complex problems into smaller, manageable chunks.

Flexible Execution

Supports iteration, refinement, and adaptive problem-solving approaches.

​
When to Use 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: 
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: 
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: 
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

​
goal
string
required
The main objective or goal for the session. This should clearly describe what the agents are trying to accomplish together.
​
agentIds
array
required
Array of agent IDs that will participate in the session. These agents will collaborate under the coordination of a coordinator agent.
​
instruction
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.

​
Optional Parameters

​
exitCriteria.timeLimit.maxDurationMinutes
number
Maximum session duration in minutes. Default: 10 minutes.
​
exitCriteria.userSignals.explicit
array
Array of explicit user commands that will complete the session (e.g., [“/done”, “/complete”, “thanks”]).
​
listenToComments
boolean
Whether the session should listen for and respond to user comments. Default: true.
​
keepSessionOpenForComments
boolean
Whether to keep the session open for comments after completion. Default: false.

​
Exit Criteria Configuration

​
Time Limits

Set maximum session duration: 
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. 
exitCriteria:
  userSignals:
    explicit: ["/done", "/complete", "thanks", "good job"]

​
Combined Criteria

Use both time and user signals: 
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: 
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: 
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: 
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: 
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: 
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: Ready to create collaborative workflows? Start with agent.session for complex, multi-agent tasks that require coordination, iteration, and user interaction.