feat(agent): add REST CRUD for configurations, variables, think models

  Phase 5 of the spec-coverage rollout — the Agent product's REST
  surface, pairing with the WebSocket landed in Phase 1.

  Eleven endpoints across three sub-clients reachable from
  `dg.agent()`:

    agent.think_models()                              (1 endpoint)
    agent.configurations()                            (5 endpoints)
    agent.variables()                                 (5 endpoints)

  Highlights:

    - AgentConfigurations::create accepts a JSON-encoded `config`
      string per spec. CreateAgentConfigurationRequest::from_inline
      serializes a typed InlineAgentConfig (from Phase 1) for you,
      bridging the typed WS Settings types and the REST CRUD.
    - AgentConfigurations::update_metadata is documented as the only
      way to change a saved config; the config itself is immutable
      server-side per spec.
    - AgentVariables::update takes serde_json::Value so callers can
      pass any JSON type. The DG_<NAME> key convention is documented
      but not enforced — the server validates.
    - AgentThinkModels::list hits agent.deepgram.com (not the API
      host) to match the spec's server declaration.

  Internal: Agent<'a>'s inner field is now `pub` (matching
  Transcription / Speak), so sibling files in src/agent/ can borrow
  &Deepgram directly. The rest of the WS surface is unchanged.

  Two examples under examples/agent/rest/:
    - configurations.rs: full lifecycle from typed inline config to
      create -> list -> update metadata -> delete.
    - variables.rs: CRUD on a DG_ variable, plus think-models catalog.

  11 new tests pass; 140 total. All feature combinations build clean.

Author: GregHolmes

Cargo.toml

@@ -185,3 +185,13 @@ required-features = ["agent"]
 name = "agent_microphone"
 path = "examples/agent/websocket/microphone_agent.rs"
 required-features = ["agent"]
+
+[[example]]
+name = "agent_configurations"
+path = "examples/agent/rest/configurations.rs"
+required-features = ["agent"]
+
+[[example]]
+name = "agent_variables"
+path = "examples/agent/rest/variables.rs"
+required-features = ["agent"]

examples/agent/rest/configurations.rs

@@ -0,0 +1,89 @@
+/* Expected result from running this example program.
+Created agent: <uuid> (config_keys: ["language", "listen", "speak", "think"])
+Listed 1 agents on the project.
+Updated metadata: {"env": "staging"}
+Deleted agent <uuid>.
+*/
+
+//! Saved-configuration CRUD walkthrough for the Agent REST API.
+//!
+//! Creates a configuration from an [`InlineAgentConfig`], lists the
+//! project's agents, updates the new entry's metadata, then deletes
+//! it.
+//!
+//! Run with:
+//!
+//! ```bash
+//! DEEPGRAM_API_KEY=<your-key> \
+//! DEEPGRAM_PROJECT_ID=<project-uuid> \
+//!     cargo run --features agent --example agent_configurations
+//! ```
+
+use std::env;
+
+use deepgram::agent::configurations::{
+    CreateAgentConfigurationRequest, UpdateAgentMetadataRequest,
+};
+use deepgram::agent::settings::InlineAgentConfig;
+use deepgram::agent::{
+    listen::{AgentListenProvider, AgentListenSettings, DeepgramListenV2Provider},
+    speak::{DeepgramSpeakModel, DeepgramSpeakProvider, SpeakProvider, SpeakSettings},
+    think::{OpenAiModel, OpenAiThinkProvider, ThinkProvider, ThinkSettings},
+};
+use deepgram::{Deepgram, DeepgramError};
+
+#[tokio::main]
+async fn main() -> Result<(), DeepgramError> {
+    let api_key = env::var("DEEPGRAM_API_KEY").expect("DEEPGRAM_API_KEY environment variable");
+    let project_id =
+        env::var("DEEPGRAM_PROJECT_ID").expect("DEEPGRAM_PROJECT_ID environment variable");
+
+    let dg = Deepgram::new(&api_key)?;
+    let configs = dg.agent().configurations();
+
+    // Build a typed inline config and let the SDK serialize it to the
+    // string the API expects.
+    let 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("Hello! Configured by the Rust SDK example.");
+
+    let create_request = CreateAgentConfigurationRequest::from_inline(&inline)
+        .map_err(deepgram::DeepgramError::JsonError)?
+        .with_metadata([("env", "demo"), ("source", "rust-sdk-example")]);
+
+    let created = configs.create(&project_id, &create_request).await?;
+    let agent_id = created.agent_id;
+    let mut config_keys: Vec<String> = created
+        .config
+        .as_object()
+        .map(|m| m.keys().cloned().collect())
+        .unwrap_or_default();
+    config_keys.sort();
+    println!("Created agent: {agent_id} (config_keys: {:?})", config_keys);
+
+    let listed = configs.list(&project_id).await?;
+    println!("Listed {} agents on the project.", listed.agents.len());
+
+    let updated = configs
+        .update_metadata(
+            &project_id,
+            &agent_id,
+            &UpdateAgentMetadataRequest::new([("env", "staging")]),
+        )
+        .await?;
+    println!("Updated metadata: {:?}", updated.metadata);
+
+    configs.delete(&project_id, &agent_id).await?;
+    println!("Deleted agent {agent_id}.");
+
+    Ok(())
+}

examples/agent/rest/variables.rs

@@ -0,0 +1,75 @@
+/* Expected result from running this example program.
+Created variable v1 (key=DG_AGENT_NAME)
+Listed 1 variables.
+Get -> "Alice"
+Update -> "Bob"
+Deleted variable v1.
+Think models available:
+  open_ai      gpt-4o-mini
+  anthropic    claude-3-5-haiku-latest
+  ...
+*/
+
+//! Walkthrough for the Agent template-variables REST endpoints, plus a
+//! call to the think-models catalog at the end.
+//!
+//! Run with:
+//!
+//! ```bash
+//! DEEPGRAM_API_KEY=<your-key> \
+//! DEEPGRAM_PROJECT_ID=<project-uuid> \
+//!     cargo run --features agent --example agent_variables
+//! ```
+
+use std::env;
+
+use serde_json::json;
+
+use deepgram::agent::variables::CreateAgentVariableRequest;
+use deepgram::{Deepgram, DeepgramError};
+
+#[tokio::main]
+async fn main() -> Result<(), DeepgramError> {
+    let api_key = env::var("DEEPGRAM_API_KEY").expect("DEEPGRAM_API_KEY environment variable");
+    let project_id =
+        env::var("DEEPGRAM_PROJECT_ID").expect("DEEPGRAM_PROJECT_ID environment variable");
+
+    let dg = Deepgram::new(&api_key)?;
+    let agent = dg.agent();
+    let variables = agent.variables();
+
+    let created = variables
+        .create(
+            &project_id,
+            &CreateAgentVariableRequest::new("DG_AGENT_NAME", json!("Alice")),
+        )
+        .await?;
+    let variable_id = created.variable_id.clone();
+    println!("Created variable {} (key={})", variable_id, created.key);
+
+    let listed = variables.list(&project_id).await?;
+    println!("Listed {} variables.", listed.variables.len());
+
+    let fetched = variables.get(&project_id, &variable_id).await?;
+    println!("Get -> {}", fetched.value);
+
+    let updated = variables
+        .update(&project_id, &variable_id, json!("Bob"))
+        .await?;
+    println!("Update -> {}", updated.value);
+
+    variables.delete(&project_id, &variable_id).await?;
+    println!("Deleted variable {}.", variable_id);
+
+    let think_models = agent.think_models().list().await?;
+    println!("Think models available:");
+    for model in think_models.models {
+        println!(
+            "  {:<12} {}",
+            format!("{:?}", model.provider).to_lowercase(),
+            model.id
+        );
+    }
+
+    Ok(())
+}