Call Stages

The Ultravox API’s Call Stages functionality allows you to create dynamic, multi-stage conversations. Stages enable more complex and nuanced agent interactions, giving you fine-grained control over the conversation flow.

Each stage can have a new system prompt, a different set of tools, a new voice, an updated conversation history, and more.

​

Understanding Call Stages

Call Stages (“Stages”) provide a way to segment a conversation into distinct phases, each with its own system prompt and potentially different parameters. This enables interactions that can adapt and change focus as the conversation progresses.

Key points to understand about Stages:

Dynamic System Prompts → Stages allow you to give granular system prompts to the model as the conversation progresses.

Flexibility → You have full control to determine when and how you want the conversation to progress to the next stage.

Thoughtful Design → Implementing stages requires careful planning and consideration of the conversation structure. Consider how to handle stage transitions and test thoroughly to ensure a natural flow to the conversation.

Maintain Context → Think about how the agent will maintain context about the user between stages if you need to ensure a coherent conversation.

​

Creating and Managing Stages

To implement Call Stages in your Ultravox application, follow these steps:

​

Example Stage Change Implementation

Here’s a basic example of how to implement a new call stage.

First, we create a tool that is responsible for changing stages:

function changeStage(requestBody) {
  const responseBody = {
    systemPrompt: "...", // new prompt
    ..., // other properties to change, like the voice
    // You may optionally also set toolResultText, which will be the content
    // of the tool result message in conversation history. The tool result
    // will be the most recent message the model sees during its next generation
    // unless you set initialMessages. Defaults to "OK".
    toolResultText: "(New Stage) Next, focus on..."
  };

  return {
    body: responseBody,
    headers: {
      'X-Ultravox-Response-Type': 'new-stage'
    }
  };
}

We also need to ensure that we have instructed our agent to use the tool and that we add the tool to our selectedTools during the creation of the call.

// Instruct the agent on how to use the stage management tool
// Add the tool to selectedTools
{
  systemPrompt: "You are a helpful assistant...you have access to a tool called changeStage...",
  ...
  selectedTools: [
    {
      "temporaryTool": {
        "modelToolName": "changeStage",
        "description": ...,
        "dynamicParameters": [...],
      }
    }
  ]
}

​

Ultravox API Implications

If you are not using stages for a call, retrieving calls or call messages via the API (e.g. List Calls) works as expected.

However, if you are using call stages then you most likely want to use the stage-centric API endpoints to get stage-specific settings, messages, etc.

Use List Call Stages to get all the stages for a given call.

​

Stages Call Properties

Unless overridden, stages inherit all properties of the existing call.

Here is the list of all call properties that can and cannot be changed during a new stage:

​

Use Cases for Call Stages

Call Stages are particularly useful for complex conversational flows. Here are some example scenarios:

Data Gathering → Scenarios where the agent needs to collect a lot of data. Examples: job applications, medical intake forms, applying for a mortgage.

Here are potential stages for a Mortgage Application:

• Stage 1: Greeting and basic information gathering
• Stage 2: Financial assessment
• Stage 3: Property evaluation
• Stage 4: Presentation of loan options
• Stage 5: Hand-off to loan officer

Switching Contexts → Scenarios where the agent needs to navigate different contexts. Examples: customer support escalation, triaging IT issues.

Let’s consider what the potential stages might be for Customer Support:

• Stage 1: Initial greeting and problem identification
• Stage 2: Troubleshooting
• Stage 3: Resolution or escalation (to another stage or to a human support agent)

​

Conclusion

Call Stages in the Ultravox API give you the ability to create adaptive conversations for more complex scenarios like data gathering or switching contexts. By allowing granular control over system prompts and conversation parameters at different stages, you can create more dynamic and context-aware interactions.