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

​
agentId
string
required
The unique identifier of the agent to execute. This agent will be responsible for completing the specified task.
​
instruction
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:
​
message
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 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: Ready to automate simple tasks? Start with agent.run for straightforward operations, then combine it with other actions to build powerful, automated workflows.