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.

Agent Run

Single agent, focused execution, quick completion

Agent Session

Multiple agents, coordination, ongoing interaction

​
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

​
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

​
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

​
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 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: 
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: 
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: 
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

​
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 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: 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.