How to build an AI phone agent, step by step

An AI phone agent is built in seven passes: choose the agent type, write its job in plain prose, pick a voice and accent, load the facts it will be asked for, connect the actions it can take, attach a number, then call it and read the transcript. Each pass is a section of one page in the dashboard, and the agent answers calls by the end of it.

This guide walks that page top to bottom. Nothing here needs code, though every step has an API equivalent if you would rather script it.

What do you need before you start?

Three things, and none of them are technical.

First, a written answer to what this agent is for. Booking tables, chasing an unpaid invoice, telling people where their order is. One job. An agent asked to do five jobs does all five badly, and the instruction budget will not stretch to cover them anyway.

Second, the facts it will be asked for. Opening hours, the price list, the returns policy, the questions your team answers forty times a week. A plain document is fine.

Third, a phone you can call from that is not the phone the agent answers on. You will use it in step 7, and it is the only honest test there is.

Everything below happens in the dashboard, so create a free account and follow along with the screens open. Twenty minutes gets you to a working call. If you want to know what that call will cost before you point real traffic at it, pricing breaks the minute down, and phone agents covers what the channel does once it is live.

Step 1: Create the agent and pick its type

Open Agent, then New Agent in the sidebar. The first thing you see is a dialog titled Choose Agent Type, with the line "Select the type of agent you want to create. This cannot be changed later."

Two cards:

• Voice Agent, described as a live call AI agent with voice capabilities.
• Chat Agent, a web widget chat agent for your website.

Pick Voice Agent. The warning about not changing it later is literal, so if you eventually want both a phone line and a website widget, you will build two agents and point them at the same knowledge. That is a supported pattern, not a workaround.

Give the agent a name in the Agent name field. This is internal. Callers never hear it, so name it after the job rather than the persona: "Reservations line" beats "Alex".

Step 2: Write the agent's job in one paragraph

Four text fields define how the agent behaves, and all four are short on purpose.

Agent Identity is who it is. One or two sentences, written in the second person, of the form "You are a reservations assistant for a restaurant in central Bengaluru. Your name is Nina."

Agent Personality is how it sounds in words rather than in audio. Calm, brisk, apologetic when something has gone wrong. This field does more work than people expect, because it governs sentence length and how quickly the agent gives up on a tangent.

Agent Task is the job. What it is trying to achieve on every call, and what it should do when it cannot. Be explicit about the failure path: what the agent says when the answer is not in front of it matters far more than what it says when everything goes right.

Pronunciation is a small field with outsized value. Brand names, street names and product codes are read the way they are spelt unless you say otherwise. Write the correction plainly, for example "Foan as Phone". Add every word a caller would notice being mangled.

There is a hard limit worth knowing before you write a word: all customer-authored instruction fields together are capped at 4,000 characters, with a warning at 3,000. The dashboard shows how much of that budget you have used. This is not a soft suggestion. An edit that pushes an agent past the ceiling is refused.

That cap is a design constraint, not an obstacle. Instructions carry behaviour, not data. Prices, hours, policies and inventory belong in a knowledge base, which does not touch the instruction budget. If you are pasting a menu into the Agent Task field, you are using the wrong box.

Step 3: Choose a voice, an accent, and the first thing it says

Open the Voice Selection section. There is a searchable list of voices with a short character label on each, and a speaking speed control alongside it. Speed matters more than people assume: a voice that reads beautifully in a browser preview can be half a step too quick over a patchy mobile call.

Directly under the identity fields is Language and accent, and it deserves a paragraph of its own. It is a single free-text box, not a dropdown. You describe what you want in words: "Singaporean English", or "speaks only Mandarin", or "Indian English, follows the caller into Hindi". The field takes up to 200 characters.

Written that way, the agent follows a caller who switches language mid-sentence rather than dragging them back to English. English, 22 Indian languages and dozens more international languages are available depending on how the call is routed.

Then open Call Messages. Four fields, each one a moment in the call the agent would otherwise improvise:

Write the greeting yourself. The first four seconds decide whether a caller engages or hangs up, so that sentence is worth more editing attention than anything else on the page.

Step 4: Give it the facts it will be asked for

Under Knowledge, create a knowledge base, then attach it to the agent from the Knowledge Bases section on the agent page.

You can upload up to five files per source, 4 MB each, in PDF, DOCX, TXT or MD, or paste text straight into a box. One caveat that changes how you should work: a knowledge source cannot be edited after upload. Get the document right before you upload it, and expect to delete and re-add rather than tweak.

Small knowledge bases behave differently from large ones. A source under the inline threshold is placed into the agent's context directly, so the facts are simply there, with no lookup step during the call. A larger one becomes something the agent searches mid-conversation, which is equally accurate but adds a beat to the response. Either way the retrieval is semantic, so a caller asking about "parking" finds the paragraph headed "how to reach us".

Splitting knowledge by topic rather than dumping everything into one source is worth the extra few minutes. Building a knowledge base your voice agent will not hallucinate from goes into how to structure the documents and how the agent behaves when the answer genuinely is not there.

Step 5: Give it hands with tools

Knowledge lets the agent answer. Tools let it act: look up an order, book a slot, write a lead into your CRM.

Open the Integrations section and add a tool. You give it an action name, an instruction telling the model when to reach for it, a set of questions to collect from the caller, and a webhook URL. Foan POSTs a JSON body to that URL during the call, waits for a reply, and speaks the result.

Four things to know before you build one:

• A maximum of five tools per agent. This is enforced.
• The method is POST and only POST. You can set a bearer token. There is no custom headers field and no verb picker.
• The caller's number arrives on every tool call already. It is in the payload as part of the call context. Never declare a required phone question on a tool that runs during a live call, because that is the only reason an agent ever asks a caller to read their own number out.
• Decide what the agent says while it waits, and what it says when the call fails. Both are configurable, and an agent that goes silent for four seconds during an API call sounds broken even when it is working.

Connecting your agent to your own APIs shows the exact payload, the response shape the agent expects back, and how to handle a slow endpoint mid-conversation.

Step 6: Give it a number to answer on

Open the Phone Number section and assign one. A number carries one agent and an agent carries one inbound number, so assigning a new number releases the previous one.

Three routes to a number:

1. Connect your own Plivo account and buy in any country Plivo sells. This is done in the dashboard only, deliberately, so the auth token never passes through anything else.
2. Buy an Indian number through Foan's numbering partner, which needs no telephony account of your own. India requires a short KYC wizard: registration, PAN, Aadhaar through DigiLocker, GST if you are a business, then a final step.
3. Forward your existing number, and change nothing else. This is the fastest route to a live agent and the one most people skip. Give your AI agent a phone number without porting anything has the dial codes.

Step 7: Call it yourself and read the transcript

Save the agent. A Call section now appears on the page, which it did not while the agent was unsaved, with two buttons.

Web Call runs the conversation in your browser. Use it while you are still editing wording, because the loop is quick and you can interrupt yourself without burning a call.

Phone Call places a real call. This is the one that counts. A browser call over good Wi-Fi hides everything a phone line will expose: the speaking speed that is slightly too fast, the pronunciation nobody corrected, the pause while a tool runs. The button stays disabled, with a tooltip saying so, until a number is assigned.

Then read the transcript rather than trusting your memory of the call. Three things are usually wrong on a first pass, and they are almost always the same three:

• The agent answered a question it should have refused, because the knowledge base did not cover it and the instructions did not say what to do about that.
• It asked for something it already had, which is nearly always the caller's phone number.
• It talked too long. Phone callers interrupt. An agent that delivers a four sentence answer gets cut off at sentence two.

Fix those, then call again from a different phone, ideally one whose number the agent has not seen. Repeat until a call you did not script goes the way you expected.

What to do when the agent goes off script

The instinct is to add a rule to the prompt. Resist it: the instruction budget is finite and rules compete with each other.

Ask which layer should own the fix instead. A factual mistake belongs in the knowledge base. A behavioural mistake, such as being too chatty or refusing too readily, belongs in Agent Personality or Agent Task. An action it could not complete belongs in a tool. Prompt rules are the last resort.

And when a call genuinely needs a person, the agent should hand it over rather than improvise. Handover is configured over the API rather than from a dashboard screen today. The behaviour is worth knowing: the caller hears one connecting line, waits in a short hold, and your colleague is briefed on the conversation so far before joining. Foan bills the AI time up to the moment the AI leaves.

Where to go next

Once one agent answers calls properly, the natural next step is outbound. Running an outbound calling campaign covers list handling, calling windows and the follow-up rules that keep you from calling the same person six times.

For what a phone agent handles once it picks up, see phone agents.