# This file was auto-generated by Fern from our API Definition.

import typing

from ..core.client_wrapper import AsyncClientWrapper, SyncClientWrapper
from ..core.pagination import AsyncPager, SyncPager
from ..core.request_options import RequestOptions
from .raw_client import AsyncRawAgentsClient, RawAgentsClient
from .types.get_agents_response import GetAgentsResponse
from .types.get_history_agents_response import GetHistoryAgentsResponse
from .types.interrupt_agents_response import InterruptAgentsResponse
from .types.list_agents_request_state import ListAgentsRequestState
from .types.list_agents_response import ListAgentsResponse
from .types.list_agents_response_data_list_item import ListAgentsResponseDataListItem
from .types.speak_agents_request_priority import SpeakAgentsRequestPriority
from .types.speak_agents_response import SpeakAgentsResponse
from .types.start_agents_request_properties import StartAgentsRequestProperties
from .types.start_agents_response import StartAgentsResponse
from .types.update_agents_request_properties import UpdateAgentsRequestProperties
from .types.update_agents_response import UpdateAgentsResponse

# this is used as the default value for optional parameters
OMIT = typing.cast(typing.Any, ...)


class AgentsClient:
    def __init__(self, *, client_wrapper: SyncClientWrapper):
        self._raw_client = RawAgentsClient(client_wrapper=client_wrapper)

    @property
    def with_raw_response(self) -> RawAgentsClient:
        """
        Retrieves a raw implementation of this client that returns raw responses.

        Returns
        -------
        RawAgentsClient
        """
        return self._raw_client

    def start(
        self,
        appid: str,
        *,
        name: str,
        properties: StartAgentsRequestProperties,
        request_options: typing.Optional[RequestOptions] = None,
    ) -> StartAgentsResponse:
        """
        Create and start a Conversational AI agent instance.

        Parameters
        ----------
        appid : str
            The App ID of the project.

        name : str
            The unique identifier of the agent. The same identifier cannot be used repeatedly.

        properties : StartAgentsRequestProperties
            Configuration details of the agent.

        request_options : typing.Optional[RequestOptions]
            Request-specific configuration.

        Returns
        -------
        StartAgentsResponse
            Request was successful. The response body contains the result of the request.

        Examples
        --------
        from agora_agent import Agora, MicrosoftTtsParams, Tts_Microsoft
        from agora_agent.agents import (
            StartAgentsRequestProperties,
            StartAgentsRequestPropertiesAsr,
            StartAgentsRequestPropertiesLlm,
        )

        client = Agora(
            authorization="YOUR_AUTHORIZATION",
            username="YOUR_USERNAME",
            password="YOUR_PASSWORD",
        )
        client.agents.start(
            appid="appid",
            name="unique_name",
            properties=StartAgentsRequestProperties(
                channel="channel_name",
                token="token",
                agent_rtc_uid="1001",
                remote_rtc_uids=["1002"],
                idle_timeout=120,
                asr=StartAgentsRequestPropertiesAsr(
                    language="en-US",
                ),
                tts=Tts_Microsoft(
                    params=MicrosoftTtsParams(
                        key="key",
                        region="region",
                        voice_name="voice_name",
                    ),
                ),
                llm=StartAgentsRequestPropertiesLlm(
                    url="https://api.openai.com/v1/chat/completions",
                    api_key="<your_llm_key>",
                    system_messages=[
                        {"role": "system", "content": "You are a helpful chatbot."}
                    ],
                    params={"model": "gpt-4o-mini"},
                    max_history=32,
                    greeting_message="Hello, how can I assist you today?",
                    failure_message="Please hold on a second.",
                ),
            ),
        )
        """
        _response = self._raw_client.start(appid, name=name, properties=properties, request_options=request_options)
        return _response.data

    def list(
        self,
        appid: str,
        *,
        channel: typing.Optional[str] = None,
        from_time: typing.Optional[float] = None,
        to_time: typing.Optional[float] = None,
        state: typing.Optional[ListAgentsRequestState] = None,
        limit: typing.Optional[int] = None,
        cursor: typing.Optional[str] = None,
        request_options: typing.Optional[RequestOptions] = None,
    ) -> SyncPager[ListAgentsResponseDataListItem, ListAgentsResponse]:
        """
        Retrieve a list of agents that meet the specified conditions.

        Parameters
        ----------
        appid : str
            The App ID of the project.

        channel : typing.Optional[str]
            The channel to query for a list of agents.

        from_time : typing.Optional[float]
            The start timestamp (in seconds) for the query. Default is 2 hours ago.

        to_time : typing.Optional[float]
            The end timestamp (in seconds) for the query. Default is current time.

        state : typing.Optional[ListAgentsRequestState]
            The agent state to filter by. Only one state can be specified per query:
            - `IDLE` (0): Agent is idle.
            - `STARTING` (1): The agent is being started.
            - `RUNNING` (2): The agent is running.
            - `STOPPING` (3): The agent is stopping.
            - `STOPPED` (4): The agent has exited.
            - `RECOVERING` (5): The agent is recovering.
            - `FAILED` (6): The agent failed to execute.

        limit : typing.Optional[int]
            The maximum number of entries returned per page.

        cursor : typing.Optional[str]
            The paging cursor, indicating the starting position (`agent_id`) of the next page of results.

        request_options : typing.Optional[RequestOptions]
            Request-specific configuration.

        Returns
        -------
        SyncPager[ListAgentsResponseDataListItem, ListAgentsResponse]
            Request was successful. The response body contains the result of the request.

        Examples
        --------
        from agora_agent import Agora

        client = Agora(
            authorization="YOUR_AUTHORIZATION",
            username="YOUR_USERNAME",
            password="YOUR_PASSWORD",
        )
        response = client.agents.list(
            appid="appid",
        )
        for item in response:
            yield item
        # alternatively, you can paginate page-by-page
        for page in response.iter_pages():
            yield page
        """
        return self._raw_client.list(
            appid,
            channel=channel,
            from_time=from_time,
            to_time=to_time,
            state=state,
            limit=limit,
            cursor=cursor,
            request_options=request_options,
        )

    def get(
        self, appid: str, agent_id: str, *, request_options: typing.Optional[RequestOptions] = None
    ) -> GetAgentsResponse:
        """
        Get the current state information of the specified agent instance.

        Parameters
        ----------
        appid : str
            The App ID of the project.

        agent_id : str
            The agent instance ID you obtained after successfully calling `join` to start a conversational AI agent.

        request_options : typing.Optional[RequestOptions]
            Request-specific configuration.

        Returns
        -------
        GetAgentsResponse
            Request was successful. The response body contains the result of the request.

        Examples
        --------
        from agora_agent import Agora

        client = Agora(
            authorization="YOUR_AUTHORIZATION",
            username="YOUR_USERNAME",
            password="YOUR_PASSWORD",
        )
        client.agents.get(
            appid="appid",
            agent_id="agentId",
        )
        """
        _response = self._raw_client.get(appid, agent_id, request_options=request_options)
        return _response.data

    def get_history(
        self, appid: str, agent_id: str, *, request_options: typing.Optional[RequestOptions] = None
    ) -> GetHistoryAgentsResponse:
        """
        Get the history of the conversation between the user and the agent.

        Call this endpoint while the agent is running to retrieve the conversation history. You can set the maximum number of cached entries using the `llm.max_history` parameter when calling the start agent endpoint. The default value is `32`.

        Parameters
        ----------
        appid : str
            The App ID of the project.

        agent_id : str
            The agent instance ID you obtained after successfully calling `join` to start a conversational AI agent.

        request_options : typing.Optional[RequestOptions]
            Request-specific configuration.

        Returns
        -------
        GetHistoryAgentsResponse
            Request was successful. The response body contains the result of the request.

        Examples
        --------
        from agora_agent import Agora

        client = Agora(
            authorization="YOUR_AUTHORIZATION",
            username="YOUR_USERNAME",
            password="YOUR_PASSWORD",
        )
        client.agents.get_history(
            appid="appid",
            agent_id="agentId",
        )
        """
        _response = self._raw_client.get_history(appid, agent_id, request_options=request_options)
        return _response.data

    def stop(self, appid: str, agent_id: str, *, request_options: typing.Optional[RequestOptions] = None) -> None:
        """
        Stop the specified conversational agent instance.

        Parameters
        ----------
        appid : str
            The App ID of the project.

        agent_id : str
            The agent instance ID you obtained after successfully calling `join` to start a conversational AI agent.

        request_options : typing.Optional[RequestOptions]
            Request-specific configuration.

        Returns
        -------
        None

        Examples
        --------
        from agora_agent import Agora

        client = Agora(
            authorization="YOUR_AUTHORIZATION",
            username="YOUR_USERNAME",
            password="YOUR_PASSWORD",
        )
        client.agents.stop(
            appid="appid",
            agent_id="agentId",
        )
        """
        _response = self._raw_client.stop(appid, agent_id, request_options=request_options)
        return _response.data

    def update(
        self,
        appid: str,
        agent_id: str,
        *,
        properties: typing.Optional[UpdateAgentsRequestProperties] = OMIT,
        request_options: typing.Optional[RequestOptions] = None,
    ) -> UpdateAgentsResponse:
        """
        Adjust Conversation AI Engine parameters at runtime.

        Parameters
        ----------
        appid : str
            The App ID of the project.

        agent_id : str
            The agent instance ID you obtained after successfully calling `join` to start a conversational AI agent.

        properties : typing.Optional[UpdateAgentsRequestProperties]
            Configuration properties to update.

        request_options : typing.Optional[RequestOptions]
            Request-specific configuration.

        Returns
        -------
        UpdateAgentsResponse
            Request was successful. The response body contains the result of the request.

        Examples
        --------
        from agora_agent import Agora
        from agora_agent.agents import (
            UpdateAgentsRequestProperties,
            UpdateAgentsRequestPropertiesLlm,
        )

        client = Agora(
            authorization="YOUR_AUTHORIZATION",
            username="YOUR_USERNAME",
            password="YOUR_PASSWORD",
        )
        client.agents.update(
            appid="appid",
            agent_id="agentId",
            properties=UpdateAgentsRequestProperties(
                token="007eJxTYxxxxxxxxxxIaHMLAAAA0ex66",
                llm=UpdateAgentsRequestPropertiesLlm(
                    system_messages=[
                        {
                            "role": "system",
                            "content": "You are a helpful assistant. xxx",
                        },
                        {
                            "role": "system",
                            "content": "Previously, user has talked about their favorite hobbies with some key topics: xxx",
                        },
                    ],
                    params={"model": "abab6.5s-chat", "max_token": 1024},
                ),
            ),
        )
        """
        _response = self._raw_client.update(appid, agent_id, properties=properties, request_options=request_options)
        return _response.data

    def speak(
        self,
        appid: str,
        agent_id: str,
        *,
        text: str,
        priority: typing.Optional[SpeakAgentsRequestPriority] = OMIT,
        interruptable: typing.Optional[bool] = OMIT,
        request_options: typing.Optional[RequestOptions] = None,
    ) -> SpeakAgentsResponse:
        """
        Broadcast a custom message using the TTS module.

        During a conversation with an agent, call this endpoint to immediately broadcast a custom message using the TTS module. Upon receiving the request, the system interrupts the agent's speech and thought process to deliver the message. This broadcast can be interrupted by human voice.

        Note: The speak API is not supported when using `mllm` configuration.

        Parameters
        ----------
        appid : str
            The App ID of the project.

        agent_id : str
            The agent instance ID you obtained after successfully calling `join` to start a conversational AI agent.

        text : str
            The broadcast message text. The maximum length of the text content is 512 bytes.

        priority : typing.Optional[SpeakAgentsRequestPriority]
            Sets the priority of the message broadcast:
            - `INTERRUPT`: High priority. The agent immediately interrupts the current interaction to announce the message.
            - `APPEND`: Medium priority. The agent announces the message after the current interaction ends.
            - `IGNORE`: Low priority. If the agent is busy interacting, it ignores and discards the broadcast; the message is only announced if the agent is not interacting.

        interruptable : typing.Optional[bool]
            Whether to allow users to interrupt the agent's broadcast by speaking:
            - `true`: Allow
            - `false`: Don't allow

        request_options : typing.Optional[RequestOptions]
            Request-specific configuration.

        Returns
        -------
        SpeakAgentsResponse
            Request was successful. The agent starts to broadcast the specified message.

        Examples
        --------
        from agora_agent import Agora

        client = Agora(
            authorization="YOUR_AUTHORIZATION",
            username="YOUR_USERNAME",
            password="YOUR_PASSWORD",
        )
        client.agents.speak(
            appid="appid",
            agent_id="agentId",
            text="Sorry, the conversation content is not compliant.",
            priority="INTERRUPT",
            interruptable=False,
        )
        """
        _response = self._raw_client.speak(
            appid, agent_id, text=text, priority=priority, interruptable=interruptable, request_options=request_options
        )
        return _response.data

    def interrupt(
        self, appid: str, agent_id: str, *, request_options: typing.Optional[RequestOptions] = None
    ) -> InterruptAgentsResponse:
        """
        Interrupt the specified agent while speaking or thinking.

        Parameters
        ----------
        appid : str
            The App ID of the project.

        agent_id : str
            The agent instance ID you obtained after successfully calling `join` to start a conversational AI agent.

        request_options : typing.Optional[RequestOptions]
            Request-specific configuration.

        Returns
        -------
        InterruptAgentsResponse
            Request was successful. The response body contains agent information and the agent stops talking and thinking immediately.

        Examples
        --------
        from agora_agent import Agora

        client = Agora(
            authorization="YOUR_AUTHORIZATION",
            username="YOUR_USERNAME",
            password="YOUR_PASSWORD",
        )
        client.agents.interrupt(
            appid="appid",
            agent_id="agentId",
        )
        """
        _response = self._raw_client.interrupt(appid, agent_id, request_options=request_options)
        return _response.data


class AsyncAgentsClient:
    def __init__(self, *, client_wrapper: AsyncClientWrapper):
        self._raw_client = AsyncRawAgentsClient(client_wrapper=client_wrapper)

    @property
    def with_raw_response(self) -> AsyncRawAgentsClient:
        """
        Retrieves a raw implementation of this client that returns raw responses.

        Returns
        -------
        AsyncRawAgentsClient
        """
        return self._raw_client

    async def start(
        self,
        appid: str,
        *,
        name: str,
        properties: StartAgentsRequestProperties,
        request_options: typing.Optional[RequestOptions] = None,
    ) -> StartAgentsResponse:
        """
        Create and start a Conversational AI agent instance.

        Parameters
        ----------
        appid : str
            The App ID of the project.

        name : str
            The unique identifier of the agent. The same identifier cannot be used repeatedly.

        properties : StartAgentsRequestProperties
            Configuration details of the agent.

        request_options : typing.Optional[RequestOptions]
            Request-specific configuration.

        Returns
        -------
        StartAgentsResponse
            Request was successful. The response body contains the result of the request.

        Examples
        --------
        import asyncio

        from agora_agent import AsyncAgora, MicrosoftTtsParams, Tts_Microsoft
        from agora_agent.agents import (
            StartAgentsRequestProperties,
            StartAgentsRequestPropertiesAsr,
            StartAgentsRequestPropertiesLlm,
        )

        client = AsyncAgora(
            authorization="YOUR_AUTHORIZATION",
            username="YOUR_USERNAME",
            password="YOUR_PASSWORD",
        )


        async def main() -> None:
            await client.agents.start(
                appid="appid",
                name="unique_name",
                properties=StartAgentsRequestProperties(
                    channel="channel_name",
                    token="token",
                    agent_rtc_uid="1001",
                    remote_rtc_uids=["1002"],
                    idle_timeout=120,
                    asr=StartAgentsRequestPropertiesAsr(
                        language="en-US",
                    ),
                    tts=Tts_Microsoft(
                        params=MicrosoftTtsParams(
                            key="key",
                            region="region",
                            voice_name="voice_name",
                        ),
                    ),
                    llm=StartAgentsRequestPropertiesLlm(
                        url="https://api.openai.com/v1/chat/completions",
                        api_key="<your_llm_key>",
                        system_messages=[
                            {"role": "system", "content": "You are a helpful chatbot."}
                        ],
                        params={"model": "gpt-4o-mini"},
                        max_history=32,
                        greeting_message="Hello, how can I assist you today?",
                        failure_message="Please hold on a second.",
                    ),
                ),
            )


        asyncio.run(main())
        """
        _response = await self._raw_client.start(
            appid, name=name, properties=properties, request_options=request_options
        )
        return _response.data

    async def list(
        self,
        appid: str,
        *,
        channel: typing.Optional[str] = None,
        from_time: typing.Optional[float] = None,
        to_time: typing.Optional[float] = None,
        state: typing.Optional[ListAgentsRequestState] = None,
        limit: typing.Optional[int] = None,
        cursor: typing.Optional[str] = None,
        request_options: typing.Optional[RequestOptions] = None,
    ) -> AsyncPager[ListAgentsResponseDataListItem, ListAgentsResponse]:
        """
        Retrieve a list of agents that meet the specified conditions.

        Parameters
        ----------
        appid : str
            The App ID of the project.

        channel : typing.Optional[str]
            The channel to query for a list of agents.

        from_time : typing.Optional[float]
            The start timestamp (in seconds) for the query. Default is 2 hours ago.

        to_time : typing.Optional[float]
            The end timestamp (in seconds) for the query. Default is current time.

        state : typing.Optional[ListAgentsRequestState]
            The agent state to filter by. Only one state can be specified per query:
            - `IDLE` (0): Agent is idle.
            - `STARTING` (1): The agent is being started.
            - `RUNNING` (2): The agent is running.
            - `STOPPING` (3): The agent is stopping.
            - `STOPPED` (4): The agent has exited.
            - `RECOVERING` (5): The agent is recovering.
            - `FAILED` (6): The agent failed to execute.

        limit : typing.Optional[int]
            The maximum number of entries returned per page.

        cursor : typing.Optional[str]
            The paging cursor, indicating the starting position (`agent_id`) of the next page of results.

        request_options : typing.Optional[RequestOptions]
            Request-specific configuration.

        Returns
        -------
        AsyncPager[ListAgentsResponseDataListItem, ListAgentsResponse]
            Request was successful. The response body contains the result of the request.

        Examples
        --------
        import asyncio

        from agora_agent import AsyncAgora

        client = AsyncAgora(
            authorization="YOUR_AUTHORIZATION",
            username="YOUR_USERNAME",
            password="YOUR_PASSWORD",
        )


        async def main() -> None:
            response = await client.agents.list(
                appid="appid",
            )
            async for item in response:
                yield item

            # alternatively, you can paginate page-by-page
            async for page in response.iter_pages():
                yield page


        asyncio.run(main())
        """
        return await self._raw_client.list(
            appid,
            channel=channel,
            from_time=from_time,
            to_time=to_time,
            state=state,
            limit=limit,
            cursor=cursor,
            request_options=request_options,
        )

    async def get(
        self, appid: str, agent_id: str, *, request_options: typing.Optional[RequestOptions] = None
    ) -> GetAgentsResponse:
        """
        Get the current state information of the specified agent instance.

        Parameters
        ----------
        appid : str
            The App ID of the project.

        agent_id : str
            The agent instance ID you obtained after successfully calling `join` to start a conversational AI agent.

        request_options : typing.Optional[RequestOptions]
            Request-specific configuration.

        Returns
        -------
        GetAgentsResponse
            Request was successful. The response body contains the result of the request.

        Examples
        --------
        import asyncio

        from agora_agent import AsyncAgora

        client = AsyncAgora(
            authorization="YOUR_AUTHORIZATION",
            username="YOUR_USERNAME",
            password="YOUR_PASSWORD",
        )


        async def main() -> None:
            await client.agents.get(
                appid="appid",
                agent_id="agentId",
            )


        asyncio.run(main())
        """
        _response = await self._raw_client.get(appid, agent_id, request_options=request_options)
        return _response.data

    async def get_history(
        self, appid: str, agent_id: str, *, request_options: typing.Optional[RequestOptions] = None
    ) -> GetHistoryAgentsResponse:
        """
        Get the history of the conversation between the user and the agent.

        Call this endpoint while the agent is running to retrieve the conversation history. You can set the maximum number of cached entries using the `llm.max_history` parameter when calling the start agent endpoint. The default value is `32`.

        Parameters
        ----------
        appid : str
            The App ID of the project.

        agent_id : str
            The agent instance ID you obtained after successfully calling `join` to start a conversational AI agent.

        request_options : typing.Optional[RequestOptions]
            Request-specific configuration.

        Returns
        -------
        GetHistoryAgentsResponse
            Request was successful. The response body contains the result of the request.

        Examples
        --------
        import asyncio

        from agora_agent import AsyncAgora

        client = AsyncAgora(
            authorization="YOUR_AUTHORIZATION",
            username="YOUR_USERNAME",
            password="YOUR_PASSWORD",
        )


        async def main() -> None:
            await client.agents.get_history(
                appid="appid",
                agent_id="agentId",
            )


        asyncio.run(main())
        """
        _response = await self._raw_client.get_history(appid, agent_id, request_options=request_options)
        return _response.data

    async def stop(self, appid: str, agent_id: str, *, request_options: typing.Optional[RequestOptions] = None) -> None:
        """
        Stop the specified conversational agent instance.

        Parameters
        ----------
        appid : str
            The App ID of the project.

        agent_id : str
            The agent instance ID you obtained after successfully calling `join` to start a conversational AI agent.

        request_options : typing.Optional[RequestOptions]
            Request-specific configuration.

        Returns
        -------
        None

        Examples
        --------
        import asyncio

        from agora_agent import AsyncAgora

        client = AsyncAgora(
            authorization="YOUR_AUTHORIZATION",
            username="YOUR_USERNAME",
            password="YOUR_PASSWORD",
        )


        async def main() -> None:
            await client.agents.stop(
                appid="appid",
                agent_id="agentId",
            )


        asyncio.run(main())
        """
        _response = await self._raw_client.stop(appid, agent_id, request_options=request_options)
        return _response.data

    async def update(
        self,
        appid: str,
        agent_id: str,
        *,
        properties: typing.Optional[UpdateAgentsRequestProperties] = OMIT,
        request_options: typing.Optional[RequestOptions] = None,
    ) -> UpdateAgentsResponse:
        """
        Adjust Conversation AI Engine parameters at runtime.

        Parameters
        ----------
        appid : str
            The App ID of the project.

        agent_id : str
            The agent instance ID you obtained after successfully calling `join` to start a conversational AI agent.

        properties : typing.Optional[UpdateAgentsRequestProperties]
            Configuration properties to update.

        request_options : typing.Optional[RequestOptions]
            Request-specific configuration.

        Returns
        -------
        UpdateAgentsResponse
            Request was successful. The response body contains the result of the request.

        Examples
        --------
        import asyncio

        from agora_agent import AsyncAgora
        from agora_agent.agents import (
            UpdateAgentsRequestProperties,
            UpdateAgentsRequestPropertiesLlm,
        )

        client = AsyncAgora(
            authorization="YOUR_AUTHORIZATION",
            username="YOUR_USERNAME",
            password="YOUR_PASSWORD",
        )


        async def main() -> None:
            await client.agents.update(
                appid="appid",
                agent_id="agentId",
                properties=UpdateAgentsRequestProperties(
                    token="007eJxTYxxxxxxxxxxIaHMLAAAA0ex66",
                    llm=UpdateAgentsRequestPropertiesLlm(
                        system_messages=[
                            {
                                "role": "system",
                                "content": "You are a helpful assistant. xxx",
                            },
                            {
                                "role": "system",
                                "content": "Previously, user has talked about their favorite hobbies with some key topics: xxx",
                            },
                        ],
                        params={"model": "abab6.5s-chat", "max_token": 1024},
                    ),
                ),
            )


        asyncio.run(main())
        """
        _response = await self._raw_client.update(
            appid, agent_id, properties=properties, request_options=request_options
        )
        return _response.data

    async def speak(
        self,
        appid: str,
        agent_id: str,
        *,
        text: str,
        priority: typing.Optional[SpeakAgentsRequestPriority] = OMIT,
        interruptable: typing.Optional[bool] = OMIT,
        request_options: typing.Optional[RequestOptions] = None,
    ) -> SpeakAgentsResponse:
        """
        Broadcast a custom message using the TTS module.

        During a conversation with an agent, call this endpoint to immediately broadcast a custom message using the TTS module. Upon receiving the request, the system interrupts the agent's speech and thought process to deliver the message. This broadcast can be interrupted by human voice.

        Note: The speak API is not supported when using `mllm` configuration.

        Parameters
        ----------
        appid : str
            The App ID of the project.

        agent_id : str
            The agent instance ID you obtained after successfully calling `join` to start a conversational AI agent.

        text : str
            The broadcast message text. The maximum length of the text content is 512 bytes.

        priority : typing.Optional[SpeakAgentsRequestPriority]
            Sets the priority of the message broadcast:
            - `INTERRUPT`: High priority. The agent immediately interrupts the current interaction to announce the message.
            - `APPEND`: Medium priority. The agent announces the message after the current interaction ends.
            - `IGNORE`: Low priority. If the agent is busy interacting, it ignores and discards the broadcast; the message is only announced if the agent is not interacting.

        interruptable : typing.Optional[bool]
            Whether to allow users to interrupt the agent's broadcast by speaking:
            - `true`: Allow
            - `false`: Don't allow

        request_options : typing.Optional[RequestOptions]
            Request-specific configuration.

        Returns
        -------
        SpeakAgentsResponse
            Request was successful. The agent starts to broadcast the specified message.

        Examples
        --------
        import asyncio

        from agora_agent import AsyncAgora

        client = AsyncAgora(
            authorization="YOUR_AUTHORIZATION",
            username="YOUR_USERNAME",
            password="YOUR_PASSWORD",
        )


        async def main() -> None:
            await client.agents.speak(
                appid="appid",
                agent_id="agentId",
                text="Sorry, the conversation content is not compliant.",
                priority="INTERRUPT",
                interruptable=False,
            )


        asyncio.run(main())
        """
        _response = await self._raw_client.speak(
            appid, agent_id, text=text, priority=priority, interruptable=interruptable, request_options=request_options
        )
        return _response.data

    async def interrupt(
        self, appid: str, agent_id: str, *, request_options: typing.Optional[RequestOptions] = None
    ) -> InterruptAgentsResponse:
        """
        Interrupt the specified agent while speaking or thinking.

        Parameters
        ----------
        appid : str
            The App ID of the project.

        agent_id : str
            The agent instance ID you obtained after successfully calling `join` to start a conversational AI agent.

        request_options : typing.Optional[RequestOptions]
            Request-specific configuration.

        Returns
        -------
        InterruptAgentsResponse
            Request was successful. The response body contains agent information and the agent stops talking and thinking immediately.

        Examples
        --------
        import asyncio

        from agora_agent import AsyncAgora

        client = AsyncAgora(
            authorization="YOUR_AUTHORIZATION",
            username="YOUR_USERNAME",
            password="YOUR_PASSWORD",
        )


        async def main() -> None:
            await client.agents.interrupt(
                appid="appid",
                agent_id="agentId",
            )


        asyncio.run(main())
        """
        _response = await self._raw_client.interrupt(appid, agent_id, request_options=request_options)
        return _response.data
