livekit-agent-tools

What this skill does

# LiveKit Agent Tools Development

Build robust, production-ready tools for LiveKit voice agents that enable LLMs to interact with external services, manage state, coordinate multi-agent workflows, and handle real-time voice interactions.

## Quick Start

### Basic Tool Pattern

```python
from livekit.agents import Agent
from livekit.agents.llm import function_tool
from livekit.agents.voice import RunContext

class MyAgent(Agent):
    def __init__(self):
        super().__init__(
            instructions="You are a helpful assistant...",
            llm="openai/gpt-4o-mini",
        )

    @function_tool
    async def get_weather(self, location: str) -> str:
        """Get current weather for a location.

        Args:
            location: City name or address to get weather for
        """
        # Your implementation here
        return f"Weather in {location}: Sunny, 72°F"
```

The `@function_tool` decorator automatically registers methods as callable tools for the LLM. The docstring is critical—it tells the LLM when and how to use the tool.

### Tool Definition Best Practices

**Critical for reliability**: A good tool definition is key to reliable tool use from your LLM. Be specific about:
- What the tool does
- When it should or should not be used
- What the arguments are for
- What type of return value to expect

## Core Concepts

### 1. Tool Naming and Descriptions

Use clear, action-oriented names that help the LLM discover the right tool:

```python
@function_tool
async def search_flights(self, origin: str, destination: str, date: str) -> str:
    """Search for available flights between two cities on a specific date.

    Use this when the user asks about flight availability, prices, or schedules.
    Do NOT use this for booking—only for searching.

    Args:
        origin: Departure city or airport code
        destination: Arrival city or airport code
        date: Travel date in YYYY-MM-DD format
    """
```

### 2. RunContext for State and Control

The `RunContext` parameter provides access to session state, speech control, and user data:

```python
@function_tool
async def save_preference(
    self,
    preference_name: str,
    value: str,
    context: RunContext
) -> str:
    """Save a user preference for later use.

    Args:
        preference_name: Name of the preference (e.g., "favorite_color")
        value: The preference value
        context: Runtime context (automatically provided)
    """
    # Access shared state across tools
    context.userdata[preference_name] = value
    return f"Saved {preference_name} as {value}"
```

**See [Context & State Management](./references/context-handling.md) for complete RunContext patterns.**

### 3. Parameter Documentation

Use type hints and annotations for rich parameter documentation:

```python
from typing import Annotated, Literal
from pydantic import Field
from enum import Enum

class Priority(str, Enum):
    LOW = "low"
    MEDIUM = "medium"
    HIGH = "high"

@function_tool
async def create_task(
    self,
    title: str,
    priority: Priority,
    due_date: Annotated[str | None, Field(description="Due date in YYYY-MM-DD format")] = None
) -> str:
    """Create a new task with specified priority.

    Args:
        title: Brief description of the task
        priority: Task priority level
        due_date: Optional deadline for the task
    """
```

**See [Parameter Patterns](./references/parameter-patterns.md) for all documentation approaches.**

## When to Use Different Patterns

### Simple Action Tools
Use for straightforward operations that execute quickly:
- Logging events
- Simple calculations
- Database queries that return quickly

**See [examples/basic-tool.py](./examples/basic-tool.py)**

### API Integration Tools
Use for external service calls:
- Weather APIs
- Database queries
- Third-party integrations

**See [examples/api-integration-tool.py](./examples/api-integration-tool.py)**

### Long-Running Tools
Use for operations that might take time and should handle interruptions:
- Web searches
- Complex calculations
- File processing

**See [Long-Running Functions](./references/long-running-functions.md)** and **[examples/long-running-tool.py](./examples/long-running-tool.py)**

### Stateful Tools
Use for maintaining context across interactions:
- Shopping cart management
- Multi-step workflows
- User preferences

**See [Context & State Management](./references/context-handling.md)** and **[examples/stateful-tool.py](./examples/stateful-tool.py)**

### Multi-Agent Coordination Tools
Use for agent handoffs and specialized routing:
- Transferring to specialized agents
- Escalation workflows
- Domain-specific routing

**See [Multi-Agent Patterns](./references/multi-agent-patterns.md)** and **[examples/agent-handoff-tool.py](./examples/agent-handoff-tool.py)**

## Dynamic Tool Creation

Tools can be created at runtime for maximum flexibility:

```python
from livekit.agents.llm import function_tool

# Option 1: Pass tools at agent creation
agent = MyAgent(
    instructions="...",
    tools=[
        function_tool(
            get_user_data,
            name="get_user_data",
            description="Fetch user information from database"
        )
    ]
)

# Option 2: Update tools after creation
await agent.update_tools(
    agent.tools + [
        function_tool(
            new_capability,
            name="new_capability",
            description="Dynamically added tool"
        )
    ]
)
```

**See [Dynamic Tool Creation](./references/dynamic-tools.md) for complete patterns.**

## Testing Your Tools

Testing is essential for reliable agents. LiveKit provides helpers that work with pytest:

```python
import pytest
from livekit.agents.testing import VoiceAgentTestSession

@pytest.mark.asyncio
async def test_weather_tool():
    async with VoiceAgentTestSession(agent=MyAgent()) as session:
        response = await session.send_text("What's the weather in Tokyo?")
        assert "Tokyo" in response.text
        assert session.tool_calls[-1].name == "get_weather"
```

**See [Testing Guide](./references/testing.md) for comprehensive testing strategies.**

## Production Considerations

### Error Handling

Always handle errors gracefully and return meaningful messages:

```python
@function_tool
async def fetch_data(self, user_id: str) -> str:
    """Fetch user data from the database."""
    try:
        data = await database.get_user(user_id)
        return f"User data: {data}"
    except UserNotFoundError:
        return f"No user found with ID {user_id}. Please check the ID and try again."
    except DatabaseError as e:
        return "I'm having trouble accessing the database right now. Please try again in a moment."
```

### Interruption Handling

Design tools that respect user interruptions for better UX:

```python
@function_tool
async def search_database(self, query: str, context: RunContext) -> str | None:
    """Search the database for matching records."""
    # Allow user to interrupt long searches
    search_task = asyncio.ensure_future(perform_search(query))
    await context.speech_handle.wait_if_not_interrupted([search_task])

    if context.speech_handle.interrupted:
        search_task.cancel()
        return None  # Skip the tool reply

    return search_task.result()
```

### Tool Organization

For complex agents with many tools:
- Group related tools by domain
- Share common tools across agents using functions defined outside classes
- Use clear naming conventions (e.g., `order_create`, `order_update`, `order_cancel`)

**See [Best Practices](./references/best-practices.md) for production patterns.**

## Reference Documentation

Load these as needed for specific patterns:

- **[Context & State Management](./references/context-handling.md)** - RunContext, userdata, session control
- **[Parameter Patterns](./references/parameter-patterns.md)** - Type hints, annotations, enums, validation
- **[Long-Running Functions](./references/long-running-functions.md)** - As