Talk to your first agent

Create a new voice agent, deploy it and talk to it in under 5 minutes. Then, learn how to make a quick change to customize an agent.

Already created an agent in the Playground?

Other guides might be a better starting point for you.

○If you used Text to Agent, try this quickstart.
○If you used Build From a Template, try this quickstart.

Deploy and call your first agent

Prerequisites

○A free Cartesia account, sign up here.
○Access to a terminal on your local machine.

Install the CLI

1 curl -fsSL https://cartesia.sh | sh

Connect to Cartesia

Authenticate with your Cartesia account. This will prompt you to add an API key from your playground.

1 cartesia auth login

Verify authentication succeeded.

1 cartesia auth status

Clone a Line template locally

Clone a simple chat template using the CLI.

1 {{CREATE_COMMAND}} simple-chat-example
2 # Choose "Basic Chat" when prompted by `cartesia create`.
3 cd simple-chat-example

Initialize your agent

Link your local template to a Cartesia agent.

1 cartesia init
2 # Choose "Create new", and name the agent "first-agent".

You’ll see a success message with a link to your agent in the playground.

1 ✓ Agent 'first-agent' created successfully
2 
3 View agent:
4 https://play.cartesia.ai/agents/agent_xxxxxxxxxxxxxxxxxx

Deploy your agent

Deploy your agent to make it available in the playground.

1 cartesia deploy

You’ll see deployment progress with a status command to track it.

1 Deploying cli-test
2 
3 ✓ File uploaded (ID: file_xxxxxxxxxxxxxxxxxx)
4 ✓ Deployment created successfully!
5 
6 Check deployment progress:
7 cartesia status ad_xxxxxxxxxxxxxxxxxx

Talk to your agent

Your agent should deploy in < 1 minute. Use the CLI to have your agent call your phone number.

1 cartesia call +1XXXXXXXXXX

Or visit the Playground to call your agent from the web interface.

This first agent should only give you canned responses. Next, we’ll enable it to give intelligent responses.

Setup local agent development

Now let’s set up your local environment to iterate on your agent.

Additional Prerequisites

○Python 3.9+ installed on your machine.
●A Gemini API key (recommended for intelligent responses).(optional)

Install dependencies

Choose your preferred Python package manager.

uv

pip

conda

1 uv venv --python 3.11
2 uv pip install .

(Optional) Setup your LLM API key

Set your Gemini API key to connect a language model.

Line supports integrations with any LLM provider of your choice.

1 export GEMINI_API_KEY=YOUR_GEMINI_KEY

If you choose to skip this step, your agent will continue to give canned answers.

Chat locally with your template

Open two terminals. In the first, start the server.

uv

pip/conda

1 uv run python main.py

In the second terminal, chat with your agent.

1 cartesia chat 8000

This is a nifty way to test your agent’s reasoning and responses locally.

Customize and redeploy your agent

Let’s customize your agent’s personality and voice to make it truly unique.

Customize your agent

Open config.py and modify SYSTEM_PROMPT to set your agent’s personality.

config.py

1 SYSTEM_PROMPT = """\
2 You are Chef Pierre, a passionate French chef from Lyon who just opened your first bistro. 
3 You're excited to share cooking tips and French recipes. 
4 Speak with warmth and enthusiasm about food. 
5 Keep responses to 1-2 sentences under 35 words since you're on the phone.\
6 """

Update the initial message in main.py in the handle_new_call function.

main.py

1 await system.send_initial_message("Bonjour! I'm Chef Pierre.")

(Optional) Set remote environment variables

If you set a Gemini API key earlier, make it available to your deployed agent. Your prompt change will have no effect without this key.

Make sure to run this command in the same terminal where you previously set the GEMINI_API_KEY environment variable.

1 cartesia env set GEMINI_API_KEY=$GEMINI_API_KEY

Redeploy your changes

Verify that you’re in the simple-chat-example folder and redeploy your changes.

1 cartesia deploy

Check deployment status

Check that your deployment is ready and get your agent URL.

1 cartesia status

Visit your agent page in the Playground using the URL from the status command.

Update voice in the Playground

On your agent page, go to Configuration. Change the voice to “Stern French Man” to match your chef personality.

Update voice in the Configuration tab on the Playground.

Call your custom agent

1 cartesia call +1XXXXXXXXXX