Vapi Workshop Companion · Bilingual Multi-Agent Voice AI

\n\n \n

\n Start here\n

Build a Bilingual Multi-Agent Voice AI System

An instructor-led, hands-on workshop where you'll build a fully working inbound phone line that detects English or Spanish callers and routes them to the right specialist agent.

\n\n

What you will build

An inbound phone line for Greenfield Property Management — a fictional property company — staffed by three Vapi assistants working as a squad:

Language Triage Agent — answers first, detects English or Spanish, routes the caller.
Maintenance Agent — collects repair details and logs a ticket via a tool.
FAQ Agent — answers general property questions via a bilingual FAQ API.

What you will learn

How to think about designing voice agents and how they differ from text based agents
Considerations for selecting the parts of your voice agent stack
System prompt design best practices for voice agents
How to build in the Vapi ecosystem

\n\n\n

How this workshop works

This companion is designed to work alongside live instruction. You will see various breakpoints where we will come back together as a class and go deeper into a concept.

Everything is managed as code using the Vapi GitOps repo. We will also utilize the Vapi dashboard for testing.

Follow along using the sidebar. Each step has copy-paste code blocks, the links you'll need, and occasional short quizzes to test your knowledge.

\n\n

\n \n

Pause — check in with Amanda

Designing voice agents

let's get under the hood

\n \n\n \n

\n Part 0\n

Setup

We manage everything as code: assistants, tools, and squads live as files in a repo and get pushed to Vapi with one command.

\n\n

Before you start

Vapi account: dashboard.vapi.ai
GitHub access: github.com/VapiAI/gitops
Local tools: Node.js 18+, npm, Git, and a code editor

\n\n

Verify your local tools

node --version\nnpm --version\ngit --version

If all three print versions, you're good to go.

\n\n

Step 1 — Clone the GitOps repo

git clone https://github.com/VapiAI/gitops greenfield-demo\ncd greenfield-demo

\n\n

Step 2 — Install dependencies

npm install

\n\n

Step 3 — Configure your environment

Open dashboard.vapi.ai/org/api-keys, copy your Private API Key, and create a .env.dev file in the project root:

echo 'VAPI_TOKEN=your-vapi-private-key-here' > .env.dev

Replace your-vapi-private-key-here with the private key you copied.

\n Why the private key, not the public one? The public key is scoped to web-call creation only and will fail with 401 Invalid Key against GitOps pull/push endpoints.\n

\n\n

Step 4 — Bootstrap the state file

Bootstrap creates .vapi-state.dev.json, which maps your local files to the resource IDs in your Vapi account:

npm run pull -- dev --bootstrap

\n\n

Step 5 — Create the resource directories

mkdir -p resources/dev/assistants\nmkdir -p resources/dev/tools\nmkdir -p resources/dev/squads

\n\n

Your project should look like this:

greenfield-demo/\n├── .env.dev\n├── .vapi-state.dev.json\n├── resources/\n│   └── dev/\n│       ├── assistants/\n│       ├── tools/\n│       └── squads/\n└── package.json

\n\n

\n\n \n

\n Part 1\n

Create the Language Triage Agent

\n\n

The three assistants share a stack

All three use the same voice, transcriber, and LLM, so call quality stays consistent across handoffs:

Voice: Cartesia sonic-3 · voiceId 2821fd0c-35c7-4adf-9c42-32e394bf85cb
Transcriber: Deepgram nova-3 with language: multi
LLM: Groq openai/gpt-oss-120b

\n\n

\n \n

Pause — check in with Amanda

How to choose your voice agent stack

the soul of your agent

\n\n

This assistant always answers the call first. Its only job: figure out the caller's language and route them to the right specialist.

\n\n

Create the assistant file

Create resources/dev/assistants/language-triage-agent.md:

---\nname: Language Triage Agent\nfirstMessage: \"Hello! Hola! I can help in English or Spanish. Tell me what you need, and I'll route you to the right specialist.\"\nvoice:\n  provider: cartesia\n  model: sonic-3\n  voiceId: 2821fd0c-35c7-4adf-9c42-32e394bf85cb\nmodel:\n  provider: groq\n  model: openai/gpt-oss-120b\n  temperature: 0\ntranscriber:\n  provider: deepgram\n  model: nova-3\n  language: multi\n  smartFormat: true\nendCallFunctionEnabled: true\nendCallMessage: \"Thank you for calling Greenfield Property Management. Gracias por llamar a Greenfield Property Management.\"\nsilenceTimeoutSeconds: 30\nmaxDurationSeconds: 600\nbackgroundDenoisingEnabled: true\nbackgroundSound: off\n---\n\n# Identity & Purpose\n\nYou are the language and intent router for Greenfield Property Management.\n\nYou support exactly two languages:\n- English\n- Spanish\n\nYour job is to do two things quickly:\n1. Detect whether the caller should be handled in English or Spanish\n2. Route them to the correct specialist:\n   - Maintenance Agent for repair issues\n   - FAQ Agent for general property questions\n\nYou do not solve the caller's issue yourself beyond a short routing acknowledgement.\n\n# Guardrails\n\n- If the caller speaks a language other than English or Spanish, politely ask them to continue in English or Spanish.\n- If the caller starts in English, route with `selected_language: en`.\n- If the caller starts in Spanish, route with `selected_language: es`.\n- If the intent is unclear, ask one short clarifying question before routing.\n- Do not collect full maintenance details.\n- Do not answer policy questions yourself.\n- Route as soon as you are confident.\n\n# Response Style\n\n- Be brief and confident.\n- Use the caller's language once you know it.\n- Keep routing language natural, for example:\n  - English: \"Got it - I am connecting you to our maintenance specialist.\"\n  - Spanish: \"Entendido - le conecto con nuestro especialista de mantenimiento.\"\n\n# Workflow\n\n## STEP 1: Listen for the first real request\n\nIdentify both:\n- language: English or Spanish\n- intent: maintenance or general question\n\n## STEP 2: If needed, clarify once\n\nIf you cannot tell whether the caller needs maintenance help or a general answer, ask one short question.\n\n## STEP 3: Route\n\nUse the correct handoff tool and include:\n- `selected_language`: `en` or `es`\n- `reason`: short summary of why you are routing\n\nExamples:\n- \"English caller reporting a leaking sink\"\n- \"Spanish caller asking about pet policy\"\n\n# Error Handling\n\n- If the caller is hard to understand, ask them to repeat once.\n- If they stay unclear after that, offer English or Spanish explicitly and ask them to choose.

\n\n

Push it to Vapi

npm run apply -- dev --allow-new-files

\n\n

You should see:

[assistants] Creating: Language Triage Agent\n[assistants] Created: Language Triage Agent -> <uuid>

\n\n

At this point the triage agent exists in Vapi — but it won't route anywhere yet, because we haven't created the squad handoff rules. That comes in Part 6.

\n\n

\n\n \n

\n Part 2\n

Create the Maintenance Agent

The specialist that takes over after the triage agent routes a maintenance call. It collects details and logs a ticket using the log_maintenance_request tool (which we'll wire up in Part 3).

\n\n

Create the assistant file

Create resources/dev/assistants/maintenance-agent.md:

---\nname: Maintenance Agent\nfirstMessage: \"\"\nfirstMessageMode: assistant-speaks-first-with-model-generated-message\nvoice:\n  provider: cartesia\n  model: sonic-3\n  voiceId: 2821fd0c-35c7-4adf-9c42-32e394bf85cb\nmodel:\n  provider: groq\n  model: openai/gpt-oss-120b\n  temperature: 0\n  toolIds:\n    - log-maintenance-request\ntranscriber:\n  provider: deepgram\n  model: nova-3\n  language: multi\n  smartFormat: true\nendCallFunctionEnabled: true\nendCallMessage: \"Thank you for calling. Gracias por llamar.\"\nsilenceTimeoutSeconds: 30\nmaxDurationSeconds: 600\nbackgroundDenoisingEnabled: true\nbackgroundSound: off\n---\n\n# RE-ENTRY PROTOCOL\n\nIf this is the first turn of the call (no prior conversation in your context), greet the caller and begin the workflow.\n\nIf you are receiving control via a handoff (prior conversation present), do NOT re-greet. Pick up from where the previous specialist left off.\n\n# Identity & Purpose\n\nYou are a virtual maintenance coordinator named Alex for Greenfield Property Management.\n\nYou support callers in English and Spanish.\n\nIf the prior handoff includes a `selected_language` argument, continue in that language unless the caller clearly switches. Otherwise, mirror the language the caller is currently using.\n\nYour primary goal is to collect the details of a maintenance request and log it with the `log_maintenance_request` tool.\n\n# Guardrails\n\n- Only handle maintenance issues.\n- If the caller asks a general property question, hand off to the FAQ Agent and preserve the same `selected_language`.\n- Do not promise exact repair times.\n- Do not collect sensitive information such as Social Security numbers, bank details, or passwords.\n\n# Response Guidelines\n\n- Ask one question at a time.\n- Keep responses short and natural.\n- Confirm key details before submitting the tool.\n- Tell the caller before calling the tool.\n\n# Workflow\n\n## STEP 1: Collect the details\n\nGather:\n1. Tenant name\n2. Unit number\n3. Issue description\n4. Urgency\n\n## STEP 2: Confirm\n\nRepeat the details back in the caller's language and ask for confirmation.\n\n## STEP 3: Log the request\n\nSay you are logging it, then call `log_maintenance_request`.\n\n## STEP 4: Wrap up\n\nIf the tool succeeds, confirm that the request was logged.\n\nIf the caller asks a general property question at any point, transfer them to the FAQ Agent with the same working language.

\n\n

Save it, but do not apply yet

\n Important: do not run npm run apply yet. This assistant references the log-maintenance-request tool, and that tool does not exist until the next section. Save the file, continue to Part 3, then apply once after the tool file exists too.\n

\n \n

Pause — check in with Amanda

How to design a good system prompt for voice agents

the soul of your agent

\n\n \n

\n Part 3\n

Connect the maintenance tool

The Maintenance Agent calls log_maintenance_request, which Vapi delivers to an HTTP endpoint that logs the ticket. We've already deployed that endpoint for you — you'll just point your tool config at it.

\n\n \n

Create the tool file

Create resources/dev/tools/log-maintenance-request.yml:

type: function\nasync: false\nfunction:\n  name: log_maintenance_request\n  description: Log a tenant maintenance request with the tenant name, unit number, issue description, and urgency level.\n  strict: true\n  parameters:\n    type: object\n    properties:\n      tenant_name:\n        type: string\n        description: Full name of the tenant\n      unit_number:\n        type: string\n        description: Unit number, for example 4B or 12A\n      issue_description:\n        type: string\n        description: Description of the maintenance issue\n      urgency:\n        type: string\n        enum: [low, medium, high, emergency]\n        description: Issue urgency level\n    required:\n      - tenant_name\n      - unit_number\n      - issue_description\n      - urgency\nmessages:\n  - type: request-start\n    blocking: true\n    contents:\n      - type: text\n        text: \"One moment while I log that for you.\"\n        language: en\n      - type: text\n        text: \"Un momento mientras registro eso.\"\n        language: es\n  - type: request-response-delayed\n    timingMilliseconds: 5000\n    contents:\n      - type: text\n        text: \"Still logging that - just a moment.\"\n        language: en\n      - type: text\n        text: \"Sigo registrando eso - un momento.\"\n        language: es\n  - type: request-failed\n    contents:\n      - type: text\n        text: \"I could not log that right now, but our team will follow up.\"\n        language: en\n      - type: text\n        text: \"No pude registrarlo ahora mismo, pero nuestro equipo dará seguimiento.\"\n        language: es\nserver:\n  url: https://amandamartin--248cf452507911f1b0bfee650bb23af1.web.val.run/log\n  timeoutSeconds: 20

\n\n

Replace the server.url with the hosted endpoint shown above, then push:

npm run apply -- dev --allow-new-files

\n\n

You should see the tool created and the Maintenance Agent created or updated with the resolved tool reference:

[tools] Creating: log_maintenance_request\n[tools] Created: log_maintenance_request -> <uuid>\n[assistants] Creating/Updating: Maintenance Agent (resolved toolIds)

\n\n

\n\n \n

\n Part 4\n

Create the FAQ Agent

The second specialist. Handles general property questions like \"when is rent due?\" or \"aceptan mascotas?\" by searching a bilingual FAQ via the search_faqs tool (wired up in Part 5).

\n\n

Create the assistant file

Create resources/dev/assistants/faq-agent.md:

---\nname: FAQ Agent\nfirstMessage: \"\"\nfirstMessageMode: assistant-speaks-first-with-model-generated-message\nvoice:\n  provider: cartesia\n  model: sonic-3\n  voiceId: 2821fd0c-35c7-4adf-9c42-32e394bf85cb\nmodel:\n  provider: groq\n  model: openai/gpt-oss-120b\n  temperature: 0\n  toolIds:\n    - search-faqs\ntranscriber:\n  provider: deepgram\n  model: nova-3\n  language: multi\n  smartFormat: true\nendCallFunctionEnabled: true\nendCallMessage: \"Glad I could help. Me alegra haber ayudado.\"\nsilenceTimeoutSeconds: 30\nmaxDurationSeconds: 600\nbackgroundDenoisingEnabled: true\nbackgroundSound: off\n---\n\n# RE-ENTRY PROTOCOL\n\nIf this is the first turn of the call (no prior conversation in your context), greet the caller and begin the workflow.\n\nIf you are receiving control via a handoff (prior conversation present), do NOT re-greet. Pick up from where the previous specialist left off.\n\n# Identity & Purpose\n\nYou are a virtual assistant named Jordan for Greenfield Property Management.\n\nYou support callers in English and Spanish.\n\nIf the prior handoff includes a `selected_language` argument, continue in that language unless the caller clearly switches. Otherwise, mirror the caller's current language.\n\nYour job is to answer general property questions accurately by using the `search_faqs` tool.\n\n# Guardrails\n\n- Only handle general property questions.\n- If the caller needs maintenance help, transfer them to the Maintenance Agent and preserve the same `selected_language`.\n- Do not guess if you do not know the answer.\n- Always use the tool before answering factual policy questions.\n\n# Response Guidelines\n\n- Keep answers short and conversational.\n- Summarize the tool result in 1-3 sentences.\n- Call the tool with both:\n  - `query`\n  - `language` set to `en` or `es`\n\n# Workflow\n\n## STEP 1: Understand the question\n\nIf it is really a maintenance issue, transfer immediately.\n\n## STEP 2: Search\n\nTell the caller you are looking it up, then call `search_faqs`.\n\n## STEP 3: Answer\n\nAnswer in the caller's current language.\n\n## STEP 4: Follow up\n\nAsk whether they need anything else.

\n\n

Save it, but do not apply yet

\n Important: do not run npm run apply yet. This assistant references the search-faqs tool, and that tool does not exist until the next section. Save the file, continue to Part 5, then apply once after the tool file exists too.\n

\n\n

\n\n \n

\n Part 5\n

Wire up the bilingual FAQ tool

The FAQ Agent calls search_faqs, which Vapi delivers to a bilingual FAQ search endpoint. As with the maintenance tool, we've already deployed the endpoint — you'll just point your tool config at it.

\n\n

Create the tool file

Create resources/dev/tools/search-faqs.yml:

type: function\nasync: false\nfunction:\n  name: search_faqs\n  description: Search the Greenfield Property Management bilingual FAQs and return an answer in English or Spanish.\n  strict: true\n  parameters:\n    type: object\n    properties:\n      query:\n        type: string\n        description: Search query based on the caller's question\n      language:\n        type: string\n        enum: [en, es]\n        description: Language to use for the returned answer\n    required:\n      - query\n      - language\nmessages:\n  - type: request-start\n    blocking: true\n    contents:\n      - type: text\n        text: \"Let me look that up for you.\"\n        language: en\n      - type: text\n        text: \"Permítame buscar eso.\"\n        language: es\n  - type: request-response-delayed\n    timingMilliseconds: 5000\n    contents:\n      - type: text\n        text: \"Still searching - one moment.\"\n        language: en\n      - type: text\n        text: \"Sigo buscando - un momento.\"\n        language: es\n  - type: request-failed\n    contents:\n      - type: text\n        text: \"I am having trouble looking that up right now.\"\n        language: en\n      - type: text\n        text: \"Estoy teniendo problemas para buscar eso ahora mismo.\"\n        language: es\nserver:\n  url: https://amandamartin--0e6748704fe911f1ab05ee650bb23af1.web.val.run/search\n  timeoutSeconds: 20

\n\n

Replace the placeholder URL with the real hosted endpoint, then push:

npm run apply -- dev --allow-new-files

\n\n

Expected output includes the tool being created and the FAQ Agent being created or updated with the resolved tool reference:

[tools] Creating: search_faqs\n[tools] Created: search_faqs -> <uuid>\n[assistants] Creating/Updating: FAQ Agent (resolved toolIds)

\n\n

\n\n \n

\n Part 6\n

Wire everything together as a squad

A squad connects your assistants and defines who can hand off to whom. We'll put the Language Triage Agent first, give it tools to route to either specialist, and give each specialist a tool to hand off to the other.

\n \n

Pause — check in with Amanda

Let's talk about squads

Use squads when specialization makes the call easier to control: each assistant owns a clear workflow, and handoffs pass only the context the next assistant needs.

Create the squad file

Create resources/dev/squads/greenfield-property-management-bilingual.yml:

name: Greenfield Property Management - Bilingual\nmembers:\n  - assistantId: language-triage-agent\n    assistantOverrides:\n      tools:append:\n        - type: handoff\n          async: false\n          messages: []\n          function:\n            name: route_to_Maintenance_Agent\n            description: Route the caller to the Maintenance Agent after identifying English or Spanish and confirming the issue is maintenance-related.\n            parameters:\n              type: object\n              properties:\n                destination:\n                  type: string\n                  enum: [\"Maintenance Agent\"]\n                  description: The squad member to hand off to\n                selected_language:\n                  type: string\n                  enum: [en, es]\n                  description: Working language for the rest of the conversation\n                reason:\n                  type: string\n                  description: Short reason for the handoff\n              required:\n                - destination\n                - selected_language\n                - reason\n          destinations:\n            - type: assistant\n              assistantName: Maintenance Agent\n              description: Handles maintenance requests in English or Spanish\n        - type: handoff\n          async: false\n          messages: []\n          function:\n            name: route_to_FAQ_Agent\n            description: Route the caller to the FAQ Agent after identifying English or Spanish and confirming the request is a general property question.\n            parameters:\n              type: object\n              properties:\n                destination:\n                  type: string\n                  enum: [\"FAQ Agent\"]\n                  description: The squad member to hand off to\n                selected_language:\n                  type: string\n                  enum: [en, es]\n                  description: Working language for the rest of the conversation\n                reason:\n                  type: string\n                  description: Short reason for the handoff\n              required:\n                - destination\n                - selected_language\n                - reason\n          destinations:\n            - type: assistant\n              assistantName: FAQ Agent\n              description: Handles general property questions in English or Spanish\n  - assistantId: maintenance-agent\n    assistantOverrides:\n      tools:append:\n        - type: handoff\n          async: false\n          messages: []\n          function:\n            name: handoff_to_FAQ_Agent\n            description: Transfer the caller to the FAQ Agent when they ask a non-maintenance property question. Preserve the selected language.\n            parameters:\n              type: object\n              properties:\n                destination:\n                  type: string\n                  enum: [\"FAQ Agent\"]\n                  description: The squad member to hand off to\n                selected_language:\n                  type: string\n                  enum: [en, es]\n                  description: Continue the call in this language\n                reason:\n                  type: string\n                  description: Short reason for the handoff\n              required:\n                - destination\n                - selected_language\n                - reason\n          destinations:\n            - type: assistant\n              assistantName: FAQ Agent\n              description: Handles general property questions in English or Spanish\n  - assistantId: faq-agent\n    assistantOverrides:\n      tools:append:\n        - type: handoff\n          async: false\n          messages: []\n          function:\n            name: handoff_to_Maintenance_Agent\n            description: Transfer the caller to the Maintenance Agent when they describe a repair issue. Preserve the selected language.\n            parameters:\n              type: object\n              properties:\n                destination:\n                  type: string\n                  enum: [\"Maintenance Agent\"]\n                  description: The squad member to hand off to\n                selected_language:\n                  type: string\n                  enum: [en, es]\n                  description: Continue the call in this language\n                reason:\n                  type: string\n                  description: Short reason for the handoff\n              required:\n                - destination\n                - selected_language\n                - reason\n          destinations:\n            - type: assistant\n              assistantName: Maintenance Agent\n              description: Handles maintenance requests in English or Spanish

\n\n

Push the squad

npm run apply -- dev --allow-new-files

You should see:

[squads] Creating: Greenfield Property Management - Bilingual\n[squads] Created: Greenfield Property Management - Bilingual -> <uuid>

\n\n

\n You're live! The squad is now running in your Vapi account. Head to the test scenarios next to try it out.\n

\n\n

\n\n \n

\n Test\n

Connect to a phone number and test!

\n \n

Pause — check in with Amanda

The Vapi Dashboard

We've been living in code; now we let the dashboard prove whether our beautiful YAML has manners.

For this workshop, test from the Vapi Dashboard instead of npm run call -- dev. The local WebSocket path in the GitOps repo still has rough edges; the dashboard \"Talk\" button is the smooth path.

\n \n

Example Test Scenarios

Scenario 1 — English maintenance request

\"Hi, my bathroom faucet is leaking.\"

Expected: Triage selects English → routes to Maintenance Agent → Maintenance Agent collects the details and logs the request.

\n\n

Scenario 2 — Spanish FAQ

\"Hola, quería preguntar si aceptan mascotas.\"

Expected: Triage selects Spanish → routes to FAQ Agent → FAQ Agent calls search_faqs with language: es → caller gets the answer in Spanish.

\n\n

Scenario 3 — English FAQ → maintenance handoff

\"When is rent due?\"
\"Actually, I also need to report that my heater stopped working.\"

Expected: Triage routes to FAQ Agent → FAQ Agent answers → FAQ Agent hands off to Maintenance Agent when the topic shifts.

\n\n

Scenario 4 — Spanish maintenance → FAQ handoff

\"Tengo un problema con el aire acondicionado.\"
\"Y otra cosa, cuál es el horario de oficina?\"

Expected: Triage routes to Maintenance Agent in Spanish → Maintenance Agent starts intake → hands off to FAQ Agent in Spanish.

\n\n

Challenge — Language switch mid-call

Start in English, then switch to Spanish after the handoff: \"Actually, también quiero preguntar sobre mascotas.\"

Watch for: The specialist should usually follow the language switch because every assistant uses the same multilingual stack. If it gets awkward, note where the switch happened and what context the next assistant needed.

\n\n \n

\n Help\n

Troubleshooting

Get stuck? Check here first, then ask your agent of choice to debug.

\n\n

Specific errors and fixes

\n\n

\"Pull halted\" / \"pull diverged\" (most common during Part 3 and Part 5)

This means your local state file and what's actually in Vapi have drifted apart. The fix is a bootstrap re-sync, then apply again:

npm run pull -- dev --bootstrap\nnpm run apply -- dev --allow-new-files

If pull itself errors on the same machine, nuke the local state file and re-bootstrap (safe, Vapi has the source of truth):

rm .vapi-state.dev.json\nnpm run pull -- dev --bootstrap\nnpm run apply -- dev --allow-new-files

\n\n

\n Still stuck? Build the whole thing in Composer instead\n

Open dashboard.vapi.ai, find Composer, and paste the prompt below. It tells Composer to build the full squad in the browser, no terminal required.

Build me a bilingual (English/Spanish) inbound voice system for Greenfield Property Management as a squad of three Vapi assistants.\n\n1) A \"Language Triage Agent\" that answers first, detects whether the caller is speaking English or Spanish, identifies whether they need maintenance help or have a general property question, then routes them to the right specialist. It does not solve the issue itself.\n\n2) A \"Maintenance Agent\" named Alex that collects a maintenance request (tenant name, unit number, issue description, urgency one of low/medium/high/emergency), confirms the details with the caller, then logs the ticket via a function tool called log_maintenance_request. The tool's server URL is https://amandamartin--248cf452507911f1b0bfee650bb23af1.web.val.run/log\n\n3) An \"FAQ Agent\" named Jordan that answers general property questions (rent, pets, parking, office hours) in English or Spanish by always calling a function tool called search_faqs before answering. The tool takes a query string and a language string (en or es). The tool's server URL is https://amandamartin--0e6748704fe911f1ab05ee650bb23af1.web.val.run/search\n\nWire them into a squad with handoffs so the triage agent can route to either specialist, and the specialists can hand off to each other if the topic changes mid-call. Preserve the caller's selected language across handoffs. Do not re-greet on handoff.\n\nShared stack across all three assistants: Deepgram nova-3 with language \"multi\" for transcription, Groq openai/gpt-oss-120b for the LLM with temperature 0 on the triage agent, Cartesia sonic-3 voiceId 2821fd0c-35c7-4adf-9c42-32e394bf85cb for the voice.

\n\n

\"VAPI_TOKEN not set\"

Make sure .env.dev exists in the project root and contains VAPI_TOKEN=your-key.

\n\n

Apply surfaces update / overwrite errors

Refresh state with npm run pull -- dev --bootstrap, then apply again.

\n\n

Single-file apply seems to do nothing

Retry with a broader scope: npm run apply -- dev --allow-new-files assistants, ... tools, or a full npm run apply -- dev --allow-new-files.

\n\n

npm run call -- dev does not connect

Use the Vapi Dashboard \"Talk\" button for this workshop instead.

\n\n

Spanish FAQ answers come back wrong or empty

Verify the tool is being called with language: es, and that the FAQ data has Spanish fields and keywords.

\n\n

Tool call times out

Confirm the server.url on the tool matches the hosted endpoint, and that calling it directly with curl returns valid JSON.

\n\n

Agent never hands off

Check that assistantName in the squad exactly matches the assistant's name field (case-sensitive).

\n\n

Voice is inconsistent across assistants

All three assistant files must use the same Cartesia config and the exact same voiceId.

\n\n

Advanced multilingual note — tool messages keep playing in English

With Deepgram language: multi, Vapi's active-language signal pins to a single language at call start, so the contents[] selector can default to English for the whole call. To get per-language tool messages, set assistantOverrides.transcriber.language on each squad-member destination — es on the Spanish handoff path and en on the English path. See docs/Vapi Prompt Optimization Guide.md §16 in the gitops repo.

\n\n

Resources for curious attendees

\n\n

Maintenance endpoint internals

The endpoint is a small Hono server. It accepts Vapi's tool-call request body and returns a result in the shape Vapi expects:

import { Hono } from \"npm:hono\";\n\nconst app = new Hono();\n\napp.get(\"/\", (c) => {\n  return c.json({ status: \"ok\", message: \"Maintenance Logger for Vapi\" });\n});\n\napp.post(\"/log\", async (c) => {\n  let toolCallId = \"unknown\";\n  try {\n    const body = await c.req.json();\n\n    // body.message.toolCallList[i].function.arguments is sent as an OBJECT\n    // by Vapi (the SDK types claim string, but the runtime payload is the\n    // already-parsed object). Defensive handling for both shapes.\n    const toolCall = body?.message?.toolCallList?.[0];\n    toolCallId = toolCall?.id ?? \"unknown\";\n    const rawArgs = toolCall?.function?.arguments;\n    const args = typeof rawArgs === \"string\" ? JSON.parse(rawArgs) : (rawArgs ?? {});\n\n    console.log(\"Maintenance request:\", args);\n\n    return c.json({\n      results: [\n        {\n          toolCallId,\n          result: `Logged ${args.urgency ?? \"unspecified\"}-priority maintenance request from ${args.tenant_name ?? \"(unknown tenant)\"} for unit ${args.unit_number ?? \"(unknown)\"}: ${args.issue_description ?? \"(no description)\"}. The team will follow up shortly.`,\n        },\n      ],\n    });\n  } catch (err) {\n    console.error(\"Maintenance logger error:\", err);\n    // Always return HTTP 200 — Vapi ignores non-200 responses entirely\n    return c.json({\n      results: [\n        {\n          toolCallId,\n          error: String(err instanceof Error ? err.message : err),\n        },\n      ],\n    });\n  }\n});\n\nexport default app.fetch;

Two things worth noticing:

Defensive arg parsing. The SDK types claim function.arguments is a string, but at runtime Vapi often sends the parsed object. The handler accepts both.
Always return HTTP 200. Vapi treats non-200 responses as a transport failure, so we always 200 — even on error — and put the error inside the results[] payload.

\n\n

FAQ API internals

Two files on Val Town: a Hono server (main.ts) and a small in-memory FAQ list (faqs.ts). The handler scores each FAQ entry by how many query words it matches, sorts by score, and returns the answer in the requested language.

\n\n

main.ts

import { Hono } from \"npm:hono\";\nimport { faqs } from \"./faqs.ts\";\n\nconst app = new Hono();\n\napp.get(\"/\", (c) => {\n  return c.json({ status: \"ok\", message: \"Bilingual FAQ API for Vapi\" });\n});\n\napp.post(\"/search\", async (c) => {\n  let toolCallId = \"unknown\";\n  try {\n    const body = await c.req.json();\n    const toolCall = body?.message?.toolCallList?.[0];\n    toolCallId = toolCall?.id ?? \"unknown\";\n    const rawArgs = toolCall?.function?.arguments;\n    const args = typeof rawArgs === \"string\" ? JSON.parse(rawArgs) : (rawArgs ?? {});\n\n    const query = String(args.query ?? \"\").trim();\n    const language = args.language === \"es\" ? \"es\" : \"en\";\n\n    // Word-level scoring with a full-list fallback: always return something\n    // useful so the LLM doesn't retry with a different query.\n    const queryWords = query.toLowerCase().split(/\\s+/).filter((w) => w.length > 0);\n\n    const scored = faqs.map((entry) => {\n      const haystack = [\n        entry.topic,\n        ...entry.keywords,\n        entry.question_en, entry.question_es,\n        entry.answer_en,   entry.answer_es,\n      ].join(\" \").toLowerCase();\n      const score = queryWords.filter((w) => haystack.includes(w)).length;\n      return { entry, score };\n    });\n\n    const topMatches = scored\n      .filter((s) => s.score > 0)\n      .sort((a, b) => b.score - a.score)\n      .map((s) => s.entry);\n\n    // No matches? Return ALL FAQs so the LLM picks the right one instead of retrying.\n    const final = topMatches.length > 0 ? topMatches : faqs;\n\n    const result = final\n      .map((entry) => (language === \"es\" ? entry.answer_es : entry.answer_en))\n      .join(\" \");\n\n    return c.json({ results: [{ toolCallId, result }] });\n  } catch (err) {\n    console.error(\"FAQ search error:\", err);\n    return c.json({\n      results: [{ toolCallId, error: String(err instanceof Error ? err.message : err) }],\n    });\n  }\n});\n\nexport default app.fetch;

\n\n

faqs.ts

export const faqs = [\n  { topic: \"rent\",\n    keywords: [\"rent\",\"due date\",\"late fee\",\"renta\",\"fecha de pago\",\"cargo por retraso\"],\n    question_en: \"When is rent due?\",\n    question_es: \"Cuando se vence la renta?\",\n    answer_en: \"Rent is due on the 1st of each month. A $50 late fee is applied after the 5th.\",\n    answer_es: \"La renta se vence el dia 1 de cada mes. Despues del dia 5 se aplica un cargo por retraso de $50.\" },\n  { topic: \"payments\",\n    keywords: [\"pay rent\",\"tenant portal\",\"pagar renta\",\"portal\"],\n    question_en: \"How do I pay rent?\",\n    question_es: \"Como pago la renta?\",\n    answer_en: \"You can pay rent through the tenant portal, by mailing a check, or by setting up direct deposit.\",\n    answer_es: \"Puede pagar la renta por el portal de inquilinos, enviando un cheque por correo o configurando deposito directo.\" },\n  { topic: \"pets\",\n    keywords: [\"pets\",\"cats\",\"dogs\",\"mascotas\",\"gatos\",\"perros\"],\n    question_en: \"What is the pet policy?\",\n    question_es: \"Cual es la politica de mascotas?\",\n    answer_en: \"Pets are allowed with a signed pet addendum. There is a $300 pet deposit and $25 monthly pet rent.\",\n    answer_es: \"Se permiten mascotas con un anexo firmado. Hay un deposito de $300 y una renta mensual de mascotas de $25.\" },\n  { topic: \"parking\",\n    keywords: [\"parking\",\"guest parking\",\"estacionamiento\",\"visitantes\"],\n    question_en: \"What are the parking rules?\",\n    question_es: \"Cuales son las reglas de estacionamiento?\",\n    answer_en: \"Each unit gets one assigned parking spot. Guest parking is available in the visitor lot.\",\n    answer_es: \"Cada unidad tiene un lugar asignado. El estacionamiento para visitantes esta disponible en el lote de visitas.\" },\n  { topic: \"maintenance\",\n    keywords: [\"maintenance\",\"repair\",\"mantenimiento\",\"reparacion\"],\n    question_en: \"How do I submit a maintenance request?\",\n    question_es: \"Como envio una solicitud de mantenimiento?\",\n    answer_en: \"You can report maintenance by calling this line, using the tenant portal, or visiting the office.\",\n    answer_es: \"Puede reportar mantenimiento llamando a esta linea, usando el portal de inquilinos o visitando la oficina.\" },\n  { topic: \"office\",\n    keywords: [\"office hours\",\"hours\",\"horario\",\"oficina\"],\n    question_en: \"What are the office hours?\",\n    question_es: \"Cual es el horario de oficina?\",\n    answer_en: \"The office is open Monday through Friday, 9 AM to 5 PM, and Saturday from 10 AM to 2 PM.\",\n    answer_es: \"La oficina abre de lunes a viernes de 9 AM a 5 PM, y los sabados de 10 AM a 2 PM.\" },\n];

\n\n

Useful links

\n\n \n

\n <3\n

Connect with Vapi

\n\n

Share your Thoughts

Share your thoughts on this workshop to benefit future developers!

\n Workshop feedback form\n\n

Join the Community

\n\n \n \n

\n\n \n

\n Start here\n

Build a Bilingual Multi-Agent Voice AI System

An instructor-led, hands-on workshop where you'll build a fully working inbound phone line that detects English or Spanish callers and routes them to the right specialist agent.

\n\n

What you will build

An inbound phone line for Greenfield Property Management — a fictional property company — staffed by three Vapi assistants working as a squad:

Language Triage Agent — answers first, detects English or Spanish, routes the caller.
Maintenance Agent — collects repair details and logs a ticket via a tool.
FAQ Agent — answers general property questions via a bilingual FAQ API.

What you will learn

How to think about designing voice agents and how they differ from text based agents
Considerations for selecting the parts of your voice agent stack
System prompt design best practices for voice agents
How to build in the Vapi ecosystem

\n\n\n

How this workshop works

This companion is designed to work alongside live instruction. You will see various breakpoints where we will come back together as a class and go deeper into a concept.

Everything is managed as code using the Vapi GitOps repo. We will also utilize the Vapi dashboard for testing.

Follow along using the sidebar. Each step has copy-paste code blocks, the links you'll need, and occasional short quizzes to test your knowledge.

\n\n

\n \n

Pause — check in with Amanda

Designing voice agents

let's get under the hood

\n \n\n \n

\n Part 0\n

Setup

We manage everything as code: assistants, tools, and squads live as files in a repo and get pushed to Vapi with one command.

\n\n

Before you start

Vapi account: dashboard.vapi.ai
GitHub access: github.com/VapiAI/gitops
Local tools: Node.js 18+, npm, Git, and a code editor

\n\n

Verify your local tools

node --version\nnpm --version\ngit --version

If all three print versions, you're good to go.

\n\n

Step 1 — Clone the GitOps repo

git clone https://github.com/VapiAI/gitops greenfield-demo\ncd greenfield-demo

\n\n

Step 2 — Install dependencies

npm install

\n\n

Step 3 — Configure your environment

Open dashboard.vapi.ai/org/api-keys, copy your Private API Key, and create a .env.dev file in the project root:

echo 'VAPI_TOKEN=your-vapi-private-key-here' > .env.dev

Replace your-vapi-private-key-here with the private key you copied.

\n Why the private key, not the public one? The public key is scoped to web-call creation only and will fail with 401 Invalid Key against GitOps pull/push endpoints.\n

\n\n

Step 4 — Bootstrap the state file

Bootstrap creates .vapi-state.dev.json, which maps your local files to the resource IDs in your Vapi account:

npm run pull -- dev --bootstrap

\n\n

Step 5 — Create the resource directories

mkdir -p resources/dev/assistants\nmkdir -p resources/dev/tools\nmkdir -p resources/dev/squads

\n\n

Your project should look like this:

greenfield-demo/\n├── .env.dev\n├── .vapi-state.dev.json\n├── resources/\n│   └── dev/\n│       ├── assistants/\n│       ├── tools/\n│       └── squads/\n└── package.json

\n\n

\n\n \n

\n Part 1\n

Create the Language Triage Agent

\n\n

The three assistants share a stack

All three use the same voice, transcriber, and LLM, so call quality stays consistent across handoffs:

Voice: Cartesia sonic-3 · voiceId 2821fd0c-35c7-4adf-9c42-32e394bf85cb
Transcriber: Deepgram nova-3 with language: multi
LLM: Groq openai/gpt-oss-120b

\n\n

\n \n

Pause — check in with Amanda

How to choose your voice agent stack

the soul of your agent

\n\n

This assistant always answers the call first. Its only job: figure out the caller's language and route them to the right specialist.

\n\n

Create the assistant file

Create resources/dev/assistants/language-triage-agent.md:

---\nname: Language Triage Agent\nfirstMessage: \"Hello! Hola! I can help in English or Spanish. Tell me what you need, and I'll route you to the right specialist.\"\nvoice:\n  provider: cartesia\n  model: sonic-3\n  voiceId: 2821fd0c-35c7-4adf-9c42-32e394bf85cb\nmodel:\n  provider: groq\n  model: openai/gpt-oss-120b\n  temperature: 0\ntranscriber:\n  provider: deepgram\n  model: nova-3\n  language: multi\n  smartFormat: true\nendCallFunctionEnabled: true\nendCallMessage: \"Thank you for calling Greenfield Property Management. Gracias por llamar a Greenfield Property Management.\"\nsilenceTimeoutSeconds: 30\nmaxDurationSeconds: 600\nbackgroundDenoisingEnabled: true\nbackgroundSound: off\n---\n\n# Identity & Purpose\n\nYou are the language and intent router for Greenfield Property Management.\n\nYou support exactly two languages:\n- English\n- Spanish\n\nYour job is to do two things quickly:\n1. Detect whether the caller should be handled in English or Spanish\n2. Route them to the correct specialist:\n   - Maintenance Agent for repair issues\n   - FAQ Agent for general property questions\n\nYou do not solve the caller's issue yourself beyond a short routing acknowledgement.\n\n# Guardrails\n\n- If the caller speaks a language other than English or Spanish, politely ask them to continue in English or Spanish.\n- If the caller starts in English, route with `selected_language: en`.\n- If the caller starts in Spanish, route with `selected_language: es`.\n- If the intent is unclear, ask one short clarifying question before routing.\n- Do not collect full maintenance details.\n- Do not answer policy questions yourself.\n- Route as soon as you are confident.\n\n# Response Style\n\n- Be brief and confident.\n- Use the caller's language once you know it.\n- Keep routing language natural, for example:\n  - English: \"Got it - I am connecting you to our maintenance specialist.\"\n  - Spanish: \"Entendido - le conecto con nuestro especialista de mantenimiento.\"\n\n# Workflow\n\n## STEP 1: Listen for the first real request\n\nIdentify both:\n- language: English or Spanish\n- intent: maintenance or general question\n\n## STEP 2: If needed, clarify once\n\nIf you cannot tell whether the caller needs maintenance help or a general answer, ask one short question.\n\n## STEP 3: Route\n\nUse the correct handoff tool and include:\n- `selected_language`: `en` or `es`\n- `reason`: short summary of why you are routing\n\nExamples:\n- \"English caller reporting a leaking sink\"\n- \"Spanish caller asking about pet policy\"\n\n# Error Handling\n\n- If the caller is hard to understand, ask them to repeat once.\n- If they stay unclear after that, offer English or Spanish explicitly and ask them to choose.

\n\n

Push it to Vapi

npm run apply -- dev --allow-new-files

\n\n

You should see:

[assistants] Creating: Language Triage Agent\n[assistants] Created: Language Triage Agent -> <uuid>

\n\n

At this point the triage agent exists in Vapi — but it won't route anywhere yet, because we haven't created the squad handoff rules. That comes in Part 6.

\n\n

\n\n \n

\n Part 2\n

Create the Maintenance Agent

The specialist that takes over after the triage agent routes a maintenance call. It collects details and logs a ticket using the log_maintenance_request tool (which we'll wire up in Part 3).

\n\n

Create the assistant file

Create resources/dev/assistants/maintenance-agent.md:

---\nname: Maintenance Agent\nfirstMessage: \"\"\nfirstMessageMode: assistant-speaks-first-with-model-generated-message\nvoice:\n  provider: cartesia\n  model: sonic-3\n  voiceId: 2821fd0c-35c7-4adf-9c42-32e394bf85cb\nmodel:\n  provider: groq\n  model: openai/gpt-oss-120b\n  temperature: 0\n  toolIds:\n    - log-maintenance-request\ntranscriber:\n  provider: deepgram\n  model: nova-3\n  language: multi\n  smartFormat: true\nendCallFunctionEnabled: true\nendCallMessage: \"Thank you for calling. Gracias por llamar.\"\nsilenceTimeoutSeconds: 30\nmaxDurationSeconds: 600\nbackgroundDenoisingEnabled: true\nbackgroundSound: off\n---\n\n# RE-ENTRY PROTOCOL\n\nIf this is the first turn of the call (no prior conversation in your context), greet the caller and begin the workflow.\n\nIf you are receiving control via a handoff (prior conversation present), do NOT re-greet. Pick up from where the previous specialist left off.\n\n# Identity & Purpose\n\nYou are a virtual maintenance coordinator named Alex for Greenfield Property Management.\n\nYou support callers in English and Spanish.\n\nIf the prior handoff includes a `selected_language` argument, continue in that language unless the caller clearly switches. Otherwise, mirror the language the caller is currently using.\n\nYour primary goal is to collect the details of a maintenance request and log it with the `log_maintenance_request` tool.\n\n# Guardrails\n\n- Only handle maintenance issues.\n- If the caller asks a general property question, hand off to the FAQ Agent and preserve the same `selected_language`.\n- Do not promise exact repair times.\n- Do not collect sensitive information such as Social Security numbers, bank details, or passwords.\n\n# Response Guidelines\n\n- Ask one question at a time.\n- Keep responses short and natural.\n- Confirm key details before submitting the tool.\n- Tell the caller before calling the tool.\n\n# Workflow\n\n## STEP 1: Collect the details\n\nGather:\n1. Tenant name\n2. Unit number\n3. Issue description\n4. Urgency\n\n## STEP 2: Confirm\n\nRepeat the details back in the caller's language and ask for confirmation.\n\n## STEP 3: Log the request\n\nSay you are logging it, then call `log_maintenance_request`.\n\n## STEP 4: Wrap up\n\nIf the tool succeeds, confirm that the request was logged.\n\nIf the caller asks a general property question at any point, transfer them to the FAQ Agent with the same working language.

\n\n

Save it, but do not apply yet

\n \n

Pause — check in with Amanda

How to design a good system prompt for voice agents

the soul of your agent

\n\n \n

\n Part 3\n

Connect the maintenance tool

\n\n \n

Create the tool file

Create resources/dev/tools/log-maintenance-request.yml:

type: function\nasync: false\nfunction:\n  name: log_maintenance_request\n  description: Log a tenant maintenance request with the tenant name, unit number, issue description, and urgency level.\n  strict: true\n  parameters:\n    type: object\n    properties:\n      tenant_name:\n        type: string\n        description: Full name of the tenant\n      unit_number:\n        type: string\n        description: Unit number, for example 4B or 12A\n      issue_description:\n        type: string\n        description: Description of the maintenance issue\n      urgency:\n        type: string\n        enum: [low, medium, high, emergency]\n        description: Issue urgency level\n    required:\n      - tenant_name\n      - unit_number\n      - issue_description\n      - urgency\nmessages:\n  - type: request-start\n    blocking: true\n    contents:\n      - type: text\n        text: \"One moment while I log that for you.\"\n        language: en\n      - type: text\n        text: \"Un momento mientras registro eso.\"\n        language: es\n  - type: request-response-delayed\n    timingMilliseconds: 5000\n    contents:\n      - type: text\n        text: \"Still logging that - just a moment.\"\n        language: en\n      - type: text\n        text: \"Sigo registrando eso - un momento.\"\n        language: es\n  - type: request-failed\n    contents:\n      - type: text\n        text: \"I could not log that right now, but our team will follow up.\"\n        language: en\n      - type: text\n        text: \"No pude registrarlo ahora mismo, pero nuestro equipo dará seguimiento.\"\n        language: es\nserver:\n  url: https://amandamartin--248cf452507911f1b0bfee650bb23af1.web.val.run/log\n  timeoutSeconds: 20

\n\n

Replace the server.url with the hosted endpoint shown above, then push:

npm run apply -- dev --allow-new-files

\n\n

You should see the tool created and the Maintenance Agent created or updated with the resolved tool reference:

[tools] Creating: log_maintenance_request\n[tools] Created: log_maintenance_request -> <uuid>\n[assistants] Creating/Updating: Maintenance Agent (resolved toolIds)

\n\n

\n\n \n

\n Part 4\n

Create the FAQ Agent

The second specialist. Handles general property questions like \"when is rent due?\" or \"aceptan mascotas?\" by searching a bilingual FAQ via the search_faqs tool (wired up in Part 5).

\n\n

Create the assistant file

Create resources/dev/assistants/faq-agent.md:

---\nname: FAQ Agent\nfirstMessage: \"\"\nfirstMessageMode: assistant-speaks-first-with-model-generated-message\nvoice:\n  provider: cartesia\n  model: sonic-3\n  voiceId: 2821fd0c-35c7-4adf-9c42-32e394bf85cb\nmodel:\n  provider: groq\n  model: openai/gpt-oss-120b\n  temperature: 0\n  toolIds:\n    - search-faqs\ntranscriber:\n  provider: deepgram\n  model: nova-3\n  language: multi\n  smartFormat: true\nendCallFunctionEnabled: true\nendCallMessage: \"Glad I could help. Me alegra haber ayudado.\"\nsilenceTimeoutSeconds: 30\nmaxDurationSeconds: 600\nbackgroundDenoisingEnabled: true\nbackgroundSound: off\n---\n\n# RE-ENTRY PROTOCOL\n\nIf this is the first turn of the call (no prior conversation in your context), greet the caller and begin the workflow.\n\nIf you are receiving control via a handoff (prior conversation present), do NOT re-greet. Pick up from where the previous specialist left off.\n\n# Identity & Purpose\n\nYou are a virtual assistant named Jordan for Greenfield Property Management.\n\nYou support callers in English and Spanish.\n\nIf the prior handoff includes a `selected_language` argument, continue in that language unless the caller clearly switches. Otherwise, mirror the caller's current language.\n\nYour job is to answer general property questions accurately by using the `search_faqs` tool.\n\n# Guardrails\n\n- Only handle general property questions.\n- If the caller needs maintenance help, transfer them to the Maintenance Agent and preserve the same `selected_language`.\n- Do not guess if you do not know the answer.\n- Always use the tool before answering factual policy questions.\n\n# Response Guidelines\n\n- Keep answers short and conversational.\n- Summarize the tool result in 1-3 sentences.\n- Call the tool with both:\n  - `query`\n  - `language` set to `en` or `es`\n\n# Workflow\n\n## STEP 1: Understand the question\n\nIf it is really a maintenance issue, transfer immediately.\n\n## STEP 2: Search\n\nTell the caller you are looking it up, then call `search_faqs`.\n\n## STEP 3: Answer\n\nAnswer in the caller's current language.\n\n## STEP 4: Follow up\n\nAsk whether they need anything else.

\n\n

Save it, but do not apply yet

\n\n

\n\n \n

\n Part 5\n

Wire up the bilingual FAQ tool

\n\n

Create the tool file

Create resources/dev/tools/search-faqs.yml:

type: function\nasync: false\nfunction:\n  name: search_faqs\n  description: Search the Greenfield Property Management bilingual FAQs and return an answer in English or Spanish.\n  strict: true\n  parameters:\n    type: object\n    properties:\n      query:\n        type: string\n        description: Search query based on the caller's question\n      language:\n        type: string\n        enum: [en, es]\n        description: Language to use for the returned answer\n    required:\n      - query\n      - language\nmessages:\n  - type: request-start\n    blocking: true\n    contents:\n      - type: text\n        text: \"Let me look that up for you.\"\n        language: en\n      - type: text\n        text: \"Permítame buscar eso.\"\n        language: es\n  - type: request-response-delayed\n    timingMilliseconds: 5000\n    contents:\n      - type: text\n        text: \"Still searching - one moment.\"\n        language: en\n      - type: text\n        text: \"Sigo buscando - un momento.\"\n        language: es\n  - type: request-failed\n    contents:\n      - type: text\n        text: \"I am having trouble looking that up right now.\"\n        language: en\n      - type: text\n        text: \"Estoy teniendo problemas para buscar eso ahora mismo.\"\n        language: es\nserver:\n  url: https://amandamartin--0e6748704fe911f1ab05ee650bb23af1.web.val.run/search\n  timeoutSeconds: 20

\n\n

Replace the placeholder URL with the real hosted endpoint, then push:

npm run apply -- dev --allow-new-files

\n\n

Expected output includes the tool being created and the FAQ Agent being created or updated with the resolved tool reference:

[tools] Creating: search_faqs\n[tools] Created: search_faqs -> <uuid>\n[assistants] Creating/Updating: FAQ Agent (resolved toolIds)

\n\n

\n\n \n

\n Part 6\n

Wire everything together as a squad

\n \n

Pause — check in with Amanda

Let's talk about squads

Use squads when specialization makes the call easier to control: each assistant owns a clear workflow, and handoffs pass only the context the next assistant needs.

Create the squad file

Create resources/dev/squads/greenfield-property-management-bilingual.yml:

name: Greenfield Property Management - Bilingual\nmembers:\n  - assistantId: language-triage-agent\n    assistantOverrides:\n      tools:append:\n        - type: handoff\n          async: false\n          messages: []\n          function:\n            name: route_to_Maintenance_Agent\n            description: Route the caller to the Maintenance Agent after identifying English or Spanish and confirming the issue is maintenance-related.\n            parameters:\n              type: object\n              properties:\n                destination:\n                  type: string\n                  enum: [\"Maintenance Agent\"]\n                  description: The squad member to hand off to\n                selected_language:\n                  type: string\n                  enum: [en, es]\n                  description: Working language for the rest of the conversation\n                reason:\n                  type: string\n                  description: Short reason for the handoff\n              required:\n                - destination\n                - selected_language\n                - reason\n          destinations:\n            - type: assistant\n              assistantName: Maintenance Agent\n              description: Handles maintenance requests in English or Spanish\n        - type: handoff\n          async: false\n          messages: []\n          function:\n            name: route_to_FAQ_Agent\n            description: Route the caller to the FAQ Agent after identifying English or Spanish and confirming the request is a general property question.\n            parameters:\n              type: object\n              properties:\n                destination:\n                  type: string\n                  enum: [\"FAQ Agent\"]\n                  description: The squad member to hand off to\n                selected_language:\n                  type: string\n                  enum: [en, es]\n                  description: Working language for the rest of the conversation\n                reason:\n                  type: string\n                  description: Short reason for the handoff\n              required:\n                - destination\n                - selected_language\n                - reason\n          destinations:\n            - type: assistant\n              assistantName: FAQ Agent\n              description: Handles general property questions in English or Spanish\n  - assistantId: maintenance-agent\n    assistantOverrides:\n      tools:append:\n        - type: handoff\n          async: false\n          messages: []\n          function:\n            name: handoff_to_FAQ_Agent\n            description: Transfer the caller to the FAQ Agent when they ask a non-maintenance property question. Preserve the selected language.\n            parameters:\n              type: object\n              properties:\n                destination:\n                  type: string\n                  enum: [\"FAQ Agent\"]\n                  description: The squad member to hand off to\n                selected_language:\n                  type: string\n                  enum: [en, es]\n                  description: Continue the call in this language\n                reason:\n                  type: string\n                  description: Short reason for the handoff\n              required:\n                - destination\n                - selected_language\n                - reason\n          destinations:\n            - type: assistant\n              assistantName: FAQ Agent\n              description: Handles general property questions in English or Spanish\n  - assistantId: faq-agent\n    assistantOverrides:\n      tools:append:\n        - type: handoff\n          async: false\n          messages: []\n          function:\n            name: handoff_to_Maintenance_Agent\n            description: Transfer the caller to the Maintenance Agent when they describe a repair issue. Preserve the selected language.\n            parameters:\n              type: object\n              properties:\n                destination:\n                  type: string\n                  enum: [\"Maintenance Agent\"]\n                  description: The squad member to hand off to\n                selected_language:\n                  type: string\n                  enum: [en, es]\n                  description: Continue the call in this language\n                reason:\n                  type: string\n                  description: Short reason for the handoff\n              required:\n                - destination\n                - selected_language\n                - reason\n          destinations:\n            - type: assistant\n              assistantName: Maintenance Agent\n              description: Handles maintenance requests in English or Spanish

\n\n

Push the squad

npm run apply -- dev --allow-new-files

You should see:

[squads] Creating: Greenfield Property Management - Bilingual\n[squads] Created: Greenfield Property Management - Bilingual -> <uuid>

\n\n

\n You're live! The squad is now running in your Vapi account. Head to the test scenarios next to try it out.\n

\n\n

\n\n \n

\n Test\n

Connect to a phone number and test!

\n \n

Pause — check in with Amanda

The Vapi Dashboard

We've been living in code; now we let the dashboard prove whether our beautiful YAML has manners.

For this workshop, test from the Vapi Dashboard instead of npm run call -- dev. The local WebSocket path in the GitOps repo still has rough edges; the dashboard \"Talk\" button is the smooth path.

\n \n

Example Test Scenarios

Scenario 1 — English maintenance request

\"Hi, my bathroom faucet is leaking.\"

Expected: Triage selects English → routes to Maintenance Agent → Maintenance Agent collects the details and logs the request.

\n\n

Scenario 2 — Spanish FAQ

\"Hola, quería preguntar si aceptan mascotas.\"

Expected: Triage selects Spanish → routes to FAQ Agent → FAQ Agent calls search_faqs with language: es → caller gets the answer in Spanish.

\n\n

Scenario 3 — English FAQ → maintenance handoff

\"When is rent due?\"
\"Actually, I also need to report that my heater stopped working.\"

Expected: Triage routes to FAQ Agent → FAQ Agent answers → FAQ Agent hands off to Maintenance Agent when the topic shifts.

\n\n

Scenario 4 — Spanish maintenance → FAQ handoff

\"Tengo un problema con el aire acondicionado.\"
\"Y otra cosa, cuál es el horario de oficina?\"

Expected: Triage routes to Maintenance Agent in Spanish → Maintenance Agent starts intake → hands off to FAQ Agent in Spanish.

\n\n

Challenge — Language switch mid-call

Start in English, then switch to Spanish after the handoff: \"Actually, también quiero preguntar sobre mascotas.\"

\n\n \n

\n Help\n

Troubleshooting

Get stuck? Check here first, then ask your agent of choice to debug.

\n\n

Specific errors and fixes

\n\n

\"Pull halted\" / \"pull diverged\" (most common during Part 3 and Part 5)

This means your local state file and what's actually in Vapi have drifted apart. The fix is a bootstrap re-sync, then apply again:

npm run pull -- dev --bootstrap\nnpm run apply -- dev --allow-new-files

If pull itself errors on the same machine, nuke the local state file and re-bootstrap (safe, Vapi has the source of truth):

rm .vapi-state.dev.json\nnpm run pull -- dev --bootstrap\nnpm run apply -- dev --allow-new-files

\n\n

\n Still stuck? Build the whole thing in Composer instead\n

Open dashboard.vapi.ai, find Composer, and paste the prompt below. It tells Composer to build the full squad in the browser, no terminal required.

Build me a bilingual (English/Spanish) inbound voice system for Greenfield Property Management as a squad of three Vapi assistants.\n\n1) A \"Language Triage Agent\" that answers first, detects whether the caller is speaking English or Spanish, identifies whether they need maintenance help or have a general property question, then routes them to the right specialist. It does not solve the issue itself.\n\n2) A \"Maintenance Agent\" named Alex that collects a maintenance request (tenant name, unit number, issue description, urgency one of low/medium/high/emergency), confirms the details with the caller, then logs the ticket via a function tool called log_maintenance_request. The tool's server URL is https://amandamartin--248cf452507911f1b0bfee650bb23af1.web.val.run/log\n\n3) An \"FAQ Agent\" named Jordan that answers general property questions (rent, pets, parking, office hours) in English or Spanish by always calling a function tool called search_faqs before answering. The tool takes a query string and a language string (en or es). The tool's server URL is https://amandamartin--0e6748704fe911f1ab05ee650bb23af1.web.val.run/search\n\nWire them into a squad with handoffs so the triage agent can route to either specialist, and the specialists can hand off to each other if the topic changes mid-call. Preserve the caller's selected language across handoffs. Do not re-greet on handoff.\n\nShared stack across all three assistants: Deepgram nova-3 with language \"multi\" for transcription, Groq openai/gpt-oss-120b for the LLM with temperature 0 on the triage agent, Cartesia sonic-3 voiceId 2821fd0c-35c7-4adf-9c42-32e394bf85cb for the voice.

\n\n

\"VAPI_TOKEN not set\"

Make sure .env.dev exists in the project root and contains VAPI_TOKEN=your-key.

\n\n

Apply surfaces update / overwrite errors

Refresh state with npm run pull -- dev --bootstrap, then apply again.

\n\n

Single-file apply seems to do nothing

Retry with a broader scope: npm run apply -- dev --allow-new-files assistants, ... tools, or a full npm run apply -- dev --allow-new-files.

\n\n

npm run call -- dev does not connect

Use the Vapi Dashboard \"Talk\" button for this workshop instead.

\n\n

Spanish FAQ answers come back wrong or empty

Verify the tool is being called with language: es, and that the FAQ data has Spanish fields and keywords.

\n\n

Tool call times out

Confirm the server.url on the tool matches the hosted endpoint, and that calling it directly with curl returns valid JSON.

\n\n

Agent never hands off

Check that assistantName in the squad exactly matches the assistant's name field (case-sensitive).

\n\n

Voice is inconsistent across assistants

All three assistant files must use the same Cartesia config and the exact same voiceId.

\n\n

Advanced multilingual note — tool messages keep playing in English

\n\n

Resources for curious attendees

\n\n

Maintenance endpoint internals

The endpoint is a small Hono server. It accepts Vapi's tool-call request body and returns a result in the shape Vapi expects:

import { Hono } from \"npm:hono\";\n\nconst app = new Hono();\n\napp.get(\"/\", (c) => {\n  return c.json({ status: \"ok\", message: \"Maintenance Logger for Vapi\" });\n});\n\napp.post(\"/log\", async (c) => {\n  let toolCallId = \"unknown\";\n  try {\n    const body = await c.req.json();\n\n    // body.message.toolCallList[i].function.arguments is sent as an OBJECT\n    // by Vapi (the SDK types claim string, but the runtime payload is the\n    // already-parsed object). Defensive handling for both shapes.\n    const toolCall = body?.message?.toolCallList?.[0];\n    toolCallId = toolCall?.id ?? \"unknown\";\n    const rawArgs = toolCall?.function?.arguments;\n    const args = typeof rawArgs === \"string\" ? JSON.parse(rawArgs) : (rawArgs ?? {});\n\n    console.log(\"Maintenance request:\", args);\n\n    return c.json({\n      results: [\n        {\n          toolCallId,\n          result: `Logged ${args.urgency ?? \"unspecified\"}-priority maintenance request from ${args.tenant_name ?? \"(unknown tenant)\"} for unit ${args.unit_number ?? \"(unknown)\"}: ${args.issue_description ?? \"(no description)\"}. The team will follow up shortly.`,\n        },\n      ],\n    });\n  } catch (err) {\n    console.error(\"Maintenance logger error:\", err);\n    // Always return HTTP 200 — Vapi ignores non-200 responses entirely\n    return c.json({\n      results: [\n        {\n          toolCallId,\n          error: String(err instanceof Error ? err.message : err),\n        },\n      ],\n    });\n  }\n});\n\nexport default app.fetch;

Two things worth noticing:

Defensive arg parsing. The SDK types claim function.arguments is a string, but at runtime Vapi often sends the parsed object. The handler accepts both.
Always return HTTP 200. Vapi treats non-200 responses as a transport failure, so we always 200 — even on error — and put the error inside the results[] payload.

\n\n

FAQ API internals

\n\n

main.ts

import { Hono } from \"npm:hono\";\nimport { faqs } from \"./faqs.ts\";\n\nconst app = new Hono();\n\napp.get(\"/\", (c) => {\n  return c.json({ status: \"ok\", message: \"Bilingual FAQ API for Vapi\" });\n});\n\napp.post(\"/search\", async (c) => {\n  let toolCallId = \"unknown\";\n  try {\n    const body = await c.req.json();\n    const toolCall = body?.message?.toolCallList?.[0];\n    toolCallId = toolCall?.id ?? \"unknown\";\n    const rawArgs = toolCall?.function?.arguments;\n    const args = typeof rawArgs === \"string\" ? JSON.parse(rawArgs) : (rawArgs ?? {});\n\n    const query = String(args.query ?? \"\").trim();\n    const language = args.language === \"es\" ? \"es\" : \"en\";\n\n    // Word-level scoring with a full-list fallback: always return something\n    // useful so the LLM doesn't retry with a different query.\n    const queryWords = query.toLowerCase().split(/\\s+/).filter((w) => w.length > 0);\n\n    const scored = faqs.map((entry) => {\n      const haystack = [\n        entry.topic,\n        ...entry.keywords,\n        entry.question_en, entry.question_es,\n        entry.answer_en,   entry.answer_es,\n      ].join(\" \").toLowerCase();\n      const score = queryWords.filter((w) => haystack.includes(w)).length;\n      return { entry, score };\n    });\n\n    const topMatches = scored\n      .filter((s) => s.score > 0)\n      .sort((a, b) => b.score - a.score)\n      .map((s) => s.entry);\n\n    // No matches? Return ALL FAQs so the LLM picks the right one instead of retrying.\n    const final = topMatches.length > 0 ? topMatches : faqs;\n\n    const result = final\n      .map((entry) => (language === \"es\" ? entry.answer_es : entry.answer_en))\n      .join(\" \");\n\n    return c.json({ results: [{ toolCallId, result }] });\n  } catch (err) {\n    console.error(\"FAQ search error:\", err);\n    return c.json({\n      results: [{ toolCallId, error: String(err instanceof Error ? err.message : err) }],\n    });\n  }\n});\n\nexport default app.fetch;

\n\n

faqs.ts

export const faqs = [\n  { topic: \"rent\",\n    keywords: [\"rent\",\"due date\",\"late fee\",\"renta\",\"fecha de pago\",\"cargo por retraso\"],\n    question_en: \"When is rent due?\",\n    question_es: \"Cuando se vence la renta?\",\n    answer_en: \"Rent is due on the 1st of each month. A $50 late fee is applied after the 5th.\",\n    answer_es: \"La renta se vence el dia 1 de cada mes. Despues del dia 5 se aplica un cargo por retraso de $50.\" },\n  { topic: \"payments\",\n    keywords: [\"pay rent\",\"tenant portal\",\"pagar renta\",\"portal\"],\n    question_en: \"How do I pay rent?\",\n    question_es: \"Como pago la renta?\",\n    answer_en: \"You can pay rent through the tenant portal, by mailing a check, or by setting up direct deposit.\",\n    answer_es: \"Puede pagar la renta por el portal de inquilinos, enviando un cheque por correo o configurando deposito directo.\" },\n  { topic: \"pets\",\n    keywords: [\"pets\",\"cats\",\"dogs\",\"mascotas\",\"gatos\",\"perros\"],\n    question_en: \"What is the pet policy?\",\n    question_es: \"Cual es la politica de mascotas?\",\n    answer_en: \"Pets are allowed with a signed pet addendum. There is a $300 pet deposit and $25 monthly pet rent.\",\n    answer_es: \"Se permiten mascotas con un anexo firmado. Hay un deposito de $300 y una renta mensual de mascotas de $25.\" },\n  { topic: \"parking\",\n    keywords: [\"parking\",\"guest parking\",\"estacionamiento\",\"visitantes\"],\n    question_en: \"What are the parking rules?\",\n    question_es: \"Cuales son las reglas de estacionamiento?\",\n    answer_en: \"Each unit gets one assigned parking spot. Guest parking is available in the visitor lot.\",\n    answer_es: \"Cada unidad tiene un lugar asignado. El estacionamiento para visitantes esta disponible en el lote de visitas.\" },\n  { topic: \"maintenance\",\n    keywords: [\"maintenance\",\"repair\",\"mantenimiento\",\"reparacion\"],\n    question_en: \"How do I submit a maintenance request?\",\n    question_es: \"Como envio una solicitud de mantenimiento?\",\n    answer_en: \"You can report maintenance by calling this line, using the tenant portal, or visiting the office.\",\n    answer_es: \"Puede reportar mantenimiento llamando a esta linea, usando el portal de inquilinos o visitando la oficina.\" },\n  { topic: \"office\",\n    keywords: [\"office hours\",\"hours\",\"horario\",\"oficina\"],\n    question_en: \"What are the office hours?\",\n    question_es: \"Cual es el horario de oficina?\",\n    answer_en: \"The office is open Monday through Friday, 9 AM to 5 PM, and Saturday from 10 AM to 2 PM.\",\n    answer_es: \"La oficina abre de lunes a viernes de 9 AM a 5 PM, y los sabados de 10 AM a 2 PM.\" },\n];

\n\n

Useful links

\n\n \n

\n <3\n

Connect with Vapi

\n\n

Presentation

This slide deck was used by the instructor during the live workshop

\n \n

Join the Community

\n\n \n \n

Diff · v21