> ## Documentation Index
> Fetch the complete documentation index at: https://docs.layest.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Run Agent Workflows: Manual, Triggered & Scheduled
> Learn how to run Layest agent workflows manually, via triggers, or on a schedule. Monitor runs, view outputs, and handle errors in real time.
Once your agent is configured and active, you need a way to put it to work. Layest gives you three distinct ways to run agent workflows: manually from the dashboard for testing and one-off tasks, automatically via event triggers that fire when something happens in a connected system, or on a fixed schedule for recurring jobs. Each run mode is suited to different situations, and you can combine them — for example, running an agent on a schedule while also allowing it to be triggered by incoming webhooks.
This page explains how each run mode works, how to monitor runs in progress, and how to handle errors.
***
## Three Ways to Run a Workflow
**Manual runs** let you execute an agent immediately from the Layest dashboard. This is the fastest way to test your agent, process a one-off request, or run an ad-hoc task without setting up any automation.
### Running an Agent Manually
Go to **Agents** in the sidebar and click the agent you want to run.
Click the **Run** tab at the top of the agent detail page. This opens the manual run panel.
If your agent expects an input — such as a user message, a document, or a JSON payload — enter it in the **Input** field. Some agents have no required input and will run immediately with just a trigger.
```json theme={null}
{
"user_message": "Can you summarize last quarter's sales report?",
"context": {
"user_id": "usr_12345",
"region": "EMEA"
}
}
```
The input schema is defined in your agent's tool configuration. If the Run tab shows a structured form instead of a raw JSON editor, Layest has auto-detected the expected input shape and built a UI for it.
Click **Run Now** to start the workflow. You will be taken to the **Run Detail** page automatically, where you can watch the run progress in real time.
### When to Use Manual Runs
* Testing a newly configured or updated agent before enabling triggers
* Processing a one-off document, file, or request
* Debugging agent behavior by running with specific controlled inputs
* Demonstrating agent capabilities to stakeholders
**Trigger-based runs** start automatically when a specific event occurs in a connected integration or when an external system sends a signal to Layest. This is the most common run mode for production agents that need to respond to real-world events in real time.
### Types of Triggers
| Trigger Type | Example Events |
| --------------------- | -------------------------------------------------------------------------------------------- |
| **Webhook** | An external system sends a POST request to your agent's unique webhook URL |
| **Integration Event** | A new Zendesk ticket is created, a Slack message is posted, a row is added to a Google Sheet |
| **Form Submission** | A user submits a form on your website or a Layest-hosted form |
| **API Call** | Your application calls the Layest API to start a run programmatically |
| **Agent-to-Agent** | Another Layest agent completes a step and hands off to this agent |
### Configuring a Trigger
In your agent's detail page, click the **Triggers** tab. Existing triggers are listed here; click **Add Trigger** to create a new one.
Select the trigger type from the list. For **Integration Events**, you will be asked to choose the connected integration and specify which event(s) should start the agent.
Use the input mapping editor to specify how data from the trigger event should be passed into your agent. For example, map the `ticket.body` field from a Zendesk trigger to your agent's `user_message` input.
```json theme={null}
{
"user_message": "{{trigger.ticket.body}}",
"ticket_id": "{{trigger.ticket.id}}",
"priority": "{{trigger.ticket.priority}}"
}
```
Click **Save Trigger**. The trigger is active immediately — any matching event will now start a run automatically.
Test your trigger by clicking **Send Test Event** in the trigger configuration panel. This fires a sample payload and starts a real run so you can verify the mapping is correct.
### Webhook URL
Every Layest agent has a unique webhook URL. Find it in the **Triggers** tab under **Webhook Endpoint**. Send a `POST` request with a JSON body to this URL to start a run from any external system:
```bash theme={null}
curl -X POST https://app.layest.ai/webhooks/agents/agt_abc123 \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{"user_message": "Process this request"}'
```
Never expose your API key in client-side code or public repositories. Use environment variables or a secrets manager to keep it secure.
**Scheduled runs** execute your agent automatically at a fixed time or recurring interval — no external event required. This is ideal for daily reports, periodic data syncs, regular cleanups, and any workflow that needs to run on a predictable cadence.
### Setting Up a Schedule
In your agent's detail page, click the **Schedules** tab. Click **Add Schedule** to create a new schedule.
Select how often the agent should run:
| Option | Example |
| ----------------- | --------------------------------------- |
| **Hourly** | Every hour at minute 0 |
| **Daily** | Every day at 09:00 UTC |
| **Weekly** | Every Monday at 08:00 UTC |
| **Monthly** | First day of each month at 00:00 UTC |
| **Custom (Cron)** | Any interval using standard cron syntax |
For custom intervals, enter a cron expression directly. For example, `0 9 * * 1-5` runs the agent at 9:00 AM every weekday.
If your agent requires input, define the static payload to use for each scheduled run. For example, a daily report agent might receive:
```json theme={null}
{
"report_type": "daily_summary",
"date": "{{today}}",
"recipients": ["team@acmecorp.com"]
}
```
Use the `{{today}}`, `{{yesterday}}`, and `{{now}}` template variables to inject dynamic date values into your scheduled input without hardcoding dates.
Click **Save Schedule**. The schedule becomes active immediately. The next scheduled run time is displayed in the Schedules panel.
### Timezone Handling
All schedules run in **UTC** by default. To run at a local time, convert to UTC before entering your schedule, or select a timezone override in the schedule settings.
Scheduled runs are queued up to 1 minute before the scheduled time to ensure on-time execution. During high platform load, there may be a short delay of up to 2 minutes.
***
## Viewing Run Status and History
All runs — regardless of how they were triggered — are recorded in the **Run History** panel. To access it:
1. Open the agent from the **Agents** list.
2. Click the **Runs** tab.
The Runs tab shows a paginated list of all runs with:
| Column | Description |
| --------------- | --------------------------------------------------------------------------- |
| **Run ID** | Unique identifier for the run (useful for API lookups and support requests) |
| **Status** | `Running`, `Completed`, `Failed`, `Timeout`, or `Cancelled` |
| **Trigger** | How the run was started (Manual, Webhook, Schedule, API) |
| **Started At** | Timestamp of when the run began |
| **Duration** | Total time from start to completion |
| **Tokens Used** | Total tokens consumed by the model in this run |
Click any row to open the **Run Detail** page.
***
## Understanding Run Outputs and Logs
The Run Detail page gives you a complete picture of what happened during a run:
* **Input** — the exact payload the agent received
* **Output** — the final response or result the agent produced
* **Steps** — an expandable list of every action the agent took, including model calls, tool calls, and decision points
* **Tool Calls** — details of each tool invocation, including the request sent and the response received
* **Logs** — raw log stream with timestamps, useful for debugging
* **Token Usage** — breakdown of prompt tokens, completion tokens, and total cost
Run logs are retained for **30 days** on the Starter plan and **90 days** on the Pro and Enterprise plans. Export logs to your own storage via the Layest API or the **Export Logs** button if you need longer retention.
***
## Error States and Retrying Runs
When a run fails, the status column shows **Failed** and the Run Detail page displays the error message and the step at which the failure occurred. Common error types include:
| Error | Likely Cause | Resolution |
| ----------------------- | ------------------------------------------------------------------- | ------------------------------------------------------------- |
| `ModelTimeout` | The model took too long to respond | Increase the response timeout in Behavior Settings, or retry |
| `ToolCallFailed` | A connected integration returned an error | Check the integration's auth status and the tool call details |
| `InputValidationError` | The incoming payload did not match the expected schema | Fix the input mapping in the trigger or the calling system |
| `RateLimitExceeded` | Your model provider's rate limit was hit | Switch to a different model tier or reduce run frequency |
| `ContextLengthExceeded` | The conversation + instructions exceeded the model's context window | Shorten your system prompt or reduce retrieved memory chunks |
### Retrying a Failed Run
To retry a failed run with the same input:
1. Open the failed run from the **Runs** tab.
2. Click **Retry Run** in the top-right corner of the Run Detail page.
3. Layest creates a new run with the identical input and marks the original as superseded.
If a run fails repeatedly with the same error, check the **Alerts** tab in your workspace settings. You can configure automatic alerts (Slack, email, or webhook) whenever a run fails, so your team is notified without having to monitor the dashboard manually.
***
## Cancelling a Running Workflow
To stop a run that is currently in progress:
1. Open the **Runs** tab and find the run with status **Running**.
2. Click the run to open the detail page.
3. Click **Cancel Run** in the top-right corner.
Cancellation is best-effort — if the agent has already made irreversible tool calls (e.g., sent an email, created a ticket), those actions cannot be undone. The run status will update to **Cancelled** within a few seconds.
***
## Next Steps
Go deeper with run analytics, performance dashboards, and anomaly detection across all your agents.
Tune your agent's model, instructions, and behavior settings to improve run outcomes.