Line SDK Voice Agent Guide

Build production voice agents with the Cartesia Line SDK. This guide covers agent creation, tool patterns, multi-agent workflows, and LLM provider configuration.

How Line Works

Line is Cartesia's voice agent deployment platform. You write Python agent code using the Line SDK, deploy it to Cartesia's managed cloud via the cartesia CLI, and Cartesia hosts it with auto-scaling. Cartesia handles STT (Ink), TTS (Sonic), telephony, and audio orchestration. Only one deployment per agent is active at a time; once deployed, your agent receives calls automatically.

┌─────────────────────────────────────────────────────────────────┐ │ Cartesia Line Platform │ │ ┌──────────┐ ┌──────────────┐ ┌──────────┐ │ │ │ Ink │───▶│ Your Agent │───▶│ Sonic │ │ │ │ (STT) │ │ (Line SDK) │ │ (TTS) │ │ │ └──────────┘ └──────────────┘ └──────────┘ │ │ ▲ │ │ │ │ Audio Orchestration │ │ │ └────────────────────────────────────┘ │ └─────────────────────────────────────────────────────────────────┘ ▲ │ │ WebSocket ▼ ┌───────┴────────────────────────────────────┴───────┐ │ Client (Phone / Web / Mobile) │ └─────────────────────────────────────────────────────┘

Your code handles:

• LLM reasoning and conversation flow

• Tool execution (API calls, database lookups)

• Multi-agent coordination and handoffs

Cartesia handles:

• Speech-to-text (Ink)

• Text-to-speech (Sonic)

• Real-time audio streaming

• Turn-taking and interruption detection

• Deployment and auto-scaling

Audio Input Options:

• Cartesia Telephony - Managed phone numbers

• Calls API - Web apps, mobile apps, custom telephony

Prerequisites

• Python 3.9+ and uv (recommended package manager)

• Cartesia API key — get one at play.cartesia.ai/keys (used by the CLI and for deployment)

• LLM API key — for whichever LLM provider your agent calls (e.g. ANTHROPIC_API_KEY , OPENAI_API_KEY , GEMINI_API_KEY )

• Cartesia CLI — install with: curl -fsSL https://cartesia.sh | sh

Cartesia CLI Reference

Authentication

cartesia auth login # Login with Cartesia API key cartesia auth status # Check auth status

Project Setup

cartesia create [project-name] # Create project from template cartesia init # Link existing directory to an agent

Local Development

cartesia chat <port> # Chat with local agent (text mode)

Deployment

cartesia deploy # Deploy to Cartesia cloud cartesia status # Check deployment status

Environment Variables (encrypted, stored on Cartesia)

cartesia env set KEY=VALUE # Set a single env var cartesia env set --from .env # Import all vars from .env file cartesia env rm <name> # Remove an env var

Agents & Calls

cartesia agents ls # List all agents cartesia deployments ls # List deployments cartesia call <phone> [agent-id] # Make outbound call

Quick Start

1. Create Project

cartesia auth login cartesia create my-agent cd my-agent

2. Write Agent Code

main.py :

import os from line.llm_agent import LlmAgent, LlmConfig, end_call from line.voice_agent_app import AgentEnv, CallRequest, VoiceAgentApp

async def get_agent(env: AgentEnv, call_request: CallRequest): return LlmAgent( model="anthropic/claude-haiku-4-5-20251001", api_key=os.getenv("ANTHROPIC_API_KEY"), tools=[end_call], config=LlmConfig( system_prompt="You are a helpful voice assistant.", introduction="Hello! How can I help you today?", ), )

app = VoiceAgentApp(get_agent=get_agent)

if name == "main": app.run()

3. Test Locally

ANTHROPIC_API_KEY=your-key python main.py cartesia chat 8000 # Text chat with your running agent

4. Deploy

cartesia env set ANTHROPIC_API_KEY=your-key # Encrypted, stored on Cartesia cartesia deploy cartesia status # Verify deployment is active

5. Make a Call

cartesia call +1234567890 # Outbound call via CLI

Or trigger calls from the Cartesia dashboard.

Project Structure

Every Line agent project MUST have:

my_agent/ ├── main.py # VoiceAgentApp entry point (REQUIRED) ├── cartesia.toml # Deployment config, created by cartesia init or cartesia create (REQUIRED) └── pyproject.toml # Dependencies: cartesia-line

Core Concepts

LlmAgent

The main agent class that wraps LLM providers via LiteLLM:

from line.llm_agent import LlmAgent, LlmConfig

agent = LlmAgent( model="gemini/gemini-2.5-flash-preview-09-2025", # LiteLLM model string api_key=os.getenv("GEMINI_API_KEY"), # Provider API key tools=[end_call, my_custom_tool], # List of tools config=LlmConfig(...), # Agent configuration max_tool_iterations=10, # Max tool call loops (default: 10) )

LlmConfig

Configuration for agent behavior and LLM sampling:

from line.llm_agent import LlmConfig

config = LlmConfig( # Agent behavior system_prompt="You are a helpful assistant.", introduction="Hello! How can I help?", # Set to "" to wait for user first

# Sampling parameters (optional)
temperature=0.7,
max_tokens=1024,
top_p=0.9,

# Resilience (optional)
num_retries=2,
timeout=30.0,
fallbacks=["gpt-4o-mini"],  # Fallback models

)

Dynamic Configuration from CallRequest

Use LlmConfig.from_call_request() to pull configuration from the incoming call:

async def get_agent(env: AgentEnv, call_request: CallRequest): return LlmAgent( model="anthropic/claude-sonnet-4-20250514", api_key=os.getenv("ANTHROPIC_API_KEY"), tools=[end_call], config=LlmConfig.from_call_request( call_request, fallback_system_prompt="Default system prompt if not in request.", fallback_introduction="Default introduction if not in request.", temperature=0.7, # Additional LlmConfig options ), )

Priority order: CallRequest value > fallback argument > SDK default

VoiceAgentApp

The application harness that manages HTTP endpoints and WebSocket connections:

from line.voice_agent_app import VoiceAgentApp, AgentEnv, CallRequest

async def get_agent(env: AgentEnv, call_request: CallRequest): # env.loop - asyncio event loop # call_request.call_id - unique call identifier # call_request.agent.system_prompt - from request # call_request.agent.introduction - from request # call_request.metadata - custom metadata dict return LlmAgent(...)

app = VoiceAgentApp(get_agent=get_agent) app.run(host="0.0.0.0", port=8000)

Built-in Tools

Import from line.llm_agent :

from line.llm_agent import end_call, send_dtmf, transfer_call, web_search

end_call

End the current call. Tell the LLM to say goodbye before calling this.

tools=[end_call]

System prompt: "Say goodbye before ending the call with end_call."

send_dtmf

Send DTMF tones (touch-tone buttons). Useful for IVR navigation.

tools=[send_dtmf]

Buttons: "0"-"9", "*", "#" (strings, not integers!)

transfer_call

Transfer to another phone number (E.164 format required).

tools=[transfer_call]

Example: +14155551234

web_search

Search the web for real-time information. Uses native LLM web search when available, falls back to DuckDuckGo.

Default settings

tools=[web_search]

Custom settings

tools=[web_search(search_context_size="high")] # "low", "medium", "high"

Custom Tool Types

Three tool paradigms for different use cases:

Type Decorator Use Case Result Handling

Loopback @loopback_tool

API calls, database lookups Result sent back to LLM

Passthrough @passthrough_tool

End call, transfer, DTMF Bypasses LLM, goes to user

Handoff @handoff_tool

Multi-agent workflows Transfers control to another agent

Tool Type Decision Tree

Does the result need LLM processing? ├─ YES → @loopback_tool │ └─ Is it long-running (>1s)? → @loopback_tool(is_background=True) │ └─ Yield interim status, then final result ├─ NO, deterministic action → @passthrough_tool │ └─ Yields OutputEvent objects directly (AgentSendText, AgentEndCall, etc.) └─ Transfer to another agent → @handoff_tool or agent_as_handoff()

Loopback Tools

Results are sent back to the LLM to inform the next response:

from typing import Annotated from line.llm_agent import loopback_tool, ToolEnv

@loopback_tool async def get_order_status( ctx: ToolEnv, order_id: Annotated[str, "The order ID to look up"], ) -> str: """Look up the current status of an order.""" order = await db.get_order(order_id) return f"Order {order_id} status: {order.status}, ETA: {order.eta}"

Parameter syntax:

• First parameter MUST be ctx: ToolEnv

• Use Annotated[type, "description"] for LLM-visible parameters

• Tool description comes from the docstring

• Optional parameters need default values (not just Optional[T] )

@loopback_tool async def search_products( ctx: ToolEnv, query: Annotated[str, "Search query"], category: Annotated[str, "Product category"] = "all", # Optional with default limit: Annotated[int, "Max results"] = 10, ) -> str: """Search the product catalog.""" ...

Passthrough Tools

Results bypass the LLM and go directly to the user/system:

from line.events import AgentSendText, AgentTransferCall from line.llm_agent import passthrough_tool, ToolEnv

@passthrough_tool async def transfer_to_support( ctx: ToolEnv, reason: Annotated[str, "Reason for transfer"], ): """Transfer the call to the support team.""" yield AgentSendText(text="Let me transfer you to our support team now.") yield AgentTransferCall(target_phone_number="+18005551234")

Output event types (from line.events ):

• AgentSendText(text="...")

• Speak text to user

• AgentEndCall()

• End the call

• AgentTransferCall(target_phone_number="+1...")

• Transfer call

• AgentSendDtmf(button="5")

• Send DTMF tone

Handoff Tools

Transfer control to another agent. See Multi-Agent Workflows.

Model Selection Strategy

Use FAST models for the main conversational agent:

• gemini/gemini-2.5-flash-preview-09-2025 (recommended)

• anthropic/claude-haiku-4-5-20251001

• gpt-4o-mini

Use POWERFUL models only via background tool calls for complex reasoning:

• anthropic/claude-opus-4-5

• gpt-4o

This pattern keeps conversations responsive while accessing deep reasoning when needed. See the Two-Tier Agent Pattern in Advanced Patterns for implementation.

LLM Providers

Line SDK uses LiteLLM model strings. Common formats:

Provider Format Example

OpenAI model_name

gpt-4o , gpt-4o-mini

Anthropic anthropic/model_name

anthropic/claude-sonnet-4-20250514

Google Gemini gemini/model_name

gemini/gemini-2.5-flash-preview-09-2025

Azure OpenAI azure/deployment_name

azure/my-gpt4-deployment

Set the appropriate API key environment variable:

• OPENAI_API_KEY

• ANTHROPIC_API_KEY

• GEMINI_API_KEY

• AZURE_API_KEY

Full list: https://docs.litellm.ai/docs/providers

Common Patterns

Agent with Custom Tools

from typing import Annotated from line.llm_agent import LlmAgent, LlmConfig, loopback_tool, end_call, ToolEnv

@loopback_tool async def check_appointment( ctx: ToolEnv, date: Annotated[str, "Date in YYYY-MM-DD format"], ) -> str: """Check available appointment slots for a given date.""" slots = await calendar.get_available_slots(date) return f"Available slots on {date}: {', '.join(slots)}"

@loopback_tool async def book_appointment( ctx: ToolEnv, date: Annotated[str, "Date in YYYY-MM-DD format"], time: Annotated[str, "Time in HH:MM format"], name: Annotated[str, "Customer name"], ) -> str: """Book an appointment slot.""" result = await calendar.book(date, time, name) return f"Appointment booked for {name} on {date} at {time}. Confirmation: {result.id}"

async def get_agent(env: AgentEnv, call_request: CallRequest): return LlmAgent( model="gemini/gemini-2.5-flash-preview-09-2025", api_key=os.getenv("GEMINI_API_KEY"), tools=[check_appointment, book_appointment, end_call], config=LlmConfig( system_prompt="""You are an appointment scheduling assistant. Help users check availability and book appointments. Always confirm the booking details before finalizing.""", introduction="Hi! I can help you schedule an appointment. What date works for you?", ), )

Wait for User to Speak First

Set introduction="" to have the agent wait for the user:

config=LlmConfig( system_prompt="You are a helpful assistant.", introduction="", # Empty string = wait for user )

Form Filling Pattern

See the form filler example for collecting structured data via voice. Key pattern:

@loopback_tool async def record_answer( ctx: ToolEnv, answer: Annotated[str, "The user's answer"], ) -> dict: """Record an answer to the current question.""" # Process and validate answer # Return next question or completion status return {"next_question": "What is your email?", "is_complete": False}

Common Mistakes to Avoid

Missing end_call tool - If not included (or a similar custom tool), the agent cannot end the call on its own and must wait for the user to hang up

Raising exceptions in tools - Return user-friendly error strings:

BAD

raise ValueError("Invalid order ID")

GOOD

return "I couldn't find that order. Please check the ID and try again."

Forgetting ctx parameter - First parameter must be ctx: ToolEnv :

GOOD

@loopback_tool async def my_tool(ctx: ToolEnv, order_id: Annotated[str, "Order ID"]): ...

Forgetting event in handoff tools - Handoff tools MUST have event parameter:

GOOD

@handoff_tool async def my_handoff(ctx: ToolEnv, param: Annotated[str, "desc"], event): ...

Missing Annotated descriptions - LLM needs parameter descriptions:

GOOD

async def my_tool(ctx, order_id: Annotated[str, "The order ID to look up"]): ...

Blocking on long operations - Use is_background=True and yield interim status:

@loopback_tool(is_background=True) async def slow_search(ctx: ToolEnv, query: Annotated[str, "Query"]): yield "Searching..." # Immediate feedback result = await slow_operation() yield result

Using sync APIs directly - Wrap sync calls with asyncio.to_thread() :

result = await asyncio.to_thread(sync_api_call, params)

Using slow models for main conversation - Use fast models (haiku, flash, mini) for the main agent, powerful models only via background tools.

Reference Documentation

• Tool Patterns - Deep dive on tool implementation

• Multi-Agent Workflows - Handoffs, wrappers, guardrails

• Advanced Patterns - Background tools, state, events

• Calls API - WebSocket integration for web/mobile apps

• Troubleshooting - Common issues and debugging

Key Imports

Core

from line.llm_agent import LlmAgent, LlmConfig from line.voice_agent_app import VoiceAgentApp, AgentEnv, CallRequest

Built-in tools

from line.llm_agent import end_call, send_dtmf, transfer_call, web_search

Tool decorators

from line.llm_agent import loopback_tool, passthrough_tool, handoff_tool

Tool context

from line.llm_agent import ToolEnv

Multi-agent

from line.llm_agent import agent_as_handoff

Events (for passthrough/handoff tools and custom agents)

from line.events import ( AgentSendText, AgentEndCall, AgentTransferCall, AgentSendDtmf, AgentUpdateCall, )

Key Reference Files

When implementing Line SDK agents, reference these example files:

• examples/basic_chat/main.py

• Simplest agent pattern

• examples/form_filler/

• Loopback tools with state

• examples/chat_supervisor/main.py

• Background tools with two-tier model strategy

• examples/transfer_agent/main.py

• Multi-agent handoffs

• examples/echo/tools.py

• Custom handoff tools