Build a reliable phone agent

This is the order that makes an agent dependable on real calls, from the first brief to the weekly review after launch. Each step says what to do and which Voice Logica tool does it from Claude or ChatGPT (connect your assistant). The detailed pages are linked; this page is the checklist.

For AI assistants following this page

Before the first change to a settings section, call get_agent_settings with that section and format: true to get its fields. Settings writes are patches: pass only what changes. Confirm with the user before anything that changes what live callers hear.

At a glance

Step	From a chat
1. Define the job	get_my_agent, get_agent, get_company_operating_hours
2. Write the prompt	get_agent_prompt, edit_agent_prompt
3. Greeting	update_agent_settings (section "welcome", "ai_disclosure")
4. Knowledge	create_knowledge_file, add_knowledge_entries, add_knowledge_link, knowledge_execute (action "assign_knowledge_file_to_agent"), search_knowledge
5. Tools and workflows	list_integrations, describe_integration, update_agent_settings (section "tools", "workflows"), create_workflow_from_template
6. Transfers	update_agent_settings (section "transfer"), update_company_operating_hours
7. Ending the call	update_agent_settings (section "end_call")
8. Language and voice	list_voices, update_agent_settings (section "voice", "languages", "pronunciation")
9. Call results	update_agent_settings (section "analysis")
10. Memory	update_agent_settings (section "memory")
11. Test	scenarios_query, scenarios_execute, run_agent_scenario, test_in_browser, call_me, get_call_result
12. Go live	get_guide (guide "go_live"), telephony_execute (action "update_number")
13. Improve	get_calls, knowledge_query / knowledge_execute (unanswered questions)

1. Define the job and the calls it will get

• Write one sentence: who calls, and what the agent must achieve on the call.
• List the 5-10 most common reasons people call, each with the approved answer or action. These become the prompt sections, the knowledge entries and the test scenarios.
• For each reason decide one outcome: the agent answers, the agent does it (booking, lookup, SMS), the agent takes a message, or a person takes over.
• Collect business hours, languages, tone (ask the business; formal is the safe default), who can take transfers and when, and what happens out of hours.
• Decide what is out of scope (wrong number, sales pitches, unrelated requests): the agent declines politely and ends the call without collecting details.
• One agent, one job. If the prompt still grows past about 20,000 characters after facts move to knowledge, split it: a front-desk agent that transfers to a specialist agent.

From a chat: get_my_agent or get_agent to read what exists, get_company_operating_hours / update_company_operating_hours for the hours. Sign-up already built a first agent - edit it rather than creating a second one (Your First Agent).

2. Write the prompt

The prompt is how the agent behaves. Facts go to knowledge (step 4). Keep it in this order:

1. Role - who it is, which company, who calls.
2. How it speaks - tone and spoken style (below).
3. Call reasons - one section per reason: what to ask, in which order, what to do, when it is finished.
4. Taking a message - only for reasons that need a follow-up.
5. Transfers - when a transfer is allowed and to whom (step 6).
6. Ending - what to say before hanging up.
7. General rules - last.

Spoken style, Greek and English

• Short sentences, one idea each. One question per turn, then wait for the answer.
• It is speech: no lists, markdown, emojis or links read aloud.
• Answer in the caller’s language. In Greek, use the polite plural unless the business wants otherwise, and write natural spoken Greek, not a translation.
• Never re-ask something the caller already said in this call.

Rules that keep it honest

• Never invent prices, availability, stock, dates or policies. If it is not in knowledge or in a tool result, the agent says it will check, takes a message, or transfers.
• Never say something is booked, sent or transferred until the tool confirms it. On a tool failure, apologise and offer a message.
• Read back names, phone numbers, emails, order numbers and dates, digit by digit where it matters, and get a yes before using them.
• An unknown question gets an honest “I don’t have that information” plus a message or a transfer, never a guess.

Writing tips

• Say what to do, not only what to avoid. State each rule once; repeat only a safety-critical rule at the exact step where it applies.
• Name each tool at the point in the flow where it should fire, with its exact name.
• Live values use {{variable}} with flat names such as {{phone_number}} and {{date}} (workflows use call.-prefixed names). Do not use square brackets in the prompt.
• Write phone numbers, emails and web addresses exactly as they are. No added spaces, pauses or spelled-out symbols.
• Aim for 15,000-20,000 characters at most. Your plan also caps the prompt length.

Short example:

ROLE:
You are the receptionist of Smile Dental Clinic. People call to book, move or cancel
appointments and to ask about treatments.

HOW YOU SPEAK:
Short, friendly-formal sentences. One question at a time, then wait for the answer.
Answer in the caller's language.

BOOKING:
1. Ask which treatment they need.
2. Ask for a preferred day, then call <your availability tool>.
3. Offer at most two free times from the result. Never suggest a time it did not return.
4. Read back day, time and name, and ask them to confirm. Only then call <your booking tool>.
5. Say it is booked only after the booking tool succeeds. If it fails, offer to take a message.

From a chat: get_agent_prompt first, then edit_agent_prompt to change passages and keep the rest. Pass prompt to it only for a full rewrite. On an agent that is already live, pass destination: "staging", test (step 11), then publish with versions_execute (action "publish_agent_version").

3. Greeting

• One short line: the company name, that the caller is speaking with an AI (or turn AI disclosure on), and one opening question.
• If recording is on, put the consent line in the greeting (Recording & Privacy).
• Set a separate out-of-hours greeting when the business closes; it can also end the call right after.
• Do not repeat the greeting inside the prompt, or the agent may greet twice.

From a chat: update_agent_settings (section "welcome") and (section "ai_disclosure").

4. Knowledge

• Prompt = behaviour, flow, rules. Knowledge = prices, services, addresses, detailed hours, policies, long FAQ answers.
• Write entries as question and answer, phrased the way callers ask, with alternative phrasings. One fact per entry. Greek questions for Greek callers.
• Keep it factual, approved and current. Remove what is outdated.
• Attach the knowledge base to the agent. Creating it is not enough.
• Check retrieval: ask search_knowledge the caller’s question and see which entry comes back first. No right entry means the knowledge is missing; the right entry ranked lower means rephrase it.
• Turn on Questions your agents could not answer in Learning Center - Settings, so every gap comes back to you (step 13).

From a chat: create_knowledge_file, add_knowledge_entries (or add_knowledge_text, add_knowledge_link, crawl_website_pages for a website), knowledge_execute (action "assign_knowledge_file_to_agent"), search_knowledge, knowledge_query (action "audit_knowledge_health"). Details: Knowledge, Knowledge bases.

5. Tools and workflows the agent uses mid-call

• Enable only what the job needs. A tool that is off cannot fire; a tool that is on but never mentioned in the prompt rarely fires.
• For each tool, the prompt says when to use it, what to collect and confirm first, and what to say on success and on failure.
• Connect the integration first, then enable its tool on the agent.
• Keep Skip Turn on so the agent does not talk over a caller reading out a number or a code.
• SMS needs the Send SMS tool enabled and one line in the prompt saying when to text.
• Let a workflow do exact lookups and date calculations instead of asking the prompt to work them out. A workflow runs only on the agents it is attached to.

From a chat: list_integrations and describe_integration; update_agent_settings (section "tools", with the tool name); create_workflow_from_template, edit_workflow, test_workflow, then update_agent_settings (section "workflows") to attach. Details: Tools & Workflows, Workflows.

6. Transfers to a person, and when not to transfer

• Turn on Enable call transfer under Call handling - Transfer. Warm is the safe default: the agent waits for a person to pick up before connecting.
• In Routing Instructions, say when a transfer is allowed, not only where. A bare list of names and numbers makes the agent dial as soon as it recognises a name.
• Set business hours and turn on Block Transfer When Company Is Closed. Out of hours the agent takes a message instead.
• When a transfer is not allowed (closed, person not on the list, request out of scope), the agent says so and offers to take a message. It does not try the transfer.
• If nobody answers a Warm transfer, the agent is back with the caller: tell it to take a message then.
• A transfer to an external number is an outbound call and needs telephony credit. A transfer to another agent does not.
• Transfers are configured here, never as a hang-up reason.

From a chat: get_agent_settings (section "transfer", format: true), then update_agent_settings (section "transfer"); update_company_operating_hours. Details: Transfer.

7. Ending the call

• Turn on Enable Automatic Call Ending with specific reasons tied to what the caller says or confirms, for example “the caller confirms they need nothing else”. Vague reasons hang up on a pause.
• A message-taking branch finishes (details confirmed) before the call can end.
• Add a reason for out-of-scope or abusive calls: a polite line, then end.
• Set Call Duration Limit as a ceiling, not a target.

From a chat: update_agent_settings (section "end_call"). Details: Hang up.

8. Languages and voice

• Set the primary language, then add the other languages callers use. The agent can switch during a call.
• Listen to voices before choosing one.
• A word the agent says wrong: add a pronunciation entry, written the way it should sound (a Latin-script brand name in a Greek agent is written in Greek letters). A word the agent mishears: add it to Custom vocabulary under Voice & Language.

From a chat: list_voices, update_agent_settings (section "voice"), (section "languages", {add: ...}), (section "pronunciation"). Details: How the agent hears.

9. Call results

• Turn Call Summary on in After the call - Call results. Memory needs it.
• Add only the analysis properties someone will filter or act on, for example the request, whether it is urgent, the caller’s name and a callback number. Each property captures one clear fact, described the way a grader would judge it.
• Turn on auto-created tasks only if someone works the Tasks board.

From a chat: update_agent_settings (section "analysis"). Details: Call results.

10. Memory

• Call Memory lets the agent use summaries of the same caller’s earlier calls. It needs Call Summary on.
• Start small: 7 days, last 3 calls. Prove it with two test calls from the same number.
• Turn it on in the app under Skills - Knowledge, or from a chat with update_agent_settings (section "memory"): maxTimeMemory in seconds (7 days = 604800), maxInteractionsMemory as the number of past calls, and summaryEnabled: true, since memory is built from call summaries.

Details: Knowledge - Call Memory.

11. Test before going live

1. Generate scenarios - scenarios_query (action "generate_agent_scenarios") with a focus: prompt, transfer, tools or knowledge. Drafts are not saved.

2. Keep the good ones and add your own - scenarios_execute (action "create_agent_scenario"). Cover each top call reason, an out-of-hours call, a question the agent cannot answer, a caller who spells a name or number, a caller who asks for a person, and an off-topic caller.

3. Run them - run_agent_scenario with mode: "text". A text run simulates the conversation and checks what the agent says and decides. Tools, transfers and workflows do not run in text mode, so a “missed tool call” there is not a finding. To test a staged change, pass its agentVersionId.

4. Read the results - scenarios_query (action "get_agent_scenario_results"): verdict, score and suggested improvements.

5. Fix and re-run - change the prompt with edit_agent_prompt, or apply the suggestions with scenarios_execute (action "apply_scenario_improvements"; prompt changes go to staging by default). Re-run the same scenarios.

6. Make a real test call - test_in_browser returns a link to talk to the agent by voice or chat (it turns on the website widget, limited to the business’s own website). call_me has the agent ring the user’s own verified mobile; pass what they want to try as scenario. Read the call with get_call_result.

A test call passes when the agent greets with the right company name, sounds right, answers the common questions correctly, admits what it does not know, fires its tools (booking made, SMS sent, transfer connected), and ends the call cleanly.

12. Go live

• Clear every required item in the editor’s Required panel.
• Get a plan and a line, and route the number to the agent: get_guide (guide "go_live"), then telephony_execute (action "update_number"). See Activate your subscription and Telephony.
• Call the real number once and check the call appears in Calls.
• Read the first real calls the same day.

13. Improve after launch

Once a week, or after any complaint:

• Read the calls - get_calls filtered by agent and date; include: ["summary"] or ["analysis"] keeps it short. Look at transfers, very short calls and complaints.
• Understand a bad call - get_calls with include "aiDialogue" shows the prompt, tool calls and tool responses as they were during that call. Decide which it was: a missing rule, a rule that exists but another instruction won, wrong knowledge, or a tool that failed.
• Wrong fact - search_knowledge with the caller’s words, then fix the entry.
• Unanswered questions - knowledge_query (action "list_unanswered_questions", most asked first), then knowledge_execute (action "answer_unanswered_question"). The answer is used on the next call.
• One change at a time - edit, re-run the scenarios, and add a scenario for every failure you found on a real call.

For why a call ended or failed, see Call status and end reasons.

Quick fixes

Symptom	Usual cause	Fix
Makes up a price or a time	Fact missing from knowledge, or no “never invent” rule	Add the knowledge entry; add the rule at that step
Talks over a phone number	Skip Turn off, or a prompt line says “act immediately”	Enable Skip Turn; say “wait until the caller has finished”
Transfers when it should not	Routing Instructions list where, not when	Add the condition before the list
Says “I’ll transfer you” but nothing happens	Transfer off, closed hours, or no destination	Check Transfer and business hours
Hangs up mid-conversation	Vague hang-up reason	Tie the reason to a confirmed “nothing else”
Knows the answer in tests, not on calls	Knowledge not attached to this agent	Attach it; check with search_knowledge

Next Steps

Agent configuration overview - Knowledge - Transfer - What you can ask Claude and ChatGPT