Create an Agent

Configure a voice agent with a prompt, voice, and metadata variables, then copy your agent_id

An agent is your configured voice AI — it has a personality (defined by its prompt), a voice, and optional dynamic variables that get filled in at call time. In this step, you’ll create one in the dashboard and get the agent_id you’ll need for every API call.

Before you start: You need a Vaani account. If you haven’t signed up yet, head to Create an Account first.

What is an Agent?

Think of an agent as a recipe for how your AI handles phone calls:

• Prompt — the instructions that define what the agent says and how it behaves
• Language & Voice — which language it speaks and what it sounds like
• Metadata Variables — dynamic placeholders in the prompt (like {customer_name}) that get filled in with real data at call time

You can create multiple agents for different use cases — one for sales follow-ups, another for appointment reminders, another for customer surveys. Each agent can handle many calls simultaneously.

Create Your Agent

1. Navigate to Agent Config

   In the dashboard sidebar, click Agent Config, then click Create Agent.

   
2. Set a Name

   Give your agent an internal name. This is for your reference only — callers never hear it. Use something descriptive like sales-followup-v1 or appointment-reminder rather than generic names like test agent.

3. Write Your Prompt

   The prompt is the most important part of your agent. It defines the agent’s personality, goals, and how it handles different situations. See Writing a Good Prompt below for guidance.

4. Choose Language and Voice

   Select the language your agent will speak. This affects both speech recognition (how well it understands callers) and text-to-speech (how it sounds). Then pick a voice from the available options for that language.

5. Define Metadata Variables (Optional)

   If your prompt uses dynamic placeholders like {customer_name}, define them here. You’ll pass the actual values through the API when triggering each call. See Understanding Metadata Variables below for details.

6. Save and Copy the Agent ID

   Click Save. Your agent is now created. Copy the Agent ID — this is the UUID you’ll use in every API call to identify this agent.

   

The agent_id is a UUID (e.g. 8cf3373e-eb6f-4b4c-9f3c-324a56a91147). Do not confuse it with the agent’s display name. When the API asks for agent_id, it always means this UUID.

Not sure which identifier is which? See the identifier reference table for a quick comparison of agent_id, API key, call_id, and outbound_number.

Writing a Good Prompt

Your prompt is the single biggest factor in how well your agent performs. Here are practical tips:

• Start with the role and personality. Tell the agent who it is and how it should behave. (“You are a friendly sales representative for .”)
• Give clear instructions. Describe what the agent should do on the call — its goal, what questions to ask, how to handle objections.
• Use {variable_name} for anything that changes per call. Names, dates, product details — anything dynamic should be a variable, not hardcoded.
• Keep it focused. A prompt that tries to handle every possible scenario usually handles none of them well. Start simple, test with real calls, and iterate.

Here’s an example of a short but effective prompt:

You are a friendly sales representative for {company_name}.
You are calling {customer_name} to follow up on their interest in {property_name}.
Be polite, answer questions about the property, and try to schedule a site visit.
If they're not interested, thank them and end the call gracefully.

Understanding Metadata Variables

Metadata variables let you personalize each call without creating separate agents. Here’s how they work:

1. Define placeholders in your prompt using curly braces:

Hello {customer_name}, I'm calling from {company_name} about {property_name}.

2. Pass the values via the API when you trigger a call:

"metadata": {
  "customer_name": "Rahul Sharma",
  "company_name": "Acme Properties",
  "property_name": "Prateek Laurel"
}

3. Vaani replaces the placeholders before the call starts, so your agent says:

“Hello Rahul Sharma, I’m calling from Acme Properties about Prateek Laurel.”

Variable names in your metadata must exactly match the {placeholders} in your prompt — including capitalization. If your prompt says {customer_name} but your metadata sends "Customer_Name", the replacement won’t work and the agent will say the placeholder literally.

Start simple. Create a basic agent with a short prompt, test it with a real call, then iterate on the prompt based on what you hear. You can edit the agent’s prompt anytime without changing its agent_id — edits apply to all future calls immediately.

Troubleshooting

My agent says the variable name literally (e.g. says '{customer_name}')

The metadata key you’re passing in the API doesn’t match the placeholder in your prompt. Check that the spelling and capitalization match exactly. For example, if your prompt uses {customer_name}, your metadata must use "customer_name" — not "customerName" or "Customer_Name".

Where do I find my agent_id?

Go to Agent Config in the dashboard. Your agent’s ID (UUID) is displayed on the agent’s detail page. Click the copy button next to it. The agent_id looks like 8cf3373e-eb6f-4b4c-9f3c-324a56a91147 — it’s the UUID, not the display name you gave the agent.

Can I change my agent's prompt after creating it?

Yes. Edits to the prompt, voice, language, or metadata variables take effect on all future calls immediately. Calls that are already in progress are not affected.

Video walkthrough coming soon. Follow the steps above — they cover everything the video will.

Next Step

Set Up Telephony

Connect a phone number so your agent can make and receive real calls