Merge pull request #29 from fixie-ai/ben-add-stages

adding call stages

docs/astro.config.mjs

@@ -35,8 +35,12 @@ export default defineConfig({
         link: 'guides/quickstart'
       },
       {
-        label: 'Phone Calls',
-        link: 'guides/phonecalls'
+        label: 'Call Stages',
+        link: 'guides/stages'
+      },
+      {
+        label: 'Ultravox + Telephony',
+        link: 'guides/telephony'
       },
       {
         label: 'Tools in Ultravox',

docs/src/content/codesnippets/call-stage-prompt.txt

@@ -0,0 +1,15 @@
+// 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": [...],
+      }
+    }
+  ]
+}

docs/src/content/codesnippets/call-stage.txt

@@ -0,0 +1,13 @@
+function changeStage(requestBody) {
+  const responseBody = {
+    systemPrompt: "...", // new prompt
+    ... // other properties
+  };
+
+  return {
+    body: responseBody,
+    headers: {
+      'X-Ultravox-Response-Type': 'new-stage'
+    }
+  };
+}

docs/src/content/docs/guides/stages.mdx

@@ -0,0 +1,150 @@
+---
+title: "Call Stages"
+description: Use Ultravox API to create dynamic, multi-stage conversations.
+---
+
+import { Steps, Code } from '@astrojs/starlight/components';
+
+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.
+
+:::note[Advanced Feature]
+Stages require planning and careful implementation. Stages are likely not required for simple use cases.
+:::
+
+## Creating and Managing Stages
+
+To implement Call Stages in your Ultravox application, follow these steps:
+
+#### 1. Plan Your Stages
+Determine the different phases of your conversation and what prompts or parameters should change at each stage.
+
+#### 2. Implement a Stage Change Tool
+
+Create a custom tool that will trigger stage changes when called. This tool should:
+
+* Respond with a header called `X-Ultravox-Response-Type` set to `new-stage`. This creates the new stage.
+* Provide the updated parameters (e.g., system prompt, tools, voice) for the new stage in the response body.
+* For [client tools](../sdk#client-tools), a new stage can be started by returning an object that has `responseType="new-stage"`.
+
+Unless overridden, stages inherit all properties of the existing call. See [Stages Call Properties](#stages-call-properties) for the list of call properties that can be changed.
+
+#### 3. Configure Stage Transitions
+
+* Prompt the agent to use the stage change tool at appropriate points in the conversation.
+* Ensure the stage change tool is part of `selectedTools` when creating the call as well as during new stages (if needed).
+* Update your system prompt as needed to instruct the agent on when/how to use the stage change tool.
+
+:::caution[Things to Remember]
+  * New stages inherit all properties from the previous stage unless explicitly overridden.
+  * Refer to [Stages Call Properties](#stages-call-properties) to understand which call properties can be changed as part of a new stage.
+  * Test your stage transitions thoroughly to ensure the conversation flows naturally.
+:::
+
+### 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:
+
+import callStageTool from '../../codesnippets/call-stage.txt?raw';
+export const title = "Basic stage change tool"
+
+<Code code={callStageTool} lang="js" title={title} />
+
+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.
+
+import callStage from '../../codesnippets/call-stage-prompt.txt?raw';
+export const cstitle = "Updating our systemPrompt and selectedTools"
+
+<Code code={callStage} lang="js" title={cstitle} />
+
+
+:::tip[Inheritance]
+New stages inherit all properties from the previous stage. You can selectively overwrite properties as needed when defining a new stage. See the [above table](#2-implement-a-stage-change-tool) for more.
+:::
+
+## Ultravox API Implications
+
+If you are not using stages for a call, retrieving calls or call messages via the API (e.g. `GET /api/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 `GET /api/calls/{call_id}/stages` to get all the stages for a given call.
+
+| Ultravox API                 | Description              | Stage-Centric Equivalent                           | Description               |
+|----------------------------- | ------------------------ | -------------------------------------------------- | ------------------------- |
+| `/calls/{call_id}`           | Get a call               | `/calls/{call_id}/stages/{call_stage_id}`          | Get the call stage        |
+| `/calls/{call_id}/messages`  | Get messages for a call  | `/calls/{call_id}/stages/{call_stage_id}/messages` | Get message for the stage |
+| `/calls/{call_id}/tools`     | Get tools for a call     | `/calls/{call_id}/stages/{call_stage_id}/tools`    | Get tools for the stage   |
+
+
+## Stages Call Properties
+
+:::tip
+The schema used for a Stages response body is a subset of the request body schema used when creating a new call. The response body must contain the new values for any properties you want to change in the new stage.
+:::
+
+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:
+
+| property            | change with new stage? |
+|-------------------- | ---------------------- |
+| systemPrompt        | Yes                    |
+| temperature         | Yes                    |
+| voice               | Yes                    |
+| languageHint        | Yes                    |
+| initialMessages     | Yes                    |
+| selectedTools       | Yes                    |
+| firstSpeaker        | No                     |
+| model               | No                     |
+| joinTimeout         | No                     |
+| maxDuration         | No                     |
+| timeExceededMessage | No                     |
+| inactivityMessages  | No                     |
+| medium              | No                     |
+| initiator           | No                     |
+| recordingEnabled    | No                     |
+
+
+## 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.

docs/src/content/docs/guides/phonecalls.mdx → docs/src/content/docs/guides/telephony.mdx

@@ -1,12 +1,10 @@
 ---
-title: "Phone Calls"
+title: "Using Ultravox with Phones"
 description: Use Ultravox API to make and receive calls from regular phones via Twilio.
 ---
 
 import { Steps, Tabs, TabItem } from '@astrojs/starlight/components';
 
-## Overview
-
 The Ultravox API allows you to create AI-powered voice applications that can interact with regular phone numbers. This enables Ultravox AI agents to make outgoing calls and receive incoming calls from traditional phone networks.
 
 :::note[Twilio Support]

docs/src/content/docs/sdk.mdx

@@ -98,7 +98,7 @@ Sets the agent's output medium for future utterances. If the agent is currently
 
 | parameter        | description                                 |
 |-------------- | ------------------------------------------- |
-| medium | How replies are communicated. Must be either `'text'` or `'voice'`.
+| medium | How replies are communicated. Must be either `'text'` or `'voice'`. |
 
 #### registerToolImplementation()
 ```ts