# null

# How Workflows Run

**Time to complete:** 5 minutes

***

## The Basics

When you click "Run" (or a trigger fires), Agent.AI runs your actions **top to bottom, one at a time**.

**Example workflow:**

1. Search for contacts
2. Loop through results
3. Update each contact
4. End loop
5. Send summary email

Each action completes before the next one starts.

***

## Watching a Workflow Run

### The Execution Log

When a workflow runs, you see each action execute in real-time:

**What you'll see:**

```
✓ Step 1: Search HubSpot Contacts (completed in 1.2s)
✓ Step 2: For Loop - Start (completed in 0.1s)
✓ Step 3: Update Contact (completed in 0.8s)
✓ Step 3: Update Contact (completed in 0.7s)  ← Runs for each loop
✓ Step 3: Update Contact (completed in 0.9s)
✓ Step 4: For Loop - End (completed in 0.1s)
✓ Step 5: Send Email (completed in 0.5s)

Workflow completed in 4.3s
```

**Colors:**

* **Green ✓** = Action succeeded
* **Red ✗** = Action failed
* **Yellow ⚠** = Action warning

***

### Viewing Action Details

Click on any action in the log to see:

**Inputs:**

```json  theme={null}
{
  "object_type": "contacts",
  "filters": "email=john@acme.com"
}
```

**Outputs:**

```json  theme={null}
{
  "results": [
    {
      "id": "12345",
      "properties": {
        "email": "john@acme.com",
        "firstname": "John"
      }
    }
  ]
}
```

**Execution time:** 1.2 seconds

***

## How Variables Flow Through Actions

Each action sees all variables created by previous actions:

**Step 1:** Search (creates `{{contacts}}`)

* Available variables: (none yet)

**Step 2:** Loop (creates `{{current_contact}}`)

* Available variables: `{{contacts}}`

**Step 3:** Update contact

* Available variables: `{{contacts}}`, `{{current_contact}}`

**Step 4:** End loop (removes `{{current_contact}}`)

* Available variables: `{{contacts}}`

**Step 5:** Send email

* Available variables: `{{contacts}}`

> **Rule:** Variables are available to all actions that come AFTER they're created.

***

## What Happens When Actions Fail

If an action fails, the workflow stops:

**Example:**

```
✓ Step 1: Search Contacts
✓ Step 2: For Loop - Start
✗ Step 3: Update Contact - ERROR: Missing required field "email"

Workflow stopped at Step 3
Steps 4-5 did not run
```

**The error shows:**

* Which action failed
* Why it failed
* What data it was working with

**Fix it:**

1. Look at the error message
2. Fix the action configuration
3. Run the workflow again

***

## Testing Your Workflow

### Use Test Mode

Before running on real data:

1. **Click "Test Run"** instead of "Run"
2. Enter sample data manually
3. Watch each action execute
4. Check outputs look right
5. Fix any errors
6. Run for real when ready

**Test data example:**

```json  theme={null}
{
  "contact_email": "test@example.com",
  "deal_id": "12345"
}
```

### Start Small

**Good approach:**

* Build 2-3 actions
* Test run
* Add 2-3 more
* Test run
* Repeat

**Risky approach:**

* Build entire 20-action workflow
* Test run
* Spend an hour debugging 😅

***

## Performance Tips

**Fast workflows:**

* ✅ Search with filters (not "get all then filter")
* ✅ Use limits on searches (e.g., max 100 results)
* ✅ Only request properties you need

**Slow workflows:**

* ❌ Get all 10,000 contacts then loop
* ❌ Request all 50+ properties when you only need 3
* ❌ No limits on searches

**Typical execution times:**

* Search: 1-2 seconds
* Update single object: 0.5-1 second
* Loop 100 items: \~1 minute
* LLM analysis: 2-5 seconds

***

## Troubleshooting

### Workflow Never Finishes

**Possible causes:**

1. Loop running too many times (missing end condition)
2. External API is slow or timing out
3. Too many items to process

**Fix:**

* Add limits to searches
* Check loop has proper end condition
* Consider breaking into smaller batches

***

### Actions Run in Wrong Order

**Problem:** Variables not available when you expect them.

**Fix:**

* Actions execute top to bottom
* Move the action that creates the variable earlier
* Variables from Step 5 aren't available in Step 3

***

### Can't See What Went Wrong

**Problem:** Error message unclear.

**Fix:**

1. Click on the failed action
2. Look at "Inputs" tab - see what data it received
3. Look at "Error" tab - see full error message
4. Check if variables have expected values

***

## Next Steps

* [ ] Learn about [Triggers](./04-triggers.md) - ways to start workflows
* [ ] Try building a simple 3-action workflow
* [ ] Use Test Mode to see execution in action

***

**Last Updated:** 2025-10-01


---

> To find navigation and other pages in this documentation, fetch the llms.txt file at: https://docs.agent.ai/llms.txt