> ## Documentation Index
> Fetch the complete documentation index at: https://docs.oration.ai/llms.txt
> Use this file to discover all available pages before exploring further.
# Assists
> Let your voice agent ask a human colleague for help without transferring the call
## What are Assists?
**Assists** let your voice agent pause a task and ask a human colleague for help — while staying on the line with the customer.
Unlike a call transfer, the AI does not hand the conversation over. It creates a request, routes it through a contact-center queue, and keeps talking to the caller (or plays hold music) until a teammate accepts, rejects, or closes the request.
Use Assists when the model can handle most of the call, but some steps need a person: looking up an account the AI cannot access, approving a refund, confirming a policy exception, or answering a question that is too sensitive to automate.
Think of Assists as tools that call a human instead of an API. You configure them next to Tools in the dashboard, and the model invokes them the same way it invokes any other action.
***
## Assists vs Tools vs call transfer
| | **Tools** | **Assists** | **Call transfer** |
| ----------------------- | --------------------------------- | ------------------------------------------------- | ------------------------------------------ |
| Who does the work | Your API or backend | A human on a contact-center queue | A human who takes the live call |
| What the customer hears | The AI stays on the call | The AI stays on the call (or hold music) | The AI leaves; a person picks up |
| When to use it | Lookups, updates, SMS, CRM writes | Judgement, systems the AI cannot reach, approvals | The caller must speak to a person directly |
If the caller needs to *talk to* someone, use [call transfer](/guides/flows/nodes/transfer). If the AI only needs a colleague to *do something* in the background, use an Assist.
***
## How Assists are organized
Assists follow the same hierarchy as Tools:
* **Assist** — A named container (shown as **Assists** in the sidebar under **Tools**). It holds one or more actions.
* **Action** — A single LLM-callable task, such as `lookup_order` or `approve_refund`. Name and description are what the model sees. Each action points at a contact-center **queue**.
* **Instance** — One live request created when the model calls an action during a conversation. Instances show up in **History** and in the contact-center **Assists** inbox.
You can clone an Assist or an action when you want a starting point instead of building from scratch.
***
## Prerequisites
You will need at least one **queue** in the contact center before you add actions. Every action routes requests through a queue — without one, the add-action form cannot be submitted. Make sure the teammates who should handle requests are assigned to that queue and can open the contact-center **Assists** inbox.
***
## Create an Assist
In the dashboard, go to **Tools → Assists**.
Click **New Assist**.
* **Name** — A short label your team will recognize (for example, `Order lookups` or `Billing exceptions`).
* **Description** — What this Assist is for. This is for your team, not the model.
Click **Create**. The new Assist appears on the list. Open it to add actions.
Assist names must be unique in the workspace. If you see a duplicate-name error, pick a different name or clone the existing Assist instead.
***
## Add an action
Open an Assist and click **Add Action**. Each action is advertised to the model as a tool.
### What the model sees
| Field | What to put | Tips |
| ----------------------------- | ---------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------ |
| **Name** | The tool name the LLM calls (for example, `lookup_order`). | Letters, digits, underscore, and hyphen only. Max 64 characters. Use `snake_case`. |
| **Description** | When and why the model should call this action. | Be specific: “Use this when the customer asks for order status and you cannot find it in tools.” |
| **Queue** | The contact-center queue that receives requests for this action. | Different actions on the same Assist can use different queues. |
| **Assist reason description** | Guidance for the required `assistReason` argument. | Tell the model to summarize *what the human needs to do*, not the whole transcript. |
| **Parameters schema** | Optional extra JSON Schema fields beyond `assistReason`. | Use this when the human needs structured data (order ID, refund amount). |
| **Restricted system prompt** | Extra instructions used only while a human is waiting on the customer. | Keep this short. The model is collecting an answer, not continuing the original task. |
### How the request behaves
| Field | Default | What it does |
| ------------------------- | ------- | ------------------------------------------------------------------------------------------------------------------------------------------- |
| **Interactive** | On | When on, the human agent can send free-text questions to the customer through the AI. |
| **Blocking** | On | When on, the speech machine parks the caller (hold music) while the request is outstanding. Turn off if the AI should keep chatting. |
| **Cancelable** | On | When on, the customer can refuse to continue and the model may cancel the request. Turn off for must-complete steps (compliance, identity). |
| **Wait before execution** | On | Waits for the start message to finish speaking before the request is created. |
Action names are function names. Spaces, punctuation, and emoji will be rejected. If two actions share a name inside the same Assist, creation fails.
### Optional parameters schema
`assistReason` is always required. Add a parameters schema when the human needs extra fields the model can fill in:
```json theme={null}
{
"type": "object",
"properties": {
"orderId": {
"type": "string",
"description": "The customer's order ID, digits only."
}
},
"required": ["orderId"]
}
```
The schema must be a JSON Schema object (`"type": "object"`). Invalid schemas are ignored at runtime, and the model will only send `assistReason`.
***
## Spoken copy and timeouts
Every action has its own customer-facing lines and timers. Edit them from **Update Action**. Spoken copy is what the *caller* hears — never mention tool names or “assist request.”
### Spoken copy
| Message | When the caller hears it |
| ------------------------- | ------------------------------------------------------------------ |
| **Start** | As soon as the model calls the action. |
| **Queue delay** | Repeated while waiting for a teammate to pick up the request. |
| **Working delay** | Repeated after a teammate is assigned and still working. |
| **Success** | The teammate accepted the request. |
| **Error / reject** | The teammate rejected the request. |
| **Queue timeout** | Nobody picked up in time. |
| **Working timeout** | The teammate did not finish in time. |
| **Resume** | The customer answered a clarifying question from the human. |
| **Human-agent close** | The teammate closed the request and handed control back to the AI. |
| **User cancel** | The customer declined to continue. |
| **Hold start / hold end** | The teammate put the caller on hold, then took them off. |
| **Technical error** | The request failed for a system reason. |
### Timeouts (milliseconds)
| Timeout | What it controls |
| ------------------------- | ------------------------------------------------------------------------------------------ |
| **Queue delay timeout** | How often the queue-delay line is spoken while unassigned. Default 10 seconds. |
| **Working delay timeout** | How often the working-delay line is spoken after assignment. Default 10 seconds. |
| **Queue timeout** | How long to wait in queue before giving up. Default 10 minutes. |
| **Working timeout** | How long to wait after assignment before giving up. Default 10 minutes. |
| **Failure timeout** | How long create / resume / cancel may wait before a technical failure. Default 10 minutes. |
Match delay copy to the action. “I’m checking that order with a colleague” is clearer than a generic “please wait,” especially on blocking actions where the caller is on hold.
***
## What happens during a call
When the conversation needs a person, the agent invokes the action (for example, `lookup_order`) and fills in `assistReason` plus any extra parameters.
The AI speaks the start copy. If **Wait before execution** is on, the request is created only after that line finishes.
A live instance is created and routed to the action’s queue. If **Blocking** is on, the caller hears hold music and delay copy until a teammate is assigned.
In the contact-center **Assists** inbox, the request appears under **In-flight**. The teammate can accept, reject, send a clarifying question (if Interactive is on), put the caller on hold, or close the request.
On accept, reject, timeout, cancel, or close, the AI speaks the matching line and continues the conversation with the outcome.
### Request statuses
| Status | Meaning |
| ---------------- | ------------------------------------------------------ |
| Created / queued | Waiting for a teammate. |
| Offered | At least one teammate has been offered the request. |
| Working | A teammate is assigned and handling it. |
| Completed | Accepted or closed by the human. |
| Failed | Rejected, timed out, overflowed, or a technical error. |
| Cancelled | The customer cancelled, or the conversation ended. |
***
## Handle requests in the contact center
Human teammates work requests from **Contact Center → Assists**, not from the Tools page.
* **In-flight** — Open requests that still need a person.
* **Approved** — Requests that were accepted.
* **Denied** — Requests that were rejected.
Open a request to read the reason, the live transcript, and (when Interactive is on) send a question back to the customer. The voice agent speaks that question; the customer’s answer is returned to you.
**Tools → Assists** is where you *configure* who the AI can ask and what they can ask for. **Contact Center → Assists** is where people *work* those live requests.
***
## Review stats and history
Open an Assist to find three tabs:
### Actions
Create, edit, clone, or delete the LLM-callable tasks on this Assist.
### Stats
Counts for the selected date range (defaults to the last 30 days):
* **Total** instances
* **Completed** (with completion rate)
* **Failed**
* **Cancelled**
* **Per action** breakdown (completed / total / failed)
Use this tab to see which actions time out or get cancelled too often — usually a sign that copy, timeouts, or queue staffing need a change.
### History
A paginated list of every instance: action name, status, end reason, and created time. Open a row to read the logs for that request.
***
## Edit, clone, and delete
* **Edit** — Change the Assist name or description from the Assist page. Change an action’s queue from **Update Action**.
* **Clone** — Duplicates the Assist and its actions. Use this to spin up a regional or language-specific variant.
* **Delete** — Archives the Assist. Agents stop receiving its actions. Runtime history is kept.
Deleting an Assist is an archive, not a hard delete. You will not see it on the list, and agents can no longer call its actions, but past instances remain in History.
***
## Best practices
| Recommendation | Why it helps |
| ------------------------------------------------- | ----------------------------------------------------------------------------------------------------- |
| One queue per kind of work | Billing exceptions and order lookups rarely belong on the same queue — put them on different actions. |
| One action per job | `lookup_order` and `approve_refund` should be separate so the model picks the right one. |
| Write the description for the model | “Call this when you cannot find the order with tools” beats “Order lookup.” |
| Keep `assistReason` short and operational | Humans need “Refund \$42 on order 1832, customer received damaged item,” not a transcript dump. |
| Turn **Blocking** on for work that cannot overlap | Approvals and lookups feel broken if the AI chats about something else while waiting. |
| Turn **Cancelable** off for required steps | Identity checks and compliance confirmations should not be skippable. |
| Test delay copy on a real call | Ten seconds of silence feels longer on the phone than in chat. |
| Staff the queue before you enable the action | An Assist with nobody on the queue always hits queue timeout. |
***
## Example: order lookup
A support agent can answer FAQs from the knowledge base, but order systems are behind a desktop the AI cannot reach.
1. Create an Assist named `Order desk`.
2. Add an action named `lookup_order`, pointed at the `Support` queue.
3. Description: `Ask a teammate to look up an order in the order system. Use this when the customer asks for status, tracking, or contents and no tool can retrieve it.`
4. Parameters schema with required `orderId`.
5. Start message: `Give me a moment — I’ll check that order with a colleague.`
6. Assign teammates to the `Support` queue and confirm they can see **Contact Center → Assists**.
During a call, when the customer says “Where is order 1832?”, the model calls `lookup_order`. The caller stays with the AI. A teammate sees the request, looks up the order, and replies. The AI continues with the answer.
***
## Frequently asked questions
Yes. Assists are workspace-scoped. Link the same Assist to every agent that should be able to request that kind of help.
No. Actions are loaded when a conversation starts. New conversations pick up the latest configuration.
Rejecting means the teammate cannot do the work (the caller hears the error line). Closing means the work is done and the AI should continue (the caller hears the human-agent close line).
Tighten the description, mention the action in the agent prompt, and make sure the Assist is linked to that agent. Vague descriptions (“help with orders”) compete with tools and knowledge base.
Confirm the queue has available teammates, they are looking at **Contact Center → Assists**, and the queue timeout is long enough for your staffing. Blocking actions feel slower to callers — consider shorter delay intervals with clearer copy rather than a longer timeout.
Only if **Cancelable** is on. The model then has a cancel tool and the caller hears the user-cancel line.
***
## Related
Connect APIs the agent can call on its own, without a human in the loop.
Hand the live call to a person when the customer needs to speak to someone.
Configure the voice agent that will call your Assist actions.
A worked example of human-in-the-loop help during a live call.
> Need more help? Reach out to our team at [support@oration.ai](mailto:support@oration.ai)