Skip to main content

Background actions

Background actions delegate a bounded task to a separate agent that can reason over the conversation, use knowledge, and call selected actions before returning a concise result to your realtime agent.

Background actions are synchronous for the agent that invokes them: the agent receives the result only after the background task finishes. Use them for work that benefits from additional reasoning or several steps. A task accepted during a call can continue after the caller disconnects, and a post-call wrap-up can also start a background task.

info

Background actions are in beta and enabled per workspace. If the action type is not available in your action picker, contact Stellar to have it enabled.

Add a background action​

Open your agent's Actions tab, click + Add action, select Add agent action, and choose Background action.

Configure the ordinary action Name and Description first. The realtime agent uses these fields to decide when to delegate the task. The background action then adds task instructions, tool selection, and a step limit:

  • Instructions tell the background agent how to complete the task and what it must return to the realtime agent.
  • Tools available to background agent grants the background agent access to selected actions already attached to this agent.

Expand Advanced, then use Phases to choose when the action is available. New background actions default to In call. Select Post call to make the action available during post-conversation wrap-up, or select both phases to use it in either place.

Expand Advanced and set Maximum steps between 3 and 24 to control how many model and tool-use steps the background agent may take. The default is 6. Higher values are useful for tasks that retrieve several knowledge documents, but can consume more tokens and still remain subject to the 45-second deadline.

In Instructions, type @ to reference a selected tool, or knowledge tools and accurate transcription when enabled for your agent. When knowledge is enabled, you can mention search_knowledge and get_knowledge_document without selecting them under Tools available to background agent. Their availability still depends on the current state's knowledge permissions. A mention helps explain your workflow, but it doesn't grant access: actions and MCP tools must be selected in their respective tool selectors.

Background actions can use these actions when they don't require approval:

  • API call
  • Static response
  • Send text message

They can't use handovers, end-call actions, client actions, authentication actions, resume-flow actions, or other background actions.

A selected tool must be available in every phase selected for the background action. For example, a background action configured for both In call and Post call can select only tools that are also available in both phases.

Stellar checks these rules when you save, publish, or import the agent, and the error names the background action and the selected tool to fix. A selection that later stops qualifying, for example because the tool's phases changed or it was deleted, does not break a call: the background agent skips that tool until you update the selection.

Select MCP tools​

MCP tools available to background agent grants the background agent access to MCP tools this agent already has enabled. The field appears once the agent is connected to an MCP server with at least one enabled tool.

The background agent can only use an MCP tool that is allowed in the state the realtime agent was in when it delegated the task. A later state change during the run does not widen or narrow that access.

MCP tools are unavailable during post-conversation wrap-up, so a background action can select them only when its Phases are In call alone. Adding Post call disables the field and clears any MCP selection.

Each MCP tool is offered as server / tool and is advertised to the background agent under its namespaced name, for example mcp_orders__cancel_order. If that name is already taken by another selected tool, the background agent sees a prefixed variant of it instead. Selecting an MCP tool here doesn't change whether the realtime agent can use it.

Configure a background-only tool​

An eligible API call, static response, or send text message action can be made unavailable to the realtime agent while remaining available to a background action. Open the action, expand Advanced, and turn off Available to realtime agent. The action shows a Background only label in the Actions list.

Turning off realtime availability does not grant the background agent access. In the background action, select the tool under Tools available to background agent. That explicit selection is the authority for the background agent to use it. Removing the tool from that selection removes background access even when it remains marked Background only.

The setting is available only for eligible API call, static response, and send text message actions that do not require approval. It is not available for MCP tools.

Provide input to the background agent​

When the realtime agent invokes a background action, it supplies one required context string containing the caller's goal, relevant facts already gathered, uncertainties, and desired outcome. The background agent also receives the safe conversation context automatically, so you don't need to copy the whole transcript into this field. That context is a snapshot taken when the task starts. It includes what the agent heard, including any DTMF inputs, along with earlier tool calls and their results and exposed variables.

The input is intentionally natural language rather than a configurable parameters schema. For example, the realtime agent might provide:

The caller wants to cancel order ORD-123456. They confirmed the delivery address is Keizersgracht 123. Cancel only if the order has not shipped, and report the cancellation status and confirmation number.

Use the background action's Description to tell the realtime agent when to call it and what facts to include. Use Instructions to tell the background agent how to work and exactly what it should return. For example:

Look up the order before attempting cancellation. Do not cancel an order that has shipped. Return the order number, whether cancellation succeeded, and the cancellation confirmation number. If the order number is missing or ambiguous, request clarification.

Selected tools keep their own parameters schemas. The background agent uses those schemas when it calls them, so required fields remain structured and validated even though the outer handoff is natural language.

Results returned to the realtime agent​

The background agent ends each run with success or a request for clarification. Runner failures return an error instead. These results are passed to the realtime agent as the background action's function output.

Success​

On success, result contains the concise natural-language result requested in Instructions:

{
  "success": true,
  "result": "Order ORD-123456 was cancelled. The confirmation number is CN-90817."
}

The background agent sees selected action outputs while it works, but those outputs aren't returned automatically. Tell it which statuses, identifiers, or values the realtime agent needs.

Needs clarification​

When required information is missing or ambiguous, the background agent can return a caller-facing question and a short summary:

{
  "success": false,
  "needs_clarification": true,
  "question": "Which of your two active orders would you like to cancel?",
  "summary": "Two active orders were found and no order number was provided."
}

The realtime agent uses the question conversationally. After the caller answers, it can invoke the background action again with the new information.

Error​

If the runner times out, is cancelled, exceeds its limits, or encounters a provider failure, the realtime agent receives an error:

{
  "success": false,
  "error": "The background task did not complete.",
  "execution_started": false
}

execution_started indicates whether a selected action may already have run. When it is true, the realtime agent should not assume that retrying is safe. A competing background run can instead return background_busy: true; only one background action runs at a time in a conversation.

Runtime limits​

A background run has a 45-second deadline and uses the configured Maximum steps for both its model-turn and tool-call limits. The default is 6 and the allowed range is 3–24. Each selected API call has its own 15-second timeout, and each MCP tool call its own 30-second timeout. An API call that starts before the runner deadline is allowed to finish, but the runner doesn't start another model turn after its deadline. Text-message sends use the time remaining in the background run.

The background runner doesn't automatically retry actions after timeouts or uncertain transport failures because the action may already have produced a side effect. Configure successful-call limits on sensitive API actions and implement idempotency in the receiving API when duplicate execution would be harmful.

If the caller disconnects while a background action is running, the accepted run continues under the same deadline while post-call wrap-up begins. Stellar waits for its terminal result and activity to be saved before completing the conversation. Only one background action can run at a time, so a post-call invocation can receive background_busy: true if an in-call run is still active.

Background runs are process-local. They survive caller hangup, but they aren't durable jobs and can't recover from a service restart.

Test a background action​

Use the Playground to trigger the background action. Its timeline shows where the realtime agent started the task, live progress in an expandable Agent activity area, and where the completed result returned to the conversation. Activity from the realtime agent can continue in the main timeline while the background action runs.

Expand any activity step to inspect its input, output, outcome, and duration. Transcription and text-message activity performed by the background agent appears under the step that initiated it instead of as unrelated main-timeline activity. After the conversation ends, the saved timeline uses the completed activity snapshot for the same view.

Test success and clarification paths separately. Verify that the success result contains every value the realtime agent needs, and that clarification questions are suitable to ask the caller directly.

Next steps​