LiveKit Plugins: Phonic

Realtime voice AI integration for Phonic with LiveKit Agents.

Installation

uv add livekit-plugins-phonic

Usage

import asyncio
import logging

from dotenv import load_dotenv

from livekit.agents import (
    Agent,
    AgentServer,
    AgentSession,
    JobContext,
    cli,
    function_tool,
)
from livekit.plugins.phonic.realtime import RealtimeModel

logger = logging.getLogger("phonic-agent")

load_dotenv()


class MyAgent(Agent):
    def __init__(self) -> None:
        super().__init__(
            instructions="You are a helpful voice AI assistant named Sabrina.",
            llm=RealtimeModel(
                voice="sabrina",
                audio_speed=1.2,
            ),
        )

    @function_tool(
        description="Toggle a light on or off. Available lights are A05, A06, A07, and A08."
    )
    async def toggle_light(self, light_id: str, state: str) -> str:
        """Called when the user asks to toggle a light on or off.

        Args:
            light_id: The ID of the light to toggle
            state: Whether to turn the light on or off, e.g., 'on', 'off'
        """
        logger.info(f"Turning {state} light {light_id}")
        await asyncio.sleep(1.0)
        return f"Light {light_id} turned {state}"


server = AgentServer()


@server.rtc_session()
async def entrypoint(ctx: JobContext):
    session = AgentSession()
    await session.start(agent=MyAgent(), room=ctx.room)
    await session.generate_reply(
        instructions="Greet the user, asking about their day.",
    )


if __name__ == "__main__":
    cli.run_app(server)

Reusing tools with Phonic Responses

Convert an existing LiveKit ToolContext into the schema-only definitions accepted by Phonic's Responses API:

from livekit.plugins.phonic.realtime import to_phonic_tool_definitions

tool_definitions = to_phonic_tool_definitions(tool_context)

The executable functions remain in the ToolContext; only their names, descriptions, and parameter schemas are returned.

Configuration

Set the PHONIC_API_KEY environment variable, or pass api_key directly to RealtimeModel. All other options are optional.

Per-tool configuration

configs_for_tools takes one entry per tool you want to customize. Each entry is keyed by the tool name; every other field is optional and falls back to the plugin default when omitted. Tools with no entry keep the defaults.

RealtimeModel(
    configs_for_tools=[
        {"name": "transfer_call", "forbid_speech_after_tool_call": True},
        {"name": "submit_form", "forbid_tool_call_after_speech": True},
    ],
)

The plugin always sends tool calls with wait_for_speech_before_tool_call on; this is not configurable per tool.

Deprecated: the top-level forbid_speech_after_tool_call: list[str] option still works but is deprecated — it now folds each listed tool into configs_for_tools as forbid_speech_after_tool_call=True (an explicit configs_for_tools entry wins) and logs a warning. Prefer configs_for_tools.

Built-in tools

Phonic's built-in tools — choose_not_to_respond, keypad_input, natural_conversation_ending — are enabled by listing their names in phonic_tools, alongside any Webhook tools. To configure one, add a configs_for_tools entry keyed by the same name (respond_after_sec for choose_not_to_respond; speech_before_tool_call for the other two). A built-in listed without a config uses its Phonic-side defaults.

RealtimeModel(
    phonic_tools=["choose_not_to_respond", "keypad_input"],
    configs_for_tools=[
        {"name": "choose_not_to_respond", "respond_after_sec": 5},
    ],
)

If you already have an agent set up on the Phonic platform, you can use the phonic_agent option to specify the agent name. As a note, configuration options you set in the LiveKit Agents SDK will override the agent settings set on the Phonic platform. This means the system prompt you have set on the Phonic platform will be ignored in favor of the instructions field set on the LiveKit Agent. Likewise, options explicitly set in the RealtimeModel constructor will override the Phonic agent's settings.

If you have Webhook tools set up on the Phonic platform, you can use phonic_tools to make them available to your agent, together with Phonic's built-in tools. Custom function tools you define on the LiveKit Agent are also supported and run over the websocket.