Agent Run Action - Overcut.ai

The agent.run action executes a single AI agent to perform a specific, straightforward task within your workflow. It’s designed for simple, non-interactive operations that don’t require iteration or user feedback, making it perfect for preparation steps, analysis tasks, and single-purpose operations.

Overview

The agent.run action is ideal for tasks where you need a single agent to complete a specific job and provide output that can be used by subsequent workflow steps. Unlike agent.session, it doesn’t maintain an ongoing conversation or coordinate multiple agents - it simply runs the specified agent with your instructions and completes the task.

Single Agent Execution

Runs one specific agent with focused instructions for a single task.

Non-Interactive

Completes the task without waiting for user input or maintaining a session.

Fast Execution

Optimized for quick, straightforward tasks that don’t require iteration.

Output Sharing

Provides structured output that can be referenced by subsequent workflow steps.

When to Use Agent Run

Perfect For

Preparation tasks: Analyzing code, generating plans, extracting information
Simple analysis: Code review preparation, dependency analysis, configuration parsing
Data extraction: Parsing logs, extracting metrics, summarizing content
Single-purpose operations: Formatting, validation, transformation tasks
Quick decisions: Simple classification, routing, or decision-making

Not Suitable For

Complex, multi-step tasks that require coordination between multiple agents
Interactive workflows that need user feedback or ongoing conversation
Tasks requiring iteration or multiple rounds of refinement
Multi-agent collaboration where different agents need to work together

Basic Usage

Simple Agent Execution

The most basic usage runs a single agent:

steps:
  - id: "analyze-code"
    name: "Analyze Code"
    action: "agent.run"
    params:
      agentId: "senior-developer"

With Instructions

Provide specific instructions for the agent:

steps:
  - id: "prepare-review"
    name: "Prepare Code Review Plan"
    action: "agent.run"
    params:
      agentId: "senior-developer"
      instruction: "Analyze the code changes and create a structured review plan with priority items"

Using Dynamic Values

Reference values from previous steps or triggers:

steps:
  - id: "analyze-issue"
    name: "Analyze Issue"
    action: "agent.run"
    params:
      agentId: "product-manager"
      instruction: "Analyze the issue '{{trigger.issue.title}}' and provide technical recommendations"

Parameters

Required Parameters

string

required

The unique identifier of the agent to execute. This agent will be responsible for completing the specified task.

string

required

Specific instructions for the agent to follow. This should be clear, actionable guidance for the task at hand.

How It Works

1. Agent Selection

The system loads the specified agent configuration, including:

Selected agent (e.g., Senior Developer, Product Manager)
Available tools and capabilities
Custom instructions and configuration

2. Task Execution

The agent executes the task by:

Processing instructions and understanding the requirements
Using available tools to gather information and perform actions
Generating output based on the task requirements
Completing execution when the task is finished

3. Output Generation

The agent provides structured output that can include:

Text responses with analysis, recommendations, or results
Structured data in JSON format for downstream processing
Tool outputs from any tools used during execution
Status information about task completion

4. Workflow Continuation

The workflow continues to the next step with:

Agent output available for reference
Context preserved for subsequent steps
No ongoing session to maintain

Complete Examples

Code Review Preparation

Prepare a structured review plan for a pull request:

steps:
  - id: "clone-repo"
    name: "Clone Repository"
    action: "git.clone"
    params:
      repoFullName: "{{trigger.repository.fullName}}"
      branch: "{{trigger.pullRequest.headBranch}}"
  
  - id: "prepare-review-plan"
    name: "Prepare Review Plan"
    action: "agent.run"
    params:
      agentId: "senior-developer"
      instruction: "Analyze the code changes and create a numbered list of review items, prioritizing security, performance, and maintainability concerns"
  
  - 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 the review plan: {{outputs.prepare-review-plan}}"

Issue Analysis

Analyze a Jira issue and provide technical context:

steps:
  - id: "analyze-issue"
    name: "Analyze Issue"
    action: "agent.run"
    params:
      agentId: "product-manager"
      instruction: "Analyze the issue '{{trigger.issue.title}}' and provide: 1) Technical complexity assessment, 2) Recommended approach, 3) Potential risks"
  
  - id: "plan-implementation"
    name: "Plan Implementation"
    action: "agent.session"
    params:
      goal: "Create detailed implementation plan based on issue analysis"
      agentIds: ["senior-developer", "architect"]
      instruction: "Use this analysis to create the plan: {{outputs.analyze-issue}}"

Dependency Analysis

Analyze project dependencies and identify updates:

steps:
  - id: "clone-repo"
    name: "Clone Repository"
    action: "git.clone"
    params:
      repoFullName: "{{trigger.repository.fullName}}"
  
  - id: "analyze-dependencies"
    name: "Analyze Dependencies"
    action: "agent.run"
    params:
      agentId: "senior-developer"
      instruction: "Analyze package.json and identify outdated dependencies, security vulnerabilities, and recommended updates"
  
  - id: "create-update-plan"
    name: "Create Update Plan"
    action: "agent.run"
    params:
      agentId: "product-manager"
      instruction: "Based on the dependency analysis, create a prioritized update plan with risk assessment"

Output and Context

Step Output

The agent.run action provides output that can be used by subsequent steps:

string

required

The main output content from the agent, typically containing the task results, analysis, or generated content.

Available Variables

Use these variables in subsequent steps:

{{outputs.analyze-code.message}}: Main output from the agent

Template Examples

Basic Output Reference:

      instruction: "Use this analysis: {{outputs.analyze-code.message}}"

Integration with Other Actions

Following with Multi-Agent Session

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

steps:
  - id: "prepare-plan"
    name: "Prepare Plan"
    action: "agent.run"
    params:
      agentId: "senior-developer"
      instruction: "Create a structured plan for implementing the feature described in the issue"
  
  - id: "execute-implementation"
    name: "Execute Implementation"
    action: "agent.session"
    params:
      goal: "Implement the feature according to the prepared plan"
      agentIds: ["frontend-developer", "backend-developer", "qa-engineer"]
      instruction: "Follow this implementation plan: {{outputs.prepare-plan.message}}"

Data Processing Pipeline

Chain multiple agent.run steps for data processing:

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

Best Practices

1. Keep Instructions Clear and Focused

Single purpose: Each agent.run step should have one clear objective
Specific guidance: Provide detailed, actionable instructions
Expected output: Clarify what format or structure you expect
Context: Include relevant information from previous steps

2. Choose the Right Agent

Match skills: Select agents with appropriate expertise for the task
Consider tools: Ensure the agent has access to necessary tools
Base agent type: Use built-in agent types that match your needs
Custom agents: Leverage specialized agents for domain-specific tasks

3. Optimize for Output Reusability

Structured output: Request output in formats that downstream steps can use
Clear formatting: Ask for numbered lists, JSON, or other structured formats
Key information: Focus on actionable insights and data
Error handling: Consider what happens if the agent fails

4. Position in Workflow

Early steps: Use for preparation and analysis tasks
Data processing: Chain multiple steps for complex data workflows
Input preparation: Prepare data for more complex agent.session steps
Validation: Use for checking and validating workflow state

Next Steps

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

Multi-Agent Session Action: Learn about multi-agent, interactive workflows
Agent Differences: Understand when to use each agent action type
Base Agent Types: Compare base agent types and their default toolsets
Agent Tools Reference: See all available tools and which agents include them
Building Blocks: Explore other workflow actions and components
Execute CI Workflow: Learn how to trigger external CI pipelines directly from Overcut
Quick Starts: See complete workflow examples

Ready to automate simple tasks? Start with agent.run for straightforward operations, then combine it with other actions to build powerful, automated workflows.

​Overview

Single Agent Execution

Non-Interactive

Fast Execution

Output Sharing

​When to Use Agent Run

​Perfect For

​Not Suitable For

​Basic Usage

​Simple Agent Execution

​With Instructions

​Using Dynamic Values

​Parameters

​Required Parameters

​How It Works

​1. Agent Selection

​2. Task Execution

​3. Output Generation

​4. Workflow Continuation

​Complete Examples

​Code Review Preparation

​Issue Analysis

​Dependency Analysis

​Output and Context

​Step Output

​Available Variables

​Template Examples

​Integration with Other Actions

​Following with Multi-Agent Session

​Data Processing Pipeline

​Best Practices

​1. Keep Instructions Clear and Focused

​2. Choose the Right Agent

​3. Optimize for Output Reusability

​4. Position in Workflow

​Next Steps

Overview

When to Use Agent Run

Perfect For

Not Suitable For

Basic Usage

Simple Agent Execution

With Instructions

Using Dynamic Values

Parameters

Required Parameters

How It Works

1. Agent Selection

2. Task Execution

3. Output Generation

4. Workflow Continuation

Complete Examples

Code Review Preparation

Issue Analysis

Dependency Analysis

Output and Context

Step Output

Available Variables

Template Examples

Integration with Other Actions

Following with Multi-Agent Session

Data Processing Pipeline

Best Practices

1. Keep Instructions Clear and Focused

2. Choose the Right Agent

3. Optimize for Output Reusability

4. Position in Workflow

Next Steps