### Setup and Run Node.js LiveKit Agents Example Source: https://docs.cartesia.ai/integrations/live-kit Clone the livekit/agents-js repository, install dependencies, build the project, and run the Cartesia example agent. Requires CARTESIA_API_KEY, LIVEKIT credentials, and an LLM provider API key. Connect via WebRTC transport. ```bash # clone and setup livekit/agents-js git clone git@github.com:livekit/agents-js.git cd agents-js pnpm i && pnpm run build # run with required API keys: # - CARTESIA_API_KEY # - LIVEKIT_URL, LIVEKIT_API_KEY, LIVEKIT_API_SECRET # - some LLM provider's API key node ./examples/src/cartesia.ts dev # go to https://agents-playground.livekit.io/ # find your agent (make sure you're in the right org) # then connect to it with WebRTC transport ``` -------------------------------- ### Setup and Run Python LiveKit Agents Example Source: https://docs.cartesia.ai/integrations/live-kit Clone the livekit/agents repository, install dependencies, and run the Cartesia example agent. Requires CARTESIA_API_KEY, LIVEKIT credentials, and an LLM provider API key. ```bash # clone and setup livekit/agents git clone git@github.com:livekit/agents.git cd agents uv sync # run with required API keys: # - CARTESIA_API_KEY # - LIVEKIT_URL, LIVEKIT_API_KEY, LIVEKIT_API_SECRET # - some LLM provider's API key uv run examples/other/cartesia.py console ``` -------------------------------- ### Install Exa-py for Examples Source: https://docs.cartesia.ai/line/developer-tools/release-notes Install exa-py for Exa web search integration in examples. ```bash exa-py ``` -------------------------------- ### Run Get Voice Example (Python) Source: https://docs.cartesia.ai/llms-full.txt Instructions to clone the repository, install dependencies, and run the Python example for getting a voice. Requires setting the CARTESIA_API_KEY. ```sh git clone --branch v3.2.0 https://github.com/cartesia-ai/cartesia-python cd cartesia-python uv sync CARTESIA_API_KEY=YOUR_KEY uv run examples/examples.py voices_get [voice_id] ``` -------------------------------- ### Run Python Example Source: https://docs.cartesia.ai/examples/voices-list Clone the repository, install dependencies, and run the Python example to list voices. Ensure you set your CARTESIA_API_KEY environment variable. ```sh git clone --branch v3.2.0 https://github.com/cartesia-ai/cartesia-python cd cartesia-python uv sync CARTESIA_API_KEY=YOUR_KEY uv run examples/examples.py voices_list ``` -------------------------------- ### Run Get Voice Example (TypeScript) Source: https://docs.cartesia.ai/llms-full.txt Instructions to clone the repository, install dependencies, and run the TypeScript example for getting a voice. Requires setting the CARTESIA_API_KEY. ```sh git clone --branch v3.2.0 https://github.com/cartesia-ai/cartesia-js cd cartesia-js pnpm i CARTESIA_API_KEY=YOUR_KEY pnpm tsn examples/node_examples.ts voicesGet [voice_id] ``` -------------------------------- ### Install Duckduckgo-search for Examples Source: https://docs.cartesia.ai/line/developer-tools/release-notes Install duckduckgo-search for fallback web search functionality in examples. ```bash duckduckgo-search ``` -------------------------------- ### Run TypeScript Example Source: https://docs.cartesia.ai/examples/voices-list Clone the repository, install dependencies, and run the TypeScript example to list voices. Ensure you set your CARTESIA_API_KEY environment variable. ```sh git clone --branch v3.2.0 https://github.com/cartesia-ai/cartesia-js cd cartesia-js pnpm i CARTESIA_API_KEY=YOUR_KEY pnpm tsn examples/node_examples.ts voicesList ``` -------------------------------- ### Run Python Error Handling Example Source: https://docs.cartesia.ai/examples/error-handling Instructions to clone the repository, install dependencies, and run the Python error handling example with an API key. ```sh git clone --branch v3.2.0 https://github.com/cartesia-ai/cartesia-python cd cartesia-python uv sync CARTESIA_API_KEY=YOUR_KEY uv run examples/examples.py error_handling_example ``` -------------------------------- ### Run TypeScript Error Handling Example Source: https://docs.cartesia.ai/examples/error-handling Instructions to clone the repository, install dependencies, and run the TypeScript error handling example with an API key. ```sh git clone --branch v3.2.0 https://github.com/cartesia-ai/cartesia-js cd cartesia-js pnpm i CARTESIA_API_KEY=YOUR_KEY pnpm tsn examples/node_examples.ts errorHandling ``` -------------------------------- ### Run Infill Audio Example (Async Python) Source: https://docs.cartesia.ai/examples/infill-create Command to execute the asynchronous infill audio creation example. This requires cloning the repository, installing dependencies, and setting your Cartesia API key. ```sh git clone --branch v3.2.0 https://github.com/cartesia-ai/cartesia-python cd cartesia-python uv sync CARTESIA_API_KEY=YOUR_KEY uv run examples/async_examples.py infill_create_async left.wav right.wav "transcript to infill" ``` -------------------------------- ### Run STT Transcribe Example (Python) Source: https://docs.cartesia.ai/examples/stt-transcribe Clone the Cartesia Python repository, install dependencies, and run the synchronous STT transcribe example. Ensure you set your CARTESIA_API_KEY. ```sh git clone --branch v3.2.0 https://github.com/cartesia-ai/cartesia-python cd cartesia-python uv sync CARTESIA_API_KEY=YOUR_KEY uv run examples/examples.py stt_transcribe ``` -------------------------------- ### Clone and Run Next.js Example Source: https://docs.cartesia.ai/examples/nextjs Clone the Cartesia.js repository, install dependencies, and run the Next.js example project locally. Ensure you replace 'YOUR_KEY' with your actual Cartesia API key. ```sh git clone --branch v3.2.0 https://github.com/cartesia-ai/cartesia-js cd cartesia-js/examples/nextjs npm install CARTESIA_API_KEY=YOUR_KEY npm run dev ``` -------------------------------- ### Run STT Transcribe Example (Python Async) Source: https://docs.cartesia.ai/examples/stt-transcribe Clone the Cartesia Python repository, install dependencies, and run the asynchronous STT transcribe example. Ensure you set your CARTESIA_API_KEY. ```sh git clone --branch v3.2.0 https://github.com/cartesia-ai/cartesia-python cd cartesia-python uv sync CARTESIA_API_KEY=YOUR_KEY uv run examples/async_examples.py stt_transcribe_async ``` -------------------------------- ### Run Python TTS WebSocket Basic Example Source: https://docs.cartesia.ai/examples/tts-websocket-basic Clone the repository, install dependencies, and run the basic TTS WebSocket example using Python. Ensure you set your CARTESIA_API_KEY. ```sh git clone --branch v3.2.0 https://github.com/cartesia-ai/cartesia-python cd cartesia-python uv sync CARTESIA_API_KEY=YOUR_KEY uv run examples/examples.py tts_websocket_basic ``` -------------------------------- ### Run STT Transcribe Example (TypeScript Node.js) Source: https://docs.cartesia.ai/examples/stt-transcribe Clone the Cartesia JavaScript repository, install dependencies, and run the Node.js STT transcribe example. Ensure you set your CARTESIA_API_KEY. ```sh git clone --branch v3.2.0 https://github.com/cartesia-ai/cartesia-js cd cartesia-js pnpm i CARTESIA_API_KEY=YOUR_KEY pnpm tsn examples/node_examples.ts sttTranscribe ``` -------------------------------- ### Clone and Run Python Async TTS Example Source: https://docs.cartesia.ai/llms-full.txt Clone the Cartesia Python repository, install dependencies, and run an asynchronous text-to-speech generation example. Ensure you set your CARTESIA_API_KEY. ```sh git clone --branch v3.2.0 https://github.com/cartesia-ai/cartesia-python cd cartesia-python uv sync CARTESIA_API_KEY=YOUR_KEY uv run examples/async_examples.py tts_generate_async ``` -------------------------------- ### Run Python Async TTS WebSocket Basic Example Source: https://docs.cartesia.ai/examples/tts-websocket-basic Clone the repository, install dependencies, and run the basic asynchronous TTS WebSocket example using Python. Ensure you set your CARTESIA_API_KEY. ```sh git clone --branch v3.2.0 https://github.com/cartesia-ai/cartesia-python cd cartesia-python uv sync CARTESIA_API_KEY=YOUR_KEY uv run examples/async_examples.py tts_websocket_basic_async ``` -------------------------------- ### Run STT Manual Finalize WebSocket Example (Python) Source: https://docs.cartesia.ai/examples/stt-manual-finalize-websocket Clone the Cartesia Python repository, install dependencies, and run the STT manual finalize WebSocket example. Ensure you replace 'YOUR_KEY' with your actual Cartesia API key. ```sh git clone --branch v3.2.0 https://github.com/cartesia-ai/cartesia-python cd cartesia-python uv sync CARTESIA_API_KEY=YOUR_KEY uv run examples/examples.py stt_manual_finalize_websocket ``` -------------------------------- ### Run STT Manual Finalize WebSocket Example (Python Async) Source: https://docs.cartesia.ai/examples/stt-manual-finalize-websocket Clone the Cartesia Python repository, install dependencies, and run the asynchronous STT manual finalize WebSocket example. Replace 'YOUR_KEY' with your Cartesia API key. ```sh git clone --branch v3.2.0 https://github.com/cartesia-ai/cartesia-python cd cartesia-python uv sync CARTESIA_API_KEY=YOUR_KEY uv run examples/async_examples.py stt_manual_finalize_websocket_async ``` -------------------------------- ### Quick Start: Establish WebSocket Connection and Stream Audio Source: https://docs.cartesia.ai/line/integrations/websocket-api This JavaScript snippet demonstrates how to establish a WebSocket connection, send a 'start' event to initialize the stream, handle incoming audio from the agent, and send audio data from the user. ```javascript const ws = new WebSocket( `wss://api.cartesia.ai/agents/stream/${agentId}`, { headers: { Authorization: `Bearer ${accessToken}`, "Cartesia-Version": "2025-04-16", }, } ); // Initialize the stream ws.onopen = () => { ws.send(JSON.stringify({ event: "start", config: { input_format: "pcm_44100" }, })); }; // Handle agent audio ws.onmessage = (msg) => { const data = JSON.parse(msg.data); if (data.event === "media_output") { playAudio(atob(data.media.payload)); } }; // Send user audio function sendAudio(audioData) { ws.send(JSON.stringify({ event: "media_input", stream_id: streamId, media: { payload: btoa(audioData) }, })); } ``` -------------------------------- ### Run Python TTS WebSocket Example Source: https://docs.cartesia.ai/examples/tts-websocket-response-handling Clones the cartesia-python repository, installs dependencies, and runs the TTS WebSocket response handling example. ```sh git clone --branch v3.2.0 https://github.com/cartesia-ai/cartesia-python cd cartesia-python uv sync CARTESIA_API_KEY=YOUR_KEY uv run examples/examples.py tts_websocket_response_handling ``` -------------------------------- ### Run Infill Audio Example (Python) Source: https://docs.cartesia.ai/examples/infill-create Command to clone the repository, set up dependencies, and run the synchronous infill audio creation example. Ensure you replace 'YOUR_KEY' with your actual Cartesia API key. ```sh git clone --branch v3.2.0 https://github.com/cartesia-ai/cartesia-python cd cartesia-python uv sync CARTESIA_API_KEY=YOUR_KEY uv run examples/examples.py infill_create left.wav right.wav "transcript to infill" ``` -------------------------------- ### Create Project from Example Source: https://docs.cartesia.ai/line/cli Creates a new project by cloning an example agent from the Cartesia repository. ```zsh cartesia create ``` -------------------------------- ### Main Application Logic Source: https://docs.cartesia.ai/llms-full.txt Orchestrates the application startup, including connecting to TTS and Twilio WebSockets, setting up ngrok, and starting a call. ```javascript async function main() { try { log('Starting application'); await connectToTTSWebSocket(); log('TTS WebSocket connected successfully'); await testTTSWebSocket(); log('TTS WebSocket test passed successfully'); const twilioWebsocketPort = await setupTwilioWebSocket(); log(`Twilio WebSocket server set up on port ${twilioWebsocketPort}`); const twilioWebsocketUrl = await setupNgrokTunnel(twilioWebsocketPort); await startCall(twilioWebsocketUrl); } catch (error) { log(`Error in main function: ${error.message}`); } } // Run the script main(); ``` -------------------------------- ### Run TypeScript TTS WebSocket Example Source: https://docs.cartesia.ai/examples/tts-websocket-response-handling Clones the cartesia-js repository, installs dependencies, and runs the TTS WebSocket response handling example using Node.js. ```sh git clone --branch v3.2.0 https://github.com/cartesia-ai/cartesia-js cd cartesia-js pnpm i CARTESIA_API_KEY=YOUR_KEY pnpm tsn examples/node_examples.ts ttsWebsocketResponseHandling ``` -------------------------------- ### Run TTS SSE with Timestamps Example in Python Source: https://docs.cartesia.ai/examples/tts-sse-with-timestamps Clone the Cartesia Python repository, install dependencies, and run the synchronous TTS SSE with timestamps example. ```sh git clone --branch v3.2.0 https://github.com/cartesia-ai/cartesia-python cd cartesia-python uv sync CARTESIA_API_KEY=YOUR_KEY uv run examples/examples.py tts_sse_with_timestamps ``` -------------------------------- ### Clone and Run Python TTS Example Source: https://docs.cartesia.ai/llms-full.txt Clone the Cartesia Python repository, install dependencies, and run a text-to-speech generation example to a file. Ensure you set your CARTESIA_API_KEY. ```sh git clone --branch v3.2.0 https://github.com/cartesia-ai/cartesia-python cd cartesia-python uv sync CARTESIA_API_KEY=YOUR_KEY uv run examples/examples.py tts_generate_to_file ``` -------------------------------- ### Configure LlmAgent with Custom System Prompt and Tools Source: https://docs.cartesia.ai/line/sdk/agents Set up a detailed system prompt to define the agent's behavior and include specific tools like 'end_call'. This example demonstrates how to integrate the agent with the VoiceAgentApp. ```python import os from line import CallRequest from line.llm_agent import LlmAgent, LlmConfig, end_call from line.voice_agent_app import AgentEnv, VoiceAgentApp SYSTEM_PROMPT = """You are a friendly customer service agent. Rules: - Be polite and empathetic - Confirm understanding before taking action - end_call to gracefully end conversations """ 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=SYSTEM_PROMPT, introduction="Hello! How can I help you today?", ), ) app = VoiceAgentApp(get_agent=get_agent) if __name__ == "__main__": app.run() ``` -------------------------------- ### Create and Initialize Agent Project Source: https://docs.cartesia.ai/line/start-building/quickstart Initializes a new agent project named 'my-voice-agent' and adds the 'cartesia-line' dependency using uv. ```bash uv init my-voice-agent && cd my-voice-agent uv add cartesia-line ``` -------------------------------- ### Example: Using knowledge_base Tool Source: https://docs.cartesia.ai/llms-full.txt This example includes the `knowledge_base` tool, allowing the LLM to retrieve information from attached documents. The LLM will call this tool to answer questions based on the provided knowledge base. ```python # Knowledge base: look up the agent's attached documents tools=[knowledge_base] # LLM calls this to answer from uploaded docs ``` -------------------------------- ### Run TTS SSE with Timestamps Example in TypeScript Source: https://docs.cartesia.ai/examples/tts-sse-with-timestamps Clone the Cartesia JavaScript repository, install dependencies, and run the TTS SSE with timestamps example using Node.js. ```sh git clone --branch v3.2.0 https://github.com/cartesia-ai/cartesia-js cd cartesia-js pnpm i CARTESIA_API_KEY=YOUR_KEY pnpm tsn examples/node_examples.ts ttsSSEWithTimestamps ``` -------------------------------- ### Initialize Node.js Project Source: https://docs.cartesia.ai/integrations/twilio Initializes a new Node.js project. Run this command in your project's root directory. ```bash npm init -y ``` -------------------------------- ### Run TTS SSE with Timestamps Example in Python (Async) Source: https://docs.cartesia.ai/examples/tts-sse-with-timestamps Clone the Cartesia Python repository, install dependencies, and run the asynchronous TTS SSE with timestamps example. ```sh git clone --branch v3.2.0 https://github.com/cartesia-ai/cartesia-python cd cartesia-python uv sync CARTESIA_API_KEY=YOUR_KEY uv run examples/async_examples.py tts_sse_with_timestamps_async ``` -------------------------------- ### Word Timestamps Response Example Source: https://docs.cartesia.ai/api-reference/tts/websocket An example of a response containing word-level timing information. This format is used to provide start and end times for each word in the synthesized speech. ```json { "type": "timestamps", "done": false, "status_code": 206, "context_id": "872ec12d-bc63-4e1e-a241-4f58c879d105", "word_timestamps": { "words": [ "Hello", "world" ], "start": [ 0, 0.5 ], "end": [ 0.4, 0.9 ] } } ``` -------------------------------- ### Install Line SDK Source: https://docs.cartesia.ai/line/sdk/overview Use the uv package manager to add the Line SDK to your project. ```bash uv add cartesia-line ``` -------------------------------- ### Clone and Run TypeScript TTS Example Source: https://docs.cartesia.ai/llms-full.txt Clone the Cartesia JavaScript repository, install dependencies, and run a text-to-speech generation example using Node.js. Ensure you set your CARTESIA_API_KEY. ```sh git clone --branch v3.2.0 https://github.com/cartesia-ai/cartesia-js cd cartesia-js pnpm i CARTESIA_API_KEY=YOUR_KEY pnpm tsn examples/node_examples.ts ttsGenerateToFile ``` -------------------------------- ### Install Python SDK Source: https://docs.cartesia.ai/tools/client-libraries Install the official Python SDK from PyPI. Includes optional support for websockets. ```sh pip install --pre cartesia # for websocket support pip install 'cartesia[websockets]' ``` -------------------------------- ### Configure Built-in Tools Source: https://docs.cartesia.ai/line/developer-tools/release-notes Initialize an LlmAgent with standard tools like web search, DTMF sending, and call transfers. ```python from line.llm_agent import end_call, send_dtmf, transfer_call, web_search, agent_as_handoff agent = LlmAgent( tools=[ end_call, # End the call send_dtmf, # Send DTMF tones transfer_call, # Transfer to phone number web_search, # Real-time web search agent_as_handoff(other_agent, name="transfer_to_billing"), ], ... ) ``` -------------------------------- ### Run TypeScript TTS WebSocket Basic Example Source: https://docs.cartesia.ai/examples/tts-websocket-basic Clone the repository, install dependencies, and run the basic TTS WebSocket example using TypeScript. Ensure you set your CARTESIA_API_KEY. ```sh git clone --branch v3.2.0 https://github.com/cartesia-ai/cartesia-js cd cartesia-js pnpm i CARTESIA_API_KEY=YOUR_KEY pnpm tsn examples/node_examples.ts ttsWebsocketBasic ``` -------------------------------- ### Instantiate Router Agent with LlmAgents Source: https://docs.cartesia.ai/llms-full.txt Example of how to configure and use the RouterAgent with multiple specialized LlmAgents, including setting up their models and system prompts. ```python async def get_agent(env, call_request): return RouterAgent( default_agent=LlmAgent( model="gpt-5-nano", api_key=os.getenv("OPENAI_API_KEY"), config=LlmConfig(system_prompt="You are a helpful assistant..."), ), specialists={ "billing": LlmAgent( model="gpt-5-nano", api_key=os.getenv("OPENAI_API_KEY"), config=LlmConfig(system_prompt="You are a billing specialist..."), ), "technical": LlmAgent( model="anthropic/claude-haiku-4-5-20251001", api_key=os.getenv("ANTHROPIC_API_KEY"), config=LlmConfig(system_prompt="You are a technical support specialist..."), ), } ) ``` -------------------------------- ### Create a New Agent Source: https://docs.cartesia.ai/line/cli Creates a new agent project from an example in the Line repository. Navigate into the created directory afterwards. ```zsh cartesia create my-agent # Choose any example you like. cd my-agent ``` -------------------------------- ### List Templates Source: https://docs.cartesia.ai/api-reference/agents/agents/templates Lists public, Cartesia-provided agent templates to help you get started. ```APIDOC ## GET /agents/templates ### Description List of public, Cartesia-provided agent templates to help you get started. ### Method GET ### Endpoint /agents/templates ### Parameters #### Header Parameters - **Cartesia-Version** (string) - Required - API version header. Example: '2026-03-01' ### Request Example (No request body for GET request) ### Response #### Success Response (200) - **templates** (array) - List of agent templates. - **id** (string) - The ID of the agent template. - **name** (string) - The name of the agent template. - **description** (string) - The description of the agent template. - **repo_url** (string) - The URL of the Git repository associated with the agent template. - **root_dir** (string) - The root directory of the agent template. - **required_env_vars** (array) - The required environment variables for the agent template. - **dependencies** (array) - The dependencies of the agent template. - **owner_id** (string) - The ID of the owner of the agent template. - **created_at** (string) - The UTC timestamp when the agent template was created. - **updated_at** (string) - The UTC timestamp when the agent template was last updated. #### Response Example { "templates": [ { "id": "string", "name": "string", "description": "string", "repo_url": "string", "root_dir": "string", "required_env_vars": [ "string" ], "dependencies": [ "string" ], "owner_id": "string", "created_at": "string", "updated_at": "string" } ] } ``` -------------------------------- ### Initialize LlmAgent with Basic Configuration Source: https://docs.cartesia.ai/line/sdk/agents Use the built-in LlmAgent to wrap LLM providers. Specify the model, API key, optional tools, and configuration including system prompt and introduction. ```python from line.llm_agent import LlmAgent, LlmConfig agent = LlmAgent( model="anthropic/claude-haiku-4-5-20251001", # Or "gpt-5.2", "gemini/gemini-2.5-flash", etc. api_key="your-api-key", tools=[...], # Optional list of tools config=LlmConfig( system_prompt="You are a helpful assistant...", introduction="Hello! How can I help you today?", ), ) ``` -------------------------------- ### Run Voice Update Example (TypeScript) Source: https://docs.cartesia.ai/llms-full.txt Clones the Cartesia JS repository, installs dependencies, and executes the voice update example. Requires a Cartesia API key and a voice ID. ```sh git clone --branch v3.2.0 https://github.com/cartesia-ai/cartesia-js cd cartesia-js pnpm i CARTESIA_API_KEY=YOUR_KEY pnpm tsn examples/node_examples.ts voicesUpdate "Updated Name" ``` -------------------------------- ### Example: Scoped knowledge_base Tool with Filters Source: https://docs.cartesia.ai/llms-full.txt This example configures the `knowledge_base` tool to search within a specific category ('billing') and limits the results to the top 10. It also provides a tailored description for the LLM. ```python # Knowledge base scoped to a metadata filter with a tailored prompt tools=[knowledge_base( filters={"category": "billing"}, top_k=10, description="Look up billing and payment policy details.", )] ``` -------------------------------- ### Run TypeScript TTS WebSocket Continuations Example Source: https://docs.cartesia.ai/examples/tts-websocket-continuations Clone the Cartesia JavaScript repository, install dependencies, and run the TypeScript TTS WebSocket continuations example. Ensure you set your CARTESIA_API_KEY. ```sh git clone --branch v3.2.0 https://github.com/cartesia-ai/cartesia-js cd cartesia-js pnpm i CARTESIA_API_KEY=YOUR_KEY pnpm tsn examples/node_examples.ts ttsWebsocketContinuations ```