Agent Task Automation - Elementum Documentation

The Run Agent Task automation action lets you transition between structured, deterministic automation steps and autonomous agent actions within a single workflow. This combines the reliability of automations with the adaptability of AI agents.

New to Automations? Check out the Automation System guide first to understand how event-driven workflows work in Elementum.

How It Works

Traditional automation excels at structured, deterministic processes: “When X happens, do Y.” AI agents excel at unstructured tasks requiring reasoning, judgment, and problem-solving. Run Agent Task combines both approaches in a single workflow:

Start with structured automation (trigger detection, data gathering)
Hand off to an autonomous agent (analysis, research, decision-making)
Return to structured automation (use agent output in subsequent actions)

Record Updated (structured) →
  Run Agent Task (autonomous intelligence) →
  Update Record Fields (structured) →
  Send Email Notification (structured)

Pure Automation
Pure Agent
Hybrid (Run Agent Task)

Excellent at deterministic tasks
Struggles with tasks requiring judgment
Can’t handle “figure it out” scenarios
Limited to predefined logic paths

Configure a Run Agent Task

To add a Run Agent Task to your workflow, open your

App, click Automations, and add the Run Agent Task action to an automation that already includes a trigger.

Action Name

Provide a descriptive name for the task within your automation workflow.

"Research Customer Industry"
"Evaluate Contract Risk"
"Analyze Support Ticket Complexity"

Object Selection

After naming the action, choose the Object the agent has access to. This determines which data the agent can read and act on when executing the task.

Agent Selection

Select an agent you’ve already built to execute this task. For more on creating and configuring agents, see Agent tools, deployment, and integrations. After selecting the agent, click Configure Task and Test to proceed to the task definition.

Task Definition

The task definition tells the agent what to accomplish. It has three critical components: context, objective, and success criteria. Because agents in Run Agent Task operate in a headless environment — with no user available for follow-up questions — your task definition must be self-contained with all necessary context provided upfront through value references.

Structure
Good vs. Bad Examples
Tips for Headless Tasks

Every task definition should include:

Context — All relevant data via value references
Objective — What the agent should accomplish
Success criteria — How the agent knows it has completed the task, including specific deliverables and format

Task: "Analyze the support ticket from {{customer.name}} regarding {{ticket.subject}}.
Customer tier: {{customer.tier}}, previous tickets: {{customer.past_tickets}}.

Objective: Determine issue complexity and routing.

Success: Provide:
- Complexity rating (Low/Medium/High)
- Estimated resolution time in hours
- Recommended team (General/Specialist/Engineering)
- 2-3 sentence reasoning for recommendations"

Vague task (bad):

Task: "Research this customer"

Complete task (good):

Task: "Research {{customer.company}} (industry: {{customer.industry}},
size: {{customer.employees}} employees, location: {{customer.location}}).
Focus on their competitive landscape, recent news, and decision-making structure.
Use our product category ({{product.category}}) to identify relevant talking points."

Vague success criteria (bad):

Task: "Analyze this contract and let me know what you think"

Clear success criteria (good):

Task: "Analyze this contract for {{customer.name}}.
Success criteria:
- Identify any terms that deviate from our standard template
- Rate overall risk as Low/Medium/High
- Flag any must-negotiate items
- Provide recommended approval authority based on risk and value"

Since agents can’t ask clarifying questions, provide everything they need upfront:

Use value references extensively — Include all relevant record fields, related data, and historical context
Include business context — Customer segment, strategic importance, revenue impact, relationship tenure
Anticipate agent needs — Think about what an informed human would need: business rules, comparative data, success thresholds, constraints
Be specific but not restrictive — Give clear direction while allowing intelligent interpretation

Task: "Evaluate support ticket #{{ticket.id}} from {{customer.name}}.
Customer details:
- Tier: {{customer.tier}}
- Account age: {{customer.age_days}} days
- Lifetime value: ${{customer.lifetime_value}}
- Previous tickets: {{customer.ticket_count}}

Ticket details:
- Subject: {{ticket.subject}}
- Description: {{ticket.description}}
- Reported by: {{ticket.reporter_name}} ({{ticket.reporter_role}})

Success: Determine urgency (Critical/High/Medium/Low), estimated effort
(hours), recommended team, and whether customer success should be notified."

Output Type

Choose how the agent returns its work:

Text Output
Structured Output
Field Design Tips

Returns a simple narrative response. Best for summaries, explanations, and recommendations where you don’t need to branch on specific values in downstream actions.

Define specific fields with types, similar to AI File Reader. The agent returns data in exactly the structure you define, which you can reference directly in subsequent automation steps.Defining fields:

Field Name — Variable name for use in subsequent actions
Field Type — text, number, checkbox, date, list, etc.
Description (optional but recommended) — Helps the agent understand what you want

Example configuration:

Fields:
risk_score (number): Overall risk rating from 1-10
risk_level (text): Low/Medium/High categorization
key_risks (list): Specific risk factors identified
mitigation_required (checkbox): Whether mitigation actions are needed
reasoning (text): 2-3 sentence explanation of assessment

Using output in subsequent actions:Once the agent task completes, its output becomes available as value references:

IF run_agent_task.risk_level = "High" OR run_agent_task.mitigation_required = true
  → Start Approval Process (Legal team)
  → Send Message to Teams: "High-risk contract: {{run_agent_task.reasoning}}"
OTHERWISE
  → Update Record Fields (auto-approved)
  → Send Email Notification: "Contract approved: {{run_agent_task.reasoning}}"

Design output fields to match how you’ll use them downstream:

For routing logic — Use categorical fields like risk_level (Low/Medium/High) that work well in IF conditions
For calculations or thresholds — Use numeric fields like satisfaction_score (1-10)
For human review — Use narrative fields like summary, reasoning, recommendations

Avoid:

Fields that are too sparse (a single text blob is hard to use programmatically)
Fields that are too granular (risk_factor_1 through risk_factor_20 is overwhelming)

File Inputs

Run Agent Task can pass files directly to the agent for processing — use this in place of the AI File Reader when you want broader model support and richer file handling inside the agent’s reasoning.

The Files section is located below the Task Description field in the action configuration. Expand it to reveal the file input area — do not paste file references into the Task Description text box itself.

Expand the Files section below the Task Description.
Click Add, select Attachment type → One or many files → set the source to Attachment Trigger (when using an Attachment is Added trigger).
In the Task Description, tell the agent what to do with the file (e.g., “Summarize the attached invoice and extract line items”).

File handling depends on the agent’s selected model — choose one that supports the file types you intend to send.

The agent must use a multimodal model. If your agent uses a non-multimodal model (one without vision/file support), the platform skips file delivery entirely — the agent will respond in milliseconds without reading the file. Always confirm your agent’s model supports file input (GPT-4o, ChatGPT 5, Claude Sonnet, Gemini, or equivalent) before building the automation. Check the model in Admin → [Your App] → Intelligence → Agents → [Your Agent] → Overview.

Setting the attachment source correctly is critical. When using an Attachment is Added trigger, the Files section must reference Attachment Trigger as the source — this passes the specific file that fired the trigger to the agent. Using a record reference instead silently delivers zero file bytes and the agent cannot read the file. There is no error message; the agent simply responds without file context.

Expected execution behaviour

A successful file-processing run completes in 3–8 seconds and shows 2 completed actions (Run Agent Task + the downstream action) in the execution history. If the task completes in under 2 seconds, the agent likely did not receive the file — see Troubleshooting file inputs below.

Differences from Agent Chat

Run Agent Task is headless: the agent processes the file in a single pass using only the Task Description for guidance. It cannot ask follow-up questions. A vague description (e.g., “Look at this file”) forces the agent to guess intent, which produces different results from the same file in an interactive Agent Chat. To match Agent Chat results, write a Task Description that mirrors the question you would ask in chat, and include relevant context via value references.

The Test & Preview screen may not handle attachments the same way as an interactive Agent Chat session. If you see different results between Test & Preview and Agent Chat, try providing a more specific Task Description. To test how the agent handles a file conversationally, use the agent’s chat interface instead.

For a side-by-side comparison, see Agent Chat vs Run Agent Task.

Testing and Error Handling

Before deploying, test your agent task using the Test & Preview feature:

Fill in value references with actual data
Run the agent task
Verify the output format and quality
Adjust task definition if needed

Test with multiple scenario types: typical cases, edge cases, ambiguous cases, and varying data quality. After deployment, review the first 10–20 runs manually, monitor the run_agent_task.success field, and refine your task definition based on real-world performance.

Built-in Retry Logic

The system includes built-in retry logic (up to 3 attempts) when agents don’t provide correctly formatted structured output:

Agent attempts to provide structured output
If format is incorrect, system returns error to agent with details
Agent tries again with error context
Repeats up to 3 times

Always Check the Success Field

Always check run_agent_task.success before using agent output in downstream actions:

Run Agent Task
  ↓
IF run_agent_task.success = true
  → Normal processing flow
OTHERWISE
  → Error handling:
    - Post Comment: "Agent task failed: {{run_agent_task.error_message}}"
    - Send Message to Teams: "@admins Agent task error"
    - Make Assignment: Route to manual review

Implement Graceful Degradation

Design workflows that remain functional even if the agent task fails:

Run Agent Task: Personalization analysis
  ↓
IF run_agent_task.success = true
  → Send Email: Personalized message with {{run_agent_task.recommendations}}
OTHERWISE
  → Send Email: Standard template (still functional)

Troubleshooting file inputs

If your agent isn’t processing uploaded files correctly, check these common issues:Agent task completes in under 2 seconds with no file contentThe agent did not receive the file. Verify both:

Attachment source — Open the automation, click Edit on the Run Agent Task, and confirm the Files section references Attachment Trigger (not a record reference).
Agent model — Confirm the agent uses a multimodal model on the agent’s Overview page.

Agent responds “I don’t have access to the attached file”Same root cause — the file was not delivered. Fix the attachment source or switch to a multimodal model.Execution history shows only 1 completed actionThe Run Agent Task step failed or produced no usable output, causing downstream tasks to be skipped. Check the task’s output in the Execution Details panel for an error message.

When to Use Run Agent Task

Ideal Use Cases

Use Run Agent Task when a step in your workflow requires reasoning, judgment, or synthesis of information.

Research & Analysis

Scenario: Tasks requiring information gathering and synthesis

New Lead Created → Run Agent Task
Task: "Research {{lead.company}} to identify:
- Industry and market position
- Recent news or developments
- Competitive landscape
- 3-5 key talking points for our sales team
Success: Provide actionable sales intelligence"
Output Type: Structured
Fields: industry, company_size, recent_news, talking_points, research_confidence

Complex Evaluation & Assessment

Scenario: Decisions requiring multiple factors and reasoning

Contract Uploaded → AI File Analysis → Run Agent Task
Task: "Evaluate this contract with terms {{contract.terms}} and value {{contract.value}}.
Consider our standard terms, risk tolerance, and relationship with {{customer.name}}.
Success: Provide risk assessment (Low/Medium/High), key concerns, and approval recommendation."
Output Type: Structured
Fields: risk_level, key_concerns, approval_recommended, negotiation_points

This pattern pairs well with AI File Reader for extracting structured data before agent evaluation. See the document review example in Workflow Examples below.

Content Quality Assessment

Scenario: Evaluating quality, completeness, or appropriateness of content

Application Submitted → Run Agent Task
Task: "Review this grant application from {{applicant.name}} for {{project.title}}.
Application content: {{application.content}}
Grant criteria: {{grant.criteria}}
Success: Evaluate completeness, alignment with criteria, and provide score (1-10) with feedback."
Output Type: Structured
Fields: completeness_score, criteria_alignment, overall_score, strengths, improvements_needed

Intelligent Data Enrichment

Scenario: Enhancing records with synthesized information

Customer Record Created → Run Agent Task
Task: "Enrich data for {{customer.company}} in {{customer.industry}}.
Success: Provide company size estimate, key decision makers' typical titles,
common pain points in their industry, and recommended product fit."
Output Type: Structured
Fields: company_size_estimate, decision_maker_titles, industry_pain_points, product_recommendations

Multi-Step Problem Solving

Scenario: Tasks requiring sequential reasoning and proactive action

Complex Issue Detected → Run Agent Task
Task: "Diagnose this system issue: {{issue.description}}
Recent changes: {{system.recent_changes}}
Error logs: {{system.errors}}
Success: Provide root cause analysis, step-by-step resolution plan, and prevention recommendations."
Output Type: Structured
Fields: root_cause, resolution_steps, estimated_fix_time, prevention_measures

When NOT to Use Run Agent Task

Use standard automation actions instead when:

Deterministic logic — Simple IF/THEN logic, calculations, or predefined rules. Use IF conditions or Run Calculation instead.
Direct data operations — Creating, updating, searching, or relating records with known values. Use Create Record, Update Record Fields, or Search Records instead.
Standard classifications — Categorization with clear, predefined categories. Use AI Classification instead.
API integrations — Direct calls to external systems with structured parameters. Use Send API Request instead.

Decision rule: Does this task require reasoning, judgment, or synthesis of information? If yes, consider Run Agent Task. If no, use standard automation actions.

Workflow Examples

These examples demonstrate the structured → agent → structured pattern in complete workflows. Each combines standard automation actions with Run Agent Task.

Example: Intelligent Support Ticket Routing

Scenario: Route support tickets based on nuanced assessment, not just keywords.

Support Email Received
  ↓
AI Classification: Categorize ticket type
  ↓
Search Records: Find customer
  ↓
Find Related Records: Get customer's recent tickets and products
  ↓
Run Agent Task: "Intelligent Ticket Assessment"
  Task: "Assess support ticket from {{customer.name}} about {{ticket.subject}}.
    Ticket content: {{ticket.body}}
    Customer tier: {{customer.tier}}
    Recent tickets: {{related_tickets.summaries}}
    Customer products: {{customer.products}}
    Success: Determine complexity (1-5), required expertise (General/Product/Engineering),
    urgency (Low/Medium/High/Critical), and whether this is part of a pattern."
  Output Type: Structured
  Fields: complexity_score (number), required_expertise (text), urgency (text),
          pattern_detected (checkbox), pattern_description (text),
          estimated_resolution_hours (number)
  ↓
IF run_agent_task.pattern_detected = true
  → Add Watcher: Customer Success Manager
  → Post Comment: "Pattern detected: {{run_agent_task.pattern_description}}"
  ↓
IF run_agent_task.urgency = "Critical"
  → Make Assignment: Senior Support (immediate)
  → Send Message to Teams: "@support-leads Critical ticket: {{ticket.subject}}"
ELSE IF run_agent_task.required_expertise = "Engineering"
  → Make Assignment: Engineering Team
  → Start Approval Process: Engineering time allocation
OTHERWISE
  → Make Assignment: General Support
  ↓
Update Record Fields:
  - Complexity: {{run_agent_task.complexity_score}}
  - Estimated Hours: {{run_agent_task.estimated_resolution_hours}}
  ↓
Send Email Notification: Customer confirmation with estimated timeline

This workflow uses AI Classification for basic categorization and Run Agent Task for nuanced assessment, then feeds agent output into standard routing logic.

Example: Document Review Pipeline

Scenario: Automated first-pass contract review for a legal team.

Contract Attachment Added
  ↓
AI File Analysis: Extract contract data
  ↓
Search Records: Find customer and relationship history
  ↓
Run Agent Task: "Contract Risk Assessment"
  Task: "Review contract from {{customer.name}} with value {{contract.value}}.
    Extracted terms: {{ai_file_analysis.terms}}
    Standard terms: {{company.standard_contract_terms}}
    Customer relationship: {{customer.relationship_years}} years,
                          LTV: ${{customer.lifetime_value}}
    Success: Assess risk (Low/Medium/High), identify deviations from standard,
    flag must-negotiate items, and recommend approval authority."
  Output Type: Structured
  Fields: risk_level (text), deviations (list), must_negotiate (list),
          recommended_approver (text), business_justification (text),
          expedite_recommended (checkbox)
  ↓
Update Record Fields: Add risk assessment and recommendations
  ↓
IF run_agent_task.risk_level = "High"
  → Start Approval Process: Legal + CFO
  → Send Message to Teams: "#legal High-risk contract requires review"
ELSE IF run_agent_task.risk_level = "Medium"
  → Start Approval Process: Legal only
OTHERWISE (Low risk)
  → IF contract.value < $10000
      Update Record Fields: Auto-approved
  → OTHERWISE
      Start Approval Process: Manager only

This pairs AI File Reader for data extraction with Run Agent Task for risk assessment that requires judgment.

Example: Personalized Order Processing

Scenario: Provide personalized order handling based on customer history.

Order Created
  ↓
Search Records: Get customer history
  ↓
Run Agent Task: "Analyze Order Personalization"
  Task: "Analyze order from {{customer.name}} for {{order.items}}.
    Customer history: {{customer.past_orders}}, lifetime value: ${{customer.ltv}},
    preferences: {{customer.preferences}}.
    Success: Identify upsell opportunities, special handling needs, personalized
    message suggestions, and estimated satisfaction impact of personalization."
  Output Type: Structured
  Fields: upsell_items (list), special_handling (text), personalized_message (text),
          satisfaction_impact (text), include_sample (checkbox)
  ↓
IF run_agent_task.include_sample = true
  → Update Record Fields: Add free sample to order
  ↓
IF run_agent_task.upsell_items has values
  → Send Email: Personalized confirmation with recommendations
OTHERWISE
  → Send Email: Standard confirmation
  ↓
Create Record: Log personalization actions for future learning

Advanced Patterns

Chaining Agent Tasks

For complex workflows, break work into sequential agent tasks where each builds on the previous:

Data Collected
  ↓
Run Agent Task: "Initial Analysis"
  → Analyze raw data and identify key themes
  ↓
Run Agent Task: "Deep Dive"
  → Task: "Based on initial themes {{agent_task_1.themes}},
          conduct detailed analysis..."
  ↓
Run Agent Task: "Recommendations"
  → Task: "Given analysis {{agent_task_2.findings}},
          provide strategic recommendations..."

Use this when a single agent task would be too complex — breaking into stages improves output quality.

Conditional Agent Invocation

Use agents only when intelligence is needed, falling back to standard actions for straightforward cases:

Record Updated
  ↓
IF simple_condition = true
  → Standard processing (fast, deterministic)
OTHERWISE
  → Run Agent Task (intelligent assessment)
  → Use agent insights for decision

This is the same pattern shown in the support ticket example in Workflow Examples, where AI Classification handles simple categorization and Run Agent Task handles complex cases.

Agent + Human Hybrid

Combine agent intelligence with human oversight using approval processes:

Contract Submitted
  ↓
Run Agent Task: "Contract Assessment"
  ↓
IF run_agent_task.risk_level = "Low" AND run_agent_task.confidence > 0.9
  → Auto-approve (agent sufficient)
OTHERWISE
  → Start Approval Process (human review)
  → Context: Agent provided {{run_agent_task.reasoning}}

Combining with Other Automation Actions

Run Agent Task integrates with other automation actions:

AI File Reader — Extract structured data from documents, then pass to an agent for evaluation and recommendations. See the document review example in Workflow Examples.
API Requests — Use agent output to determine API endpoints or parameters, or feed API response data into an agent for synthesis.
AI Classification — Use classification for basic categorization, then route complex cases to Run Agent Task. See the support ticket example in Workflow Examples.

Agent Management

Agent Deletion Protection

When you attempt to delete an agent that’s used in automations, the system prevents deletion and shows a list of automations using that agent with direct links to each one. Before deleting an agent:

Check which automations use it
Update those automations to use a different agent or action
Test the updated automations
Then delete the agent

Getting Started Checklist

Identify a use case where a workflow step requires reasoning or research
Design the workflow using the structured → agent → structured pattern
Create or select an agent with appropriate capabilities — see Agent tools, deployment, and integrations
Write a task definition with complete context and clear success criteria
Define output fields if using structured output
Test with real data using the Test & Preview feature
Implement error handling with success field checks
Deploy and monitor — review early executions, then iterate based on results

Next Steps

Automation Actions Reference

See all available automation actions including Run Agent Task details

AI in Automations

Learn about other AI-powered automation capabilities

Agent tools, deployment, and integrations

Understand how agents work and integrate with workflows

Automation Best Practices

General automation and workflow best practices

​How It Works

​Configure a Run Agent Task

​Action Name

​Object Selection

​Agent Selection

​Task Definition

​Output Type

​File Inputs

​Expected execution behaviour

​Differences from Agent Chat

​Testing and Error Handling

​When to Use Run Agent Task

​Ideal Use Cases

​When NOT to Use Run Agent Task

​Workflow Examples

​Advanced Patterns

​Agent Management

​Agent Deletion Protection

​Getting Started Checklist

​Next Steps

Automation Actions Reference

AI in Automations

Agent tools, deployment, and integrations

Automation Best Practices

How It Works

Configure a Run Agent Task

Action Name

Object Selection

Agent Selection

Task Definition

Output Type

File Inputs

Expected execution behaviour

Differences from Agent Chat

Testing and Error Handling

When to Use Run Agent Task

Ideal Use Cases

When NOT to Use Run Agent Task

Workflow Examples

Advanced Patterns

Agent Management

Agent Deletion Protection

Getting Started Checklist

Next Steps