Build intelligent, low-latency voice agents with Line.
Line brings voice to your text agents with Cartesia's state-of-the-art speech models. We handle audio orchestration, deployment, and observability so you can focus on your agent's reasoning.
- Real-time interruption support — Handles audio interruptions and turn-taking out-of-the-box
- Tool calling — Connect to databases, APIs, and external services
- Multi-agent handoffs — Route conversations between specialized agents
- Web search — Built-in tool for real-time information lookup
- 100+ LLM providers — Works with any LLM via LiteLLM
- Instant deployment — Build, deploy, and start talking in minutes
1. Clone and run an example:
git clone https://github.com/cartesia-ai/line.git
cd line/examples/basic_chat
GEMINI_API_KEY=your-key uv run python main.py2. Or create from scratch:
mkdir my-agent && cd my-agent
uv init && uv add cartesia-lineCreate main.py:
import os
from line.llm_agent import LlmAgent, LlmConfig, end_call
from line.voice_agent_app import VoiceAgentApp
async def get_agent(env, call_request):
return LlmAgent(
model="gemini/gemini-2.5-flash-preview-09-2025",
api_key=os.getenv("GEMINI_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()Run it:
GEMINI_API_KEY=your-key uv run python main.py3. (Optional) Install the CLI to test locally:
curl -fsSL https://cartesia.sh | shThen chat with your agent:
PORT=8000 uv run python main.py
cartesia chat 8000See the CLI documentation for deployment and management commands.
Configure your agent's personality and behavior via LlmConfig:
config = LlmConfig(
system_prompt="You are a customer service agent for Acme Corp. Be friendly and concise.",
introduction="Hi! Thanks for calling Acme. How can I help?",
)system_prompt— Defines the agent's personality, rules, and contextintroduction— First message spoken when the call starts (set to""to wait for user)
Use LlmConfig.from_call_request() to configure prompts dynamically from your API:
async def get_agent(env: AgentEnv, call_request: CallRequest):
# Prompts come from call_request.agent.system_prompt and call_request.agent.introduction
# Falls back to your defaults if not provided
return LlmAgent(
model="gemini/gemini-2.5-flash-preview-09-2025",
tools=[end_call],
config=LlmConfig.from_call_request(
call_request,
fallback_system_prompt="You are a helpful assistant.",
fallback_introduction="Hello! How can I help?",
),
)Ready-to-use tools for common actions:
from line.llm_agent import LlmAgent, LlmConfig, end_call, knowledge_base, send_dtmf, transfer_call, voicemail, web_search
agent = LlmAgent(
model="gemini/gemini-2.5-flash-preview-09-2025",
tools=[end_call, send_dtmf, transfer_call, voicemail, web_search, knowledge_base],
config=LlmConfig(...),
)| Tool | What it does |
|---|---|
end_call |
Ends the call |
send_dtmf |
Presses phone buttons (0-9, *, #) |
transfer_call |
Transfers to a phone number (E.164). LLM-supplied by default, or pin a fixed destination with transfer_call(target_phone_number="+1...") |
voicemail |
Ends the call when you reach a voicemail, optionally leaving a message first. Configure with voicemail(message="…"). See Voicemail detection. |
web_search |
Searches the web (native LLM search or DuckDuckGo fallback) |
knowledge_base |
Looks up information from the agent's knowledge base via natural-language query. Call knowledge_base(filters={...}, top_k=10) to pre-filter retrievals or override top_k |
http_server_tool |
Creates an HTTP tool from JSON schemas (see below) |
Add the voicemail tool and the agent hangs up — after an optional message —
when it recognizes a voicemail or answering-machine greeting. On outbound calls,
set introduction="" so the agent stays silent until it hears the callee's
opening line:
from line.llm_agent import LlmAgent, LlmConfig, end_call, voicemail
agent = LlmAgent(
model="anthropic/claude-haiku-4-5-20251001",
api_key=os.getenv("ANTHROPIC_API_KEY"),
tools=[voicemail(message="Hi, please call us back when you can."), end_call],
config=LlmConfig(system_prompt=SYSTEM_PROMPT, introduction=""), # outbound: wait for the callee
)Configuration options:
voicemail # silently end the call on a voicemail
voicemail(message="Sorry we missed you.") # speak the message (uninterruptible), then end
voicemail(interruptible=True) # allow the message/hangup to be interrupted
voicemail(description="…") # override the LLM-facing "when to call this" texthttp_server_tool creates a tool that makes HTTP requests when the LLM calls it. Define the request shape with JSON schemas — no custom tool function needed:
from line.llm_agent import http_server_tool
create_ticket = http_server_tool(
name="create_ticket",
description="Creates a support ticket for the caller.",
url="https://api.example.com/v1/{tenant_id}/tickets",
method="POST",
request_body_schema={
"type": "object",
"required": ["subject", "priority"],
"properties": {
"subject": {"type": "string", "description": "Short summary of the issue."},
"priority": {"type": "string", "enum": ["low", "medium", "high"]},
# constant_value: hidden from the LLM, baked into every request
"source": {"type": "string", "constant_value": "voice_agent"},
},
},
# ${ENV_VAR} resolved from os.environ at build time
auth={"Authorization": "Bearer ${SUPPORT_API_KEY}"},
)
agent = LlmAgent(tools=[create_ticket, end_call], ...)The LLM sees subject, priority, and tenant_id (from the URL template). It never sees source — that's injected automatically. The ${SUPPORT_API_KEY} is resolved from your environment when the tool is created.
Query parameter tools work the same way for GET requests:
search_orders = http_server_tool(
name="search_orders",
description="Search orders by status.",
url="https://api.example.com/orders",
method="GET",
query_params_schema={
"type": "object",
"required": ["status"],
"properties": {
"status": {"type": "string", "enum": ["pending", "shipped", "delivered"]},
"api_key": {"type": "string", "constant_value": "pk_live_abc123"},
},
},
)Response format — the LLM always receives structured JSON:
{"ok": true, "status": 201, "body": "{\"ticket_id\": \"TKT-001\"}"}
{"ok": false, "status": 500, "error": "Internal server error"}
{"ok": false, "status": null, "error": "Request timed out after 5.0s."}Results go back to the LLM for a natural language response:
from typing import Annotated
from line.llm_agent import loopback_tool
@loopback_tool
async def get_order_status(ctx, order_id: Annotated[str, "The order ID"]) -> str:
"""Look up order status."""
order = await db.get_order(order_id)
return f"Order {order_id}: {order.status}"
agent = LlmAgent(tools=[get_order_status, end_call], ...)User: "What's the status of order 12345?" Agent: Calls tool → LLM responds: "Your order was delivered on January 5th!"
Output goes directly to the user, bypassing the LLM:
from typing import Annotated
from line.events import AgentSendText, AgentTransferCall
from line.llm_agent import passthrough_tool
@passthrough_tool
async def transfer_to_support(ctx, reason: Annotated[str, "Why they need support"]):
"""Transfer to support team."""
yield AgentSendText(text="Transferring you to support now.")
yield AgentTransferCall(target_phone_number="+18005551234")
agent = LlmAgent(tools=[transfer_to_support, end_call], ...)Transfer control to a specialized agent:
from line.llm_agent import LlmAgent, LlmConfig, agent_as_handoff, end_call
spanish_agent = LlmAgent(
model="anthropic/claude-sonnet-4-5",
tools=[end_call],
config=LlmConfig(
system_prompt="You speak only in Spanish.",
introduction="¡Hola! ¿Cómo puedo ayudarte?",
),
)
main_agent = LlmAgent(
model="gemini/gemini-2.5-flash-preview-09-2025",
tools=[
end_call,
agent_as_handoff(
spanish_agent,
handoff_message="Transferring you to our Spanish-speaking agent...",
name="transfer_to_spanish",
description="Transfer when user wants to speak Spanish.",
),
],
config=LlmConfig(system_prompt="Transfer to Spanish if requested."),
)| Type | How to create | Result goes to | Use for |
|---|---|---|---|
| Loopback | @loopback_tool |
Back to LLM | API calls, data lookup |
| Passthrough | @passthrough_tool |
Directly to user | Deterministic actions |
| Handoff | agent_as_handoff() or @handoff_tool |
Another agent | Multi-agent workflows |
By default, tool calls are terminated when the agent is interrupted (though any reasoning and tool call response values already produced are preserved for use in the next generation).
For tools that take a long time to complete, set is_background=True. The tool will continue running in the background until completion regardless of interruptions, then loop back to the LLM:
from typing import Annotated
from line.llm_agent import loopback_tool
@loopback_tool(is_background=True)
async def search_database(ctx, query: Annotated[str, "Search query"]) -> str:
"""Search that may take a while."""
results = await slow_database_search(query)
return resultsControl what the LLM sees in its conversation history using agent.history.add_entry and agent.history.update.
Insert text into the LLM's conversation history. This is useful for injecting context for controlling exactly what the LLM sees from tool calls, or integrating information from external APIs.
from line.llm_agent import LlmAgent, LlmConfig, loopback_tool
agent = LlmAgent(
model="gemini/gemini-2.5-flash-preview-09-2025",
api_key=os.getenv("GEMINI_API_KEY"),
config=LlmConfig(system_prompt="You are a helpful assistant."),
)
# Inject context before the conversation starts
agent.history.add_entry("The customer's name is Alice and she has a premium account.")
# Or inject context from within a tool call
@loopback_tool
async def lookup_customer(ctx, customer_id: str) -> str:
"""Look up customer details."""
customer = await db.get_customer(customer_id)
# Inject rich context that persists across turns
agent.history.add_entry(f"Customer profile: {customer.summary}")
return f"Found customer {customer.name}"Each entry defaults to a user message (role="user"). Pass role="system" to inject a system note instead. By default entries are appended at the end of history; pass the before= or after= anchor keyword (a HistoryEvent already in history) to insert relative to a specific event.
agent.history.update(events, *, start=None, end=None) replaces a segment of history with a new list of HistoryEvent items. The optional start and end anchors (events already present in history) determine which segment is replaced:
- Neither anchor —
eventsare prefixed before the existing history. startonly — replaces fromstartthrough the end of history.endonly — replaces from the beginning of history throughend(inclusive).- Both anchors — replaces the segment
[start..end]inclusive.
from line import CustomHistoryEntry
# Prefix the history with a reminder (neither anchor)
agent.history.update([CustomHistoryEntry(content="Remember: be concise and friendly.")])
# Replace everything from `marker` onward (start only)
agent.history.update(
[CustomHistoryEntry(content="Conversation summarized.")],
start=marker,
)
# Replace the inclusive segment between two known events (both anchors)
agent.history.update(
[CustomHistoryEntry(content="(redacted)")],
start=first_event,
end=last_event,
)update raises ValueError if an anchor is not found in the current history, or if end appears before start.
Implement the Agent protocol to add guardrails, logging, or preprocessing:
from line.agent import TurnEnv
from line.events import InputEvent, OutputEvent, UserTurnEnded, AgentSendText
from line.llm_agent import LlmAgent, LlmConfig, end_call
class GuardedAgent:
def __init__(self, inner_agent):
self.inner = inner_agent
self.blocked_words = ["competitor", "confidential"]
async def process(self, env: TurnEnv, event: InputEvent):
# Pre-process: check user input for blocked words
if isinstance(event, UserTurnEnded):
user_text = " ".join(
item.content for item in event.content if hasattr(item, "content")
)
if any(word in user_text.lower() for word in self.blocked_words):
yield AgentSendText(text="I can't discuss that topic.")
return
# Delegate to inner agent
async for output in self.inner.process(env, event):
yield output
async def get_agent(env, call_request):
inner = LlmAgent(
model="gemini/gemini-2.5-flash-preview-09-2025",
tools=[end_call],
config=LlmConfig(system_prompt="You are a helpful assistant."),
)
return GuardedAgent(inner)Line leverages LiteLLM to support 100+ LLM providers. Pass any LiteLLM-compatible model string to LlmAgent:
| Provider | Model format |
|---|---|
| OpenAI | gpt-5-nano, gpt-5.2 |
| Anthropic | anthropic/claude-haiku-4-5-20251001, anthropic/claude-sonnet-4-5 |
gemini/gemini-2.5-flash-preview-09-2025 |
| Example | Description |
|---|---|
| Basic Chat | Simple conversational agent |
| Form Filler | Collect structured data |
| Phone Transfer | IVR navigation & transfers |
| Multi-Agent | Hand off between agents |
| Echo Tool | Custom handoff tool |
| Integration | Description |
|---|---|
| Exa Web Research | Real-time web search |
| Browserbase | Fill web forms via voice |
- SDK Overview — Architecture and installation
- Tools Guide — Tool types in depth
- Agents Guide — LlmAgent, custom agents, conversation loop
- Events Reference — Input/output events
Line leverages the fantastic work by the maintainers of LiteLLM. Their open-source library provides the unified LLM interface that makes it possible to support 100+ providers out of the box.
LiteLLM is licensed under the MIT License.