Appendix B: LiveKit Agents API Quick Reference

A condensed reference for the LiveKit Agents framework classes and methods used throughout this book. For the full API surface, consult the official LiveKit documentation. What follows are the parts you will use daily.

Agent

The base class for all voice agents. Defines the agent’s instructions, tools, and behavior.

from livekit.agents import Agent

class MyAgent(Agent):
    def __init__(self):
        super().__init__(
            instructions="Your system prompt here.",
            tools=[standalone_tool],          # Optional: standalone function tools
            chat_ctx_max_messages=50,         # Optional: limit chat history length
        )

Key methods:

Properties:

AgentTask

A focused sub-conversation that produces a typed result. Extends AgentTask[T] where T is the result dataclass.

from livekit.agents import AgentTask, function_tool
from livekit.agents.voice.events import RunContext
from dataclasses import dataclass

@dataclass
class NameResult:
    first_name: str
    last_name: str

class CollectNameTask(AgentTask[NameResult]):
    def __init__(self):
        super().__init__(
            instructions="Collect the caller's first and last name."
        )

    @function_tool()
    async def record_name(
        self, ctx: RunContext, first_name: str, last_name: str
    ) -> str:
        """Record the caller's name."""
        self.complete(NameResult(first_name=first_name, last_name=last_name))
        return f"Recorded: {first_name} {last_name}"

Key methods:

AgentSession

The runtime that orchestrates the STT-LLM-TTS pipeline. Created once per call.

from livekit.agents import AgentSession

session = AgentSession(
    stt=deepgram.STT(model="nova-3"),
    llm=openai.LLM(model="gpt-4.1-nano"),
    tts=cartesia.TTS(model="sonic"),
    vad=ctx.proc.userdata["vad"],
    turn_detection=turn_detector.EOUModel(
        min_endpointing_delay=0.5,
        max_endpointing_delay=5.0,
    ),
)

await session.start(agent=MyAgent(), room=ctx.room)

Key methods:

TaskGroup

Run multiple tasks concurrently, collecting results as they complete.

from livekit.agents import TaskGroup

group = TaskGroup()
group.add(CollectNameTask())
group.add(CollectPhoneTask())
group.add(CollectServicesTask())

results = await group.run(session)
# results is a list of task results in order

Key methods:

Configuration

Turn Detection

Controls when the agent decides the user has finished speaking.

from livekit.agents import turn_detector

turn_detection = turn_detector.EOUModel(
    min_endpointing_delay=0.5,   # Minimum silence before endpoint (seconds)
    max_endpointing_delay=5.0,   # Maximum wait before forcing endpoint
    unlikely_threshold=0.04,     # EOU probability threshold for fast cutoff
    probable_threshold=0.2,      # EOU probability threshold for standard cutoff
)

Interruption Handling

Controls whether the caller can interrupt the agent mid-speech.

session = AgentSession(
    allow_interruptions=True,    # Default: True
    min_interruption_duration=0.5,  # Minimum speech duration to trigger interrupt
)

Events

Subscribe to events on the AgentSession to react to pipeline state changes.

@session.on("agent_speech_started")
def on_speech_started():
    """Agent began speaking."""
    pass

@session.on("agent_speech_stopped")
def on_speech_stopped():
    """Agent finished speaking."""
    pass

@session.on("user_speech_started")
def on_user_started():
    """User began speaking (VAD detected voice)."""
    pass

@session.on("user_speech_stopped")
def on_user_stopped(transcript: str):
    """User finished speaking. Transcript contains STT output."""
    pass

@session.on("tool_call_started")
def on_tool_started(tool_name: str):
    """LLM initiated a tool call."""
    pass

@session.on("tool_call_completed")
def on_tool_completed(tool_name: str, result: str):
    """Tool call finished executing."""
    pass

@session.on("agent_state_changed")
def on_state_changed(state: str):
    """Agent state changed: 'listening', 'thinking', 'speaking'."""
    pass

@session.on("close")
def on_close():
    """Session ended. Clean up resources."""
    pass

function_tool Decorator

Registers a method or standalone function as a tool the LLM can call.

from livekit.agents import function_tool
from livekit.agents.voice.events import RunContext

@function_tool()
async def my_tool(
    context: RunContext,
    required_arg: str,
    optional_arg: int = 10,
) -> str:
    """Tool description that the LLM reads.

    Args:
        required_arg: Description of this argument.
        optional_arg: Description with default value.
    """
    return "result string"

Parameters for @function_tool():

Rules:

• The function’s docstring becomes the tool description the LLM uses to decide when to call it.
• Type hints on parameters become the JSON schema the LLM uses for arguments.
• Always return a string. The return value is injected into the chat context as the tool result.
• Use RunContext as the first parameter to access session state and room metadata.