> ## Documentation Index
> Fetch the complete documentation index at: https://docs.elementum.io/llms.txt
> Use this file to discover all available pages before exploring further.
# Agent Task Automation
> Bridge structured and unstructured workflows by combining deterministic automation with intelligent agent autonomy
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](/workflows/automation-system) with the adaptability of [AI agents](/ai-agents/agents-tools-and-deployment).
**New to Automations?** Check out the [Automation System](/workflows/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:
1. Start with **structured automation** (trigger detection, data gathering)
2. Hand off to an **autonomous agent** (analysis, research, decision-making)
3. 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)
```
* Excellent at deterministic tasks
* Struggles with tasks requiring judgment
* Can't handle "figure it out" scenarios
* Limited to predefined logic paths
* Excellent at complex reasoning
* Can handle ambiguous tasks
* Less predictable for deterministic steps
* Harder to integrate into existing processes
* **Structured reliability** — Use automation for data gathering, record updates, notifications, and integrations
* **Intelligent autonomy** — Use agents for research, analysis, evaluation, and tasks requiring reasoning
* Transitions between both within a single workflow
## 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](/workflows/automation-triggers-reference).
### 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](/ai-agents/agents-tools-and-deployment).
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](/workflows/automation-actions-reference).
Every task definition should include:
1. **Context** — All relevant data via value references
2. **Objective** — What the agent should accomplish
3. **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:
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](/workflows/elementum-intelligence-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:
1. risk_score (number): Overall risk rating from 1-10
2. risk_level (text): Low/Medium/High categorization
3. key_risks (list): Specific risk factors identified
4. mitigation_required (checkbox): Whether mitigation actions are needed
5. 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](/workflows/elementum-intelligence-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.
1. Expand the **Files** section below the Task Description.
2. Click **Add**, select **Attachment** type → **One or many files** → set the source to **Attachment Trigger** (when using an Attachment is Added trigger).
3. 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](#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](/ai-agents/agents-interacting#agent-chat-vs-run-agent-task).
### Testing and Error Handling
Before deploying, test your agent task using the **Test & Preview** feature:
1. Fill in value references with actual data
2. Run the agent task
3. Verify the output format and quality
4. 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.
The system includes built-in retry logic (up to 3 attempts) when agents don't provide correctly formatted structured output:
1. Agent attempts to provide structured output
2. If format is incorrect, system returns error to agent with details
3. Agent tries again with error context
4. Repeats up to 3 times
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
```
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)
```
If your agent isn't processing uploaded files correctly, check these common issues:
**Agent task completes in under 2 seconds with no file content**
The agent did not receive the file. Verify both:
1. **Attachment source** — Open the automation, click **Edit** on the Run Agent Task, and confirm the Files section references **Attachment Trigger** (not a record reference).
2. **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 action**
The 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.
**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
```
**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](/workflows/elementum-intelligence-file-reader) for extracting structured data before agent evaluation. See the document review example in [Workflow Examples](#workflow-examples) below.
**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
```
**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
```
**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](/workflows/automation-actions-reference) 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](/ai-agents/ai-automations) 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](/workflows/automation-actions-reference) with Run Agent Task.
**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](/ai-agents/ai-automations) for basic categorization and Run Agent Task for nuanced assessment, then feeds agent output into standard routing logic.
**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](/workflows/elementum-intelligence-file-reader) for data extraction with Run Agent Task for risk assessment that requires judgment.
**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
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.
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](#workflow-examples), where [AI Classification](/ai-agents/ai-automations) handles simple categorization and Run Agent Task handles complex cases.
Combine agent intelligence with human oversight using [approval processes](/workflows/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}}
```
Run Agent Task integrates with other [automation actions](/workflows/automation-actions-reference):
* **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](#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](#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:
1. Check which automations use it
2. Update those automations to use a different agent or action
3. Test the updated automations
4. Then delete the agent
## Getting Started Checklist
1. **Identify a use case** where a workflow step requires reasoning or research
2. **Design the workflow** using the structured → agent → structured pattern
3. **Create or select an agent** with appropriate capabilities — see [Agent tools, deployment, and integrations](/ai-agents/agents-tools-and-deployment)
4. **Write a task definition** with complete context and [clear success criteria](#task-definition)
5. **Define output fields** if using [structured output](#output-type)
6. **Test with real data** using the Test & Preview feature
7. **Implement [error handling](#testing-and-error-handling)** with success field checks
8. **Deploy and monitor** — review early executions, then iterate based on results
## Next Steps
See all available automation actions including Run Agent Task details
Learn about other AI-powered automation capabilities
Understand how agents work and integrate with workflows
General automation and workflow best practices