livekit_api/services/

agent_dispatch.rs

// Copyright 2025 LiveKit, Inc.
//
// Licensed under the Apache License, Version 2.0 (the "License");
// you may not use this file except in compliance with the License.
// You may obtain a copy of the License at
//
//     http://www.apache.org/licenses/LICENSE-2.0
//
// Unless required by applicable law or agreed to in writing, software
// distributed under the License is distributed on an "AS IS" BASIS,
// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
// See the License for the specific language governing permissions and
// limitations under the License.

use super::{twirp_client::TwirpClient, ServiceBase, ServiceResult, LIVEKIT_PACKAGE};
use crate::{
    access_token::{AccessTokenError, VideoGrants},
    get_env_keys,
};
use http::header::HeaderMap;
use livekit_protocol as proto;

const SVC: &str = "AgentDispatchService";

#[derive(Debug)]
pub struct AgentDispatchClient {
    base: ServiceBase,
    client: TwirpClient,
}

impl AgentDispatchClient {
    /// Authenticates with an API key and secret, signing a short-lived token per request.
    pub fn with_api_key(host: &str, api_key: &str, api_secret: &str) -> Self {
        Self::build(
            host,
            ServiceBase::with_api_key(api_key, api_secret),
            crate::http_client::Client::new(),
        )
    }

    /// Authenticates with a pre-signed token, sent verbatim on every request.
    pub fn with_token(host: &str, token: &str) -> Self {
        Self::build(host, ServiceBase::with_token(token), crate::http_client::Client::new())
    }

    /// Builds the client from an already-constructed HTTP client so the unified
    /// [`LiveKitApi`](super::LiveKitApi) can share one connection pool across services.
    pub(crate) fn build(host: &str, base: ServiceBase, client: crate::http_client::Client) -> Self {
        Self { base, client: TwirpClient::with_client(host, LIVEKIT_PACKAGE, None, client) }
    }

    #[cfg(test)]
    pub(crate) fn with_default_headers(mut self, headers: http::HeaderMap) -> Self {
        self.client = self.client.with_default_headers(headers);
        self
    }

    /// Reads the API key and secret from the `LIVEKIT_API_KEY` and
    /// `LIVEKIT_API_SECRET` environment variables.
    pub fn new(host: &str) -> ServiceResult<Self> {
        let (api_key, api_secret) = get_env_keys()?;
        Ok(Self::with_api_key(host, &api_key, &api_secret))
    }

    /// Enables or disables region failover (enabled by default). Failover only
    /// engages for LiveKit Cloud hosts.
    pub fn with_failover(mut self, enabled: bool) -> Self {
        self.client = self.client.with_failover(enabled);
        self
    }

    /// Overrides the default per-request timeout (10s) for calls on this client.
    pub fn with_request_timeout(mut self, timeout: std::time::Duration) -> Self {
        self.client = self.client.with_request_timeout(timeout);
        self
    }

    /// Creates an explicit dispatch for an agent to join a room.
    ///
    /// To use explicit dispatch, your agent must be registered with an `agent_name`.
    ///
    /// # Arguments
    /// * `req` - Request containing dispatch creation parameters. The request can include
    ///   an optional `deployment` field to target a specific agent deployment.
    ///   Leave empty to target the production deployment.
    ///
    /// # Returns
    /// The created agent dispatch object
    ///
    pub async fn create_dispatch(
        &self,
        req: proto::CreateAgentDispatchRequest,
    ) -> ServiceResult<proto::AgentDispatch> {
        const METHOD: &str = "CreateDispatch";
        let headers = self.auth_headers(req.room.to_string())?;
        Ok(self.client.request(SVC, METHOD, req, headers).await?)
    }

    /// Deletes an explicit dispatch for an agent in a room.
    ///
    /// # Arguments
    /// * `dispatch_id` - ID of the dispatch to delete
    /// * `room_name` - Name of the room containing the dispatch
    ///
    /// # Returns
    /// The deleted agent dispatch object
    ///
    pub async fn delete_dispatch(
        &self,
        dispatch_id: impl Into<String>,
        room_name: impl Into<String>,
    ) -> ServiceResult<proto::AgentDispatch> {
        const METHOD: &str = "DeleteDispatch";
        let req = proto::DeleteAgentDispatchRequest {
            dispatch_id: dispatch_id.into(),
            room: room_name.into(),
        };
        let headers = self.auth_headers(req.room.to_string())?;
        Ok(self.client.request(SVC, METHOD, req, headers).await?)
    }

    /// Lists all agent dispatches in a room.
    ///
    /// # Arguments
    /// * `room_name` - Name of the room to list dispatches from
    ///
    /// # Returns
    /// List of dispatch objects in the room
    ///
    pub async fn list_dispatch(
        &self,
        room_name: impl Into<String>,
    ) -> ServiceResult<Vec<proto::AgentDispatch>> {
        const METHOD: &str = "ListDispatch";
        let req = proto::ListAgentDispatchRequest { room: room_name.into(), ..Default::default() };
        let headers = self.auth_headers(req.room.to_string())?;
        let res: proto::ListAgentDispatchResponse =
            self.client.request(SVC, METHOD, req, headers).await?;
        Ok(res.agent_dispatches)
    }

    /// Gets an agent dispatch by ID.
    ///
    /// # Arguments
    /// * `dispatch_id` - ID of the dispatch to retrieve
    /// * `room_name` - Name of the room containing the dispatch
    ///
    /// # Returns
    /// Requested dispatch object if found, `None` otherwise
    ///
    pub async fn get_dispatch(
        &self,
        dispatch_id: impl Into<String>,
        room_name: impl Into<String>,
    ) -> ServiceResult<Option<proto::AgentDispatch>> {
        const METHOD: &str = "ListDispatch";
        let req = proto::ListAgentDispatchRequest {
            room: room_name.into(),
            dispatch_id: dispatch_id.into(),
        };
        let headers = self.auth_headers(req.room.to_string())?;
        let mut res: proto::ListAgentDispatchResponse =
            self.client.request(SVC, METHOD, req, headers).await?;
        Ok(res.agent_dispatches.pop())
    }
}

impl AgentDispatchClient {
    /// Generates the auth header common to all dispatch request types.
    fn auth_headers(&self, room: String) -> Result<HeaderMap, AccessTokenError> {
        self.base.auth_header(VideoGrants { room, room_admin: true, ..Default::default() }, None)
    }
}