# Task Agents

Task Agents are AI agents that run background tasks on a schedule or on demand. Unlike voice, chat, or email agents that interact directly with people, task agents perform internal work such as data processing, analysis, and recurring operational tasks.

## Key Concepts

- **Task Agent** — An AI configuration for background task execution
- **Execution** — A single run of the task agent
- **Logs** — Records of what the agent did during execution

## Getting Started

1. Navigate to **Agents > Task Agents**
2. Click **+ Create Task Agent**
3. Configure the agent's name, instructions, and schedule
4. Save

## Creating a Task Agent

Configure your task agent with:

- **Name** — Descriptive identifier
- **Instructions** — What the agent should do when it runs
- **Tools** — Functions available during execution (e.g., CRM operations, web search, API calls)
- **Schedule** — How often to run (manual, hourly, daily, etc.)
- **Phone Number** — Optional, if the task needs SMS capabilities

## Viewing Logs

Open a task agent and select **Logs** to review its execution history:

- **Execution Date** — When the agent ran
- **Status** — Success, failure, or partial
- **Duration** — How long the execution took
- **Output** — What the agent accomplished
- **Conversation reviewed** — For an agent that reviews calls or chats (below), which conversation the run read, with a link to it, or why there was none

## Reviewing a Call or Chat

A task agent that runs when a call or chat ends — a quality review, a follow-up, a summary for staff — needs that conversation's transcript. Turn it on under **Tools & Capabilities → Cross-Agent Enrichment → Include the conversation that triggered this run**:

- The agent receives the **full transcript**, tool calls included, at the end of its prompt after the platform rules. Nothing needs to be written into the instructions; refer to it as "the call" or "the chat".
- It works for anonymous website visitors too: no contact record is needed.
- When a run carries no call or chat (for example a scheduled run), the agent reads the contact's most recent call or chat and is told that it is a fallback.
- Each run's log shows **Conversation reviewed**: which call or chat it was, with a link, or why none was included.

The older way, writing `{{call_transcript}}` or `{{chat_transcript}}` into the instructions, still works. When the setting is on, the transcript is given once, at the end, and the placeholder points to it. The instructions box reminds you to switch over.

The **Pull recent interactions** toggle beside it is separate: it lists the contact's most recent conversations on other channels (title, short summary) and lets the agent open any of them in full. The conversation being reviewed is left out of that list.

## Using Task Agents in Orchestrations

Task agents become more powerful when they are used as steps inside an orchestration. When a task agent runs in that context, two additional capabilities become available:

### Placeholder Syntax

Data from earlier orchestration steps, such as Store Read results, form submissions, or previous task agent outputs, is available inside the task agent instructions through **placeholders**:

```
{{ key_name }}
```

For example, if a Store Read step loaded `accounts_receivable`:

```
Here are the current accounts receivable:

{{ accounts_receivable }}

Identify overdue accounts and recommend next actions.
```

- The placeholder stays where you wrote it; the agent receives its **value at the end of the prompt**, after the platform rules, under the same name
- **Strings** are given as-is; **objects and arrays** as formatted JSON
- A name nothing supplies keeps its text without the braces

Any key produced by an earlier step can be referenced, including store data, `formData`, or `taskAgentResponse` from a previous task agent.

### Update Orchestration Store Tool

When a task agent runs inside an orchestration, it automatically receives the **update_orchestration_store** tool. This lets the AI write structured data back to the orchestration's persistent store during execution.

The tool accepts a `data` object of key-value pairs to merge into the store. Existing keys with the same name are overwritten while unrelated keys are preserved.

This is useful in recurring workflows where the task agent needs to process information and persist the results for the next run without requiring a separate Store Write step afterward.

> The tool only appears when the task agent is running inside an orchestration. It is not available during standalone execution.

## Common Use Cases

- **Data Enrichment** — Look up missing contact information
- **Report Generation** — Create periodic summary reports
- **CRM Maintenance** — Clean up duplicate records, update stale data
- **Monitoring** — Check external systems and alert on issues
- **Content Generation** — Create drafts for review

<!-- SCREENSHOT: task-agents-list.png — Task agents list -->
<!-- SCREENSHOT: task-agent-logs.png — Task agent execution logs -->