feat(agent): finish Phase 1 with examples and integration tests

  Wraps up Phase 1 of the spec-coverage rollout:

    - Agent::start_at_url(&str) — public URL override on the agent
      sub-client. start() now delegates to it. Used by self-hosted
      deployments and the new integration tests.

    - ThinkSettings and ThinkFunction gain builder methods so external
      consumers can construct them around the #[non_exhaustive] marker:
      ThinkSettings::{with_endpoint, with_functions, with_function,
      with_prompt, with_context_length} and
      ThinkFunction::{new, with_endpoint}.

    - Three new examples in examples/agent/websocket/:
        * function_calling.rs — client-side function definition,
          FunctionCallRequest dispatch, FunctionCallResponse reply.
        * dynamic_provider_swap.rs — UpdateSpeak mid-session to swap
          the Aura voice while the connection stays open.
        * microphone_agent.rs — full two-way audio session via cpal
          (capture) and rodio (playback). Audio I/O patterns borrowed
          from microphone_flux.rs and text_to_speech_to_stream.rs.

    - tests/agent_integration.rs uses a tokio-tungstenite mock server
      to exercise the full session lifecycle end-to-end:
      Welcome → client Settings → SettingsApplied → ConversationText →
      binary audio → AgentAudioDone → client close. The mock injects
      dg-request-id on the upgrade response and asserts on the
      serialized Settings the client sends. A second test verifies
      that unknown server JSON events round-trip through the
      AgentResponse::Unknown(Value) forward-compat variant.

  136 tests pass (lib + doctest + integration), all 4 examples
  build, both with default features and with --no-default-features
  --features agent.

Author: GregHolmes

Cargo.toml

@@ -134,3 +134,18 @@ required-features = ["speak"]
 name = "agent_simple"
 path = "examples/agent/websocket/simple_agent.rs"
 required-features = ["agent"]
+
+[[example]]
+name = "agent_function_calling"
+path = "examples/agent/websocket/function_calling.rs"
+required-features = ["agent"]
+
+[[example]]
+name = "agent_dynamic_provider_swap"
+path = "examples/agent/websocket/dynamic_provider_swap.rs"
+required-features = ["agent"]
+
+[[example]]
+name = "agent_microphone"
+path = "examples/agent/websocket/microphone_agent.rs"
+required-features = ["agent"]

examples/agent/websocket/dynamic_provider_swap.rs

@@ -0,0 +1,157 @@
+/* Expected result from running this example program.
+Connected. dg-request-id: Some(<uuid>)
+Welcome request_id: <uuid>
+Settings applied
+Conversation (Assistant): I'm using my first voice.
+[5s elapsed] Sending UpdateSpeak to switch to a different Aura-2 voice...
+SpeakUpdated
+Conversation (Assistant): Now my voice has changed.
+*/
+
+//! Dynamic provider swap example.
+//!
+//! Connects with one Speak provider (`aura-2-thalia-en`), then 5 seconds
+//! after the agent's initial greeting, sends an `UpdateSpeak` message to
+//! swap the voice to `aura-2-zeus-en`. Demonstrates that providers can
+//! be changed mid-session without dropping the WebSocket.
+//!
+//! No real audio I/O — the example surfaces the JSON message round-trip
+//! and the `SpeakUpdated` confirmation event.
+//!
+//! Run with:
+//!
+//! ```bash
+//! DEEPGRAM_API_KEY=<your-key> \
+//!     cargo run --features agent --example agent_dynamic_provider_swap
+//! ```
+
+use std::env;
+use std::time::Duration;
+
+use futures::stream::StreamExt;
+
+use deepgram::agent::{
+    audio::{AudioConfig, AudioInput, AudioInputEncoding},
+    listen::{AgentListenProvider, AgentListenSettings, DeepgramListenV2Provider},
+    messages::UpdateSpeakMessage,
+    settings::{AgentConfig, InlineAgentConfig, SettingsMessage},
+    speak::{DeepgramSpeakModel, DeepgramSpeakProvider, SpeakProvider, SpeakSettings},
+    think::{OpenAiModel, OpenAiThinkProvider, ThinkProvider, ThinkSettings},
+    AgentEvent, AgentResponse,
+};
+use deepgram::{Deepgram, DeepgramError};
+
+static SESSION_DURATION: Duration = Duration::from_secs(60);
+static SWAP_AFTER: Duration = Duration::from_secs(5);
+
+#[tokio::main]
+async fn main() -> Result<(), DeepgramError> {
+    let api_key = env::var("DEEPGRAM_API_KEY").expect("DEEPGRAM_API_KEY environment variable");
+
+    let dg = Deepgram::new(&api_key)?;
+    let (mut handle, mut events) = dg.agent().start().await?;
+
+    println!("Connected. dg-request-id: {:?}", handle.request_id());
+
+    let settings = SettingsMessage::new(
+        AudioConfig::new(
+            Some(AudioInput::new(AudioInputEncoding::Linear16, 16_000)),
+            None,
+        ),
+        AgentConfig::inline(
+            InlineAgentConfig::from_parts(
+                AgentListenSettings::new(AgentListenProvider::DeepgramV2(
+                    DeepgramListenV2Provider::new("flux-general-en"),
+                )),
+                ThinkSettings::new(ThinkProvider::OpenAi(OpenAiThinkProvider::new(
+                    OpenAiModel::Gpt4oMini,
+                ))),
+                SpeakSettings::new(SpeakProvider::Deepgram(DeepgramSpeakProvider::new(
+                    DeepgramSpeakModel::Aura2ThaliaEn,
+                ))),
+            )
+            .with_greeting("I'm using my first voice."),
+        ),
+    );
+    handle.send_settings(settings).await?;
+
+    let timeout = tokio::time::sleep(SESSION_DURATION);
+    tokio::pin!(timeout);
+    let swap_timer = tokio::time::sleep(SWAP_AFTER);
+    tokio::pin!(swap_timer);
+    let mut swapped = false;
+
+    loop {
+        tokio::select! {
+            _ = &mut timeout => {
+                println!("\nSession duration reached, closing.");
+                break;
+            }
+            _ = &mut swap_timer, if !swapped => {
+                println!(
+                    "\n[{}s elapsed] Sending UpdateSpeak to switch to a different Aura-2 voice...",
+                    SWAP_AFTER.as_secs()
+                );
+                let new_speak = SpeakSettings::new(SpeakProvider::Deepgram(
+                    DeepgramSpeakProvider::new(DeepgramSpeakModel::Aura2ZeusEn),
+                ));
+                handle
+                    .send_update_speak(UpdateSpeakMessage::one(new_speak))
+                    .await?;
+                // Optional follow-up: inject an utterance so the agent
+                // speaks again with the new voice. Without this the user
+                // would have to talk for the swap to be audible.
+                handle
+                    .send_inject_agent_message(
+                        deepgram::agent::messages::InjectAgentMessageMessage::new(
+                            "Now my voice has changed.",
+                        ),
+                    )
+                    .await?;
+                swapped = true;
+            }
+            event = events.next() => {
+                match event {
+                    Some(Ok(AgentEvent::Json(response))) => match response {
+                        AgentResponse::Welcome(w) => {
+                            println!("Welcome request_id: {}", w.request_id);
+                        }
+                        AgentResponse::SettingsApplied(_) => {
+                            println!("Settings applied");
+                        }
+                        AgentResponse::SpeakUpdated(_) => {
+                            println!("SpeakUpdated");
+                        }
+                        AgentResponse::ConversationText(c) => {
+                            println!("Conversation ({:?}): {}", c.role, c.content);
+                        }
+                        AgentResponse::Error(e) => {
+                            eprintln!("Error [{}]: {}", e.code, e.description);
+                            break;
+                        }
+                        AgentResponse::Warning(w) => {
+                            println!("Warning [{}]: {}", w.code, w.description);
+                        }
+                        _ => {}
+                    },
+                    Some(Ok(AgentEvent::Audio(_))) => {
+                        // Discard audio for brevity; the playback path is
+                        // demonstrated in the microphone example.
+                    }
+                    Some(Ok(_)) => {} // AgentEvent #[non_exhaustive]
+                    Some(Err(err)) => {
+                        eprintln!("Stream error: {err}");
+                        break;
+                    }
+                    None => {
+                        println!("Server closed connection.");
+                        break;
+                    }
+                }
+            }
+        }
+    }
+
+    handle.close().await?;
+    Ok(())
+}

examples/agent/websocket/function_calling.rs

@@ -0,0 +1,200 @@
+/* Expected result from running this example program.
+Connected. dg-request-id: Some(<uuid>)
+Welcome request_id: <uuid>
+Settings applied
+Conversation (Assistant): Hi! Ask me about the weather.
+... (after a user injection asking about NYC)
+FunctionCallRequest: get_weather (id=fc_1, client_side=true)
+  arguments: {"city":"New York"}
+  → responding with: {"temperature":72,"condition":"sunny"}
+Conversation (Assistant): It's 72 and sunny in New York.
+*/
+
+//! Function-calling Voice Agent example.
+//!
+//! Configures an agent with a single client-side function (`get_weather`),
+//! injects a synthetic user utterance asking about the weather, and
+//! responds to the resulting [`FunctionCallRequest`] with a canned
+//! `FunctionCallResponse`.
+//!
+//! No real audio I/O — the example exercises the JSON message round-trip
+//! and the function-call protocol on its own.
+//!
+//! Run with:
+//!
+//! ```bash
+//! DEEPGRAM_API_KEY=<your-key> \
+//!     cargo run --features agent --example agent_function_calling
+//! ```
+
+use std::env;
+use std::time::Duration;
+
+use futures::stream::StreamExt;
+use serde_json::json;
+
+use deepgram::agent::messages::FunctionCallResponseMessage;
+use deepgram::agent::{
+    audio::{AudioConfig, AudioInput, AudioInputEncoding},
+    listen::{AgentListenProvider, AgentListenSettings, DeepgramListenV2Provider},
+    settings::{AgentConfig, InlineAgentConfig, SettingsMessage},
+    speak::{DeepgramSpeakModel, DeepgramSpeakProvider, SpeakProvider, SpeakSettings},
+    think::{OpenAiModel, OpenAiThinkProvider, ThinkFunction, ThinkProvider, ThinkSettings},
+    AgentEvent, AgentResponse,
+};
+use deepgram::{Deepgram, DeepgramError};
+
+static SESSION_DURATION: Duration = Duration::from_secs(60);
+
+#[tokio::main]
+async fn main() -> Result<(), DeepgramError> {
+    let api_key = env::var("DEEPGRAM_API_KEY").expect("DEEPGRAM_API_KEY environment variable");
+
+    let dg = Deepgram::new(&api_key)?;
+    let (mut handle, mut events) = dg.agent().start().await?;
+
+    println!("Connected. dg-request-id: {:?}", handle.request_id());
+
+    // No `endpoint` → executed client-side. The server emits a
+    // FunctionCallRequest and waits for our FunctionCallResponse.
+    let weather_function = ThinkFunction::new(
+        "get_weather",
+        "Look up the current weather for a city.",
+        json!({
+            "type": "object",
+            "properties": {
+                "city": {
+                    "type": "string",
+                    "description": "City name, e.g. \"New York\""
+                }
+            },
+            "required": ["city"]
+        }),
+    );
+
+    let think = ThinkSettings::new(ThinkProvider::OpenAi(OpenAiThinkProvider::new(
+        OpenAiModel::Gpt4oMini,
+    )))
+    .with_function(weather_function)
+    .with_prompt(
+        "You are a helpful weather assistant. Use the get_weather function \
+         when the user asks about weather.",
+    );
+
+    let settings = SettingsMessage::new(
+        AudioConfig::new(
+            Some(AudioInput::new(AudioInputEncoding::Linear16, 16_000)),
+            None,
+        ),
+        AgentConfig::inline(
+            InlineAgentConfig::from_parts(
+                AgentListenSettings::new(AgentListenProvider::DeepgramV2(
+                    DeepgramListenV2Provider::new("flux-general-en"),
+                )),
+                think,
+                SpeakSettings::new(SpeakProvider::Deepgram(DeepgramSpeakProvider::new(
+                    DeepgramSpeakModel::Aura2ThaliaEn,
+                ))),
+            )
+            .with_greeting("Hi! Ask me about the weather."),
+        ),
+    );
+    handle.send_settings(settings).await?;
+
+    // Wait for SettingsApplied, then inject a synthetic user message
+    // so the agent has something to respond to without us needing a mic.
+    let mut injected = false;
+
+    let timeout = tokio::time::sleep(SESSION_DURATION);
+    tokio::pin!(timeout);
+
+    loop {
+        tokio::select! {
+            _ = &mut timeout => {
+                println!("\nSession duration reached, closing.");
+                break;
+            }
+            event = events.next() => {
+                match event {
+                    Some(Ok(AgentEvent::Json(response))) => match response {
+                        AgentResponse::Welcome(w) => {
+                            println!("Welcome request_id: {}", w.request_id);
+                        }
+                        AgentResponse::SettingsApplied(_) => {
+                            println!("Settings applied");
+                            if !injected {
+                                injected = true;
+                                handle
+                                    .send_inject_user_message(
+                                        deepgram::agent::messages::InjectUserMessageMessage::new(
+                                            "What's the weather in New York?",
+                                        ),
+                                    )
+                                    .await?;
+                            }
+                        }
+                        AgentResponse::ConversationText(c) => {
+                            println!("Conversation ({:?}): {}", c.role, c.content);
+                        }
+                        AgentResponse::FunctionCallRequest(req) => {
+                            for call in &req.functions {
+                                println!(
+                                    "FunctionCallRequest: {} (id={}, client_side={})",
+                                    call.name, call.id, call.client_side
+                                );
+                                println!("  arguments: {}", call.arguments);
+
+                                if call.client_side && call.name == "get_weather" {
+                                    // Canned response — in a real app, parse
+                                    // call.arguments and dispatch to your
+                                    // function implementation.
+                                    let result =
+                                        json!({"temperature": 72, "condition": "sunny"});
+                                    println!("  → responding with: {result}");
+                                    handle
+                                        .send_function_call_response(
+                                            FunctionCallResponseMessage::with_id(
+                                                call.id.clone(),
+                                                call.name.clone(),
+                                                result.to_string(),
+                                            ),
+                                        )
+                                        .await?;
+                                }
+                            }
+                        }
+                        AgentResponse::AgentAudioDone(_) => {
+                            // After the agent finishes its audio response we
+                            // could end the demo. For brevity we just log.
+                            println!("Agent audio done");
+                        }
+                        AgentResponse::Error(e) => {
+                            eprintln!("Error [{}]: {}", e.code, e.description);
+                            break;
+                        }
+                        AgentResponse::Warning(w) => {
+                            println!("Warning [{}]: {}", w.code, w.description);
+                        }
+                        _ => {}
+                    },
+                    Some(Ok(AgentEvent::Audio(_))) => {
+                        // Audio chunks arrive between AgentStartedSpeaking and
+                        // AgentAudioDone. Discarded here.
+                    }
+                    Some(Ok(_)) => {} // AgentEvent #[non_exhaustive]
+                    Some(Err(err)) => {
+                        eprintln!("Stream error: {err}");
+                        break;
+                    }
+                    None => {
+                        println!("Server closed connection.");
+                        break;
+                    }
+                }
+            }
+        }
+    }
+
+    handle.close().await?;
+    Ok(())
+}