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

> Learn how to use the agent.run action to execute single AI agents for straightforward, non-interactive tasks in your Overcut workflows.

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.

<CardGroup cols={2}>
  <Card title="Single Agent Execution" icon="user">
    Runs one specific agent with focused instructions for a single task.
  </Card>

  <Card title="Non-Interactive" icon="circle-check">
    Completes the task without waiting for user input or maintaining a session.
  </Card>

  <Card title="Fast Execution" icon="bolt-lightning">
    Optimized for quick, straightforward tasks that don't require iteration.
  </Card>

  <Card title="Output Sharing" icon="share">
    Provides structured output that can be referenced by subsequent workflow steps.
  </Card>
</CardGroup>

***

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

```yaml theme={null}
steps:
  - id: "analyze-code"
    name: "Analyze Code"
    action: "agent.run"
    params:
      agentId: "senior-developer"
```

### With Instructions

Provide specific instructions for the agent:

```yaml theme={null}
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:

```yaml theme={null}
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

<ParamField path="agentId" type="string" required>
  The unique identifier of the agent to execute. This agent will be responsible for completing the specified task.
</ParamField>

<ParamField path="instruction" type="string" required>
  Specific instructions for the agent to follow. This should be clear, actionable guidance for the task at hand.
</ParamField>

***

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

```yaml theme={null}
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:

```yaml theme={null}
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:

```yaml theme={null}
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:

<ResponseField name="message" type="string" required>
  The main output content from the agent, typically containing the task results, analysis, or generated content.
</ResponseField>

### Available Variables

Use these variables in subsequent steps:

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

### Template Examples

**Basic Output Reference:**

```yaml theme={null}
      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:

```yaml theme={null}
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:

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

***

## 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](/docs/workflows/agent-session)**: Learn about multi-agent, interactive workflows
* **[Agent Differences](/docs/workflows/agent-differences)**: Understand when to use each agent action type
* **[Base Agent Types](/docs/reference/base-agents)**: Compare base agent types and their default toolsets
* **[Agent Tools Reference](/docs/reference/tools)**: See all available tools and which agents include them
* **[Building Blocks](/docs/building-blocks)**: Explore other workflow actions and components
* **[Execute CI Workflow](/docs/workflows/ci-execute-workflow)**: Learn how to trigger external CI pipelines directly from Overcut
* **[Quick Starts](/docs/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.