Assistant Overrides: Permanent + Transient Configurations

Overview

Assistant configuration in Sulus can be permanent (a stored assistant referenced by ID), transient (a full configuration sent inline with the call), or a mix of both within a squad. Understanding these three approaches lets you decide how much of your assistant's configuration should live in a saved record versus be assembled dynamically for each call.

A permanent assistant is a stored configuration referenced by its assistantId. You can customize a stored assistant for a single call using assistantOverrides, without modifying the saved configuration itself. This is useful when you want a stable base assistant but need to swap in call-specific values, tools, or settings.

{
  "assistantId": "saved-assistant-id",
  "assistantOverrides": {
    "variableValues": {
      "customerName": "Jane Smith",
      "accountId": "12345"
    },
    "toolIds": ["tool-id-1", "tool-id-2"]
  }
}

The stored assistant record is untouched; the overrides apply only to this call.

A transient assistant is a complete configuration passed inline as an assistant object instead of referencing a stored assistantId. Nothing about it is saved — the entire configuration exists only for the duration of that call.

{
  "assistant": {
    "name": "One-Off Support Agent",
    "model": {
      "provider": "openai",
      "model": "gpt-4o",
      "messages": [
        { "role": "system", "content": "You are a temporary support agent handling a single promotional campaign." }
      ]
    },
    "voice": {
      "provider": "azure",
      "voiceId": "en-US-AriaNeural"
    }
  }
}

Transient assistants are ideal for fully dynamic, one-off configurations that don't warrant a saved record at all.

A squad can mix permanent and transient assistants among its members. For example, a permanent receptionist assistant can hand off to a transient, purpose-built assistant assembled just for that handoff:

{
  "squad": {
    "members": [
      {
        "assistantId": "permanent-receptionist-assistant-id",
        "assistantDestinations": [
          { "type": "assistant", "assistantName": "technical-support" }
        ]
      },
      {
        "assistant": {
          "name": "technical-support",
          "model": {
            "provider": "openai",
            "model": "gpt-4o",
            "messages": [
              { "role": "system", "content": "You are a technical support specialist. The customer has a high priority issue." }
            ]
          },
          "voice": { "provider": "11labs", "voiceId": "technical-voice-id" }
        }
      }
    ]
  }
}

For inbound calls, your server can return either a permanent or a transient assistant in response to an assistant-request webhook, allowing you to decide dynamically at call time.

Returning a permanent assistant by ID:

{
  "assistantId": "saved-assistant-id"
}

Returning a fully transient assistant inline:

{
  "assistant": {
    "name": "Dynamic Inbound Agent",
    "model": {
      "provider": "openai",
      "model": "gpt-4o",
      "messages": [
        { "role": "system", "content": "You are answering an inbound call for a caller whose identity was just looked up by our server." }
      ]
    },
    "voice": { "provider": "azure", "voiceId": "en-US-AriaNeural" }
  }
}

• Use permanent assistants with assistantOverrides when you want a stable, reviewable base configuration that still needs per-call personalization, such as inserting a customer's name or swapping a tool.
• Use fully transient assistants for truly one-off or highly dynamic scenarios, such as A/B testing a new prompt or voice without creating a saved record for every variant.
• Avoid embedding sensitive data directly in a transient configuration. Because the full configuration is sent inline with the API request, it is visible in that request. Prefer a permanent assistant with server-side variable injection for anything sensitive.