Skip to content

Commit d923786

Browse files
nickrobincursoragent
nickrobin
and
cursoragent
committed
docs: add Composer feature documentation (Alpha)
Add new documentation page for Composer, Vapi's AI-powered agent builder. Includes overview, getting started steps, use cases, safety features, and best practices. Marked as pre-release in navigation. Co-authored-by: Cursor <cursoragent@cursor.com>
1 parent b1347d7 commit d923786

2 files changed

Lines changed: 290 additions & 0 deletions

File tree

‎fern/composer.mdx‎

Lines changed: 286 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,286 @@
1+
---
2+
title: Composer
3+
subtitle: Build and configure voice AI agents through natural conversation
4+
slug: composer
5+
---
6+
7+
<Warning>
8+
Composer is currently in **Alpha**. Features and behavior may change as we iterate based on user feedback.
9+
</Warning>
10+
11+
## Overview
12+
13+
Composer is Vapi's intelligent assistant that helps you build and configure voice AI agents through natural conversation. Instead of manually configuring settings and writing prompts, describe what you want to build and Composer handles the technical setup.
14+
15+
Composer understands voice agent architecture and Vapi's capabilities. It can create agents, configure phone numbers, set up integrations, troubleshoot issues, and answer questions about Vapi features.
16+
17+
**Why use Composer:**
18+
19+
- **Faster development** — Build agents in minutes instead of hours by describing your use case
20+
- **Best practices built in** — Composer applies Vapi best practices automatically
21+
- **Lower barrier to entry** — No need to learn every API parameter or configuration option
22+
- **Troubleshooting support** — Composer can diagnose issues and suggest fixes
23+
24+
## Get started
25+
26+
<Steps>
27+
<Step title="Open Composer">
28+
Log into your [Vapi dashboard](https://dashboard.vapi.ai) and click the **Composer** option in the navigation, or use the chat widget.
29+
</Step>
30+
<Step title="Describe what you want to build">
31+
Tell Composer what you need in plain language. The more context you provide, the better the result.
32+
33+
**Effective prompts:**
34+
- "Help me build a restaurant reservation agent"
35+
- "I need to set up a phone number for my agent"
36+
- "Create an agent that can answer questions about my business"
37+
- "My agent isn't transferring calls correctly, can you help?"
38+
</Step>
39+
<Step title="Answer clarifying questions">
40+
Composer asks follow-up questions to understand your requirements, then takes action to build and configure your agent.
41+
</Step>
42+
<Step title="Test and iterate">
43+
Test the agent Composer creates, then request adjustments as needed. Building the right agent is an iterative process.
44+
</Step>
45+
</Steps>
46+
47+
## What Composer can do
48+
49+
### Capabilities
50+
51+
- Create and configure assistants
52+
- Set up phone numbers
53+
- Configure integrations and webhooks
54+
- Update agent prompts and settings
55+
- Troubleshoot technical issues
56+
- Answer questions about Vapi features
57+
- Recommend best practices for your use case
58+
59+
### Limitations
60+
61+
- **Cannot delete resources** — Composer cannot delete assistants, tools, phone numbers, or any other resources. This is an intentional safety measure. Use the dashboard sidebar to delete resources manually.
62+
- **Cannot access external systems** — Composer operates within Vapi and cannot reach your CRM, database, or other third-party systems directly.
63+
- **Cannot make business logic decisions** — You provide the domain knowledge; Composer handles the technical configuration.
64+
- **Cannot test your agent** — You need to test the agent yourself and provide feedback.
65+
- **Cannot deploy to production automatically** — You control when and how changes go live.
66+
67+
## Common use cases
68+
69+
<AccordionGroup>
70+
<Accordion title="Build a new agent from scratch">
71+
**What you say:**
72+
73+
> "I want to build an agent for my dental office that can schedule appointments and answer common questions about our services."
74+
75+
**What Composer does:**
76+
1. Asks about your specific requirements (hours, services, appointment types)
77+
2. Creates an agent with an appropriate system prompt
78+
3. Configures necessary tools (calendar integration, knowledge base)
79+
4. Sets up phone number configuration
80+
5. Provides testing guidance
81+
82+
**Your part:**
83+
- Answer Composer's questions about your business
84+
- Provide specific details (office hours, services offered, etc.)
85+
- Test the agent and provide feedback
86+
87+
**Example conversation:**
88+
89+
```txt title="Sample conversation"
90+
You: "I want to build an agent for my dental office that can schedule
91+
appointments and answer common questions."
92+
93+
Composer: "I'd be happy to help you build a dental office agent! Let me
94+
ask a few questions:
95+
96+
1. What are your office hours?
97+
2. What types of appointments do you offer?
98+
3. Do you want the agent to book directly or collect information
99+
for your staff to follow up?
100+
4. What are the most common questions patients ask?"
101+
102+
You: "Office hours are Mon-Fri 9am-5pm. We do cleanings, exams, and
103+
consultations. The agent should collect appointment requests and our
104+
staff will confirm. Common questions are about insurance, parking,
105+
and first-visit procedures."
106+
107+
Composer: "I've created your dental office agent. It's configured to:
108+
- Collect appointment requests during business hours
109+
- Answer questions about insurance, parking, and first visits
110+
- Escalate to staff when needed
111+
112+
Would you like me to set up a phone number for testing?"
113+
```
114+
</Accordion>
115+
116+
<Accordion title="Set up a phone number">
117+
**What you say:**
118+
119+
> "I need to connect a phone number to my agent."
120+
121+
**What Composer does:**
122+
1. Asks if you want to purchase a new number or import an existing one
123+
2. Helps you select an area code or region
124+
3. Configures the number to work with your agent
125+
4. Provides the phone number for testing
126+
127+
<Tip>
128+
If you need a specific area code for local presence, mention it upfront. If you're porting an existing number, have your account details from your current provider ready.
129+
</Tip>
130+
</Accordion>
131+
132+
<Accordion title="Troubleshoot issues">
133+
**What you say:**
134+
135+
> "My agent keeps dropping calls when trying to transfer."
136+
137+
**What Composer does:**
138+
1. Asks diagnostic questions (when does it happen, what number, etc.)
139+
2. Checks your agent configuration
140+
3. Identifies the issue (incorrect transfer format, missing permissions, etc.)
141+
4. Fixes the configuration or guides you through the fix
142+
143+
**Common issues Composer can help with:**
144+
- Call transfers not working
145+
- Agent not responding correctly to specific inputs
146+
- Phone number routing problems
147+
- Integration failures (calendar, CRM, etc.)
148+
- Voice quality or latency issues
149+
- Prompt behavior not matching expectations
150+
</Accordion>
151+
152+
<Accordion title="Integrate with external systems">
153+
**What you say:**
154+
155+
> "I want my agent to check availability in our calendar before booking appointments."
156+
157+
**What Composer does:**
158+
1. Explains integration options (API webhooks, direct integrations)
159+
2. Helps configure the integration endpoint
160+
3. Sets up the agent to call your API with the right parameters
161+
4. Provides example requests/responses for testing
162+
163+
**Your part:**
164+
- Provide your API endpoint URL
165+
- Share authentication details (API keys, etc.)
166+
- Describe the expected request/response format
167+
- Test the integration with real scenarios
168+
169+
**Popular integrations:** Google Calendar, Calendly, Salesforce, HubSpot, booking systems, knowledge bases, and custom APIs.
170+
</Accordion>
171+
</AccordionGroup>
172+
173+
## Safety features
174+
175+
Composer includes safeguards to prevent accidental or irreversible changes to your account.
176+
177+
### No deletion capability
178+
179+
Composer **cannot delete any resources** — assistants, tools, phone numbers, squads, files, or anything else. This is a deliberate safety measure, not a limitation.
180+
181+
If you ask Composer to delete something, it directs you to do it yourself:
182+
183+
```txt title="Deletion request example"
184+
You: "Delete my old test assistant"
185+
186+
Composer: "I'm not able to delete resources to prevent accidental data loss.
187+
You can delete it yourself from the dashboard — use the sidebar on the left,
188+
go to Assistants, select the one you want to remove, and delete it from there."
189+
```
190+
191+
<Note>
192+
Unlike creating or updating a resource (which can be undone or re-done), deletion is permanent. Requiring manual confirmation through the dashboard UI prevents accidental loss of important configurations.
193+
</Note>
194+
195+
### Approval required for updates
196+
197+
When Composer modifies an existing resource (like updating an assistant's prompt, changing a voice setting, or editing a tool configuration), it pauses and asks for your explicit approval first.
198+
199+
**How the approval flow works:**
200+
201+
<Steps>
202+
<Step title="Composer proposes a change">
203+
Composer shows you a summary of the update it wants to make.
204+
</Step>
205+
<Step title="You review and respond">
206+
The chat interface displays **Approve** and **Deny** buttons. Click **Approve** to proceed or **Deny** to cancel.
207+
</Step>
208+
<Step title="Composer applies the change (if approved)">
209+
If approved, Composer makes the update and confirms. If denied, no changes are made.
210+
</Step>
211+
</Steps>
212+
213+
```txt title="Approval flow example"
214+
You: "Change my agent's voice to sound more energetic"
215+
216+
Composer: [Proposes update]
217+
→ UI shows: "Update Resource — Updating voice settings on assistant xyz"
218+
[Approve] [Deny]
219+
220+
You: [Clicks Approve]
221+
222+
Composer: "Done! I've updated the voice settings. Test it out and let me
223+
know if you'd like to adjust further."
224+
```
225+
226+
**Key details about approvals:**
227+
228+
- **Tokens expire after 10 minutes** — if you don't respond in time, Composer needs to re-propose the change
229+
- **Each approval is specific** — approval tokens are cryptographically bound to the exact change being made; multiple updates each require individual approval
230+
- **Read operations don't require approval** — Composer can freely read and list your resources without permission
231+
- **Creating new resources doesn't require approval** — new assistants, tools, and other resources are additive and non-destructive
232+
233+
## Tips for best results
234+
235+
### Be specific about your use case
236+
237+
Provide context about your industry, audience, and requirements upfront.
238+
239+
```txt title="Compare prompt quality"
240+
Less effective: "I need an agent"
241+
242+
More effective: "I need an agent for my e-commerce store that can track
243+
orders, answer product questions, and handle returns"
244+
```
245+
246+
### Iterate in stages
247+
248+
Build a basic working agent first, then layer on advanced features:
249+
250+
1. **Phase 1** — Basic conversation flow
251+
2. **Phase 2** — Add integrations (calendar, CRM, knowledge base)
252+
3. **Phase 3** — Add advanced features (custom voices, complex routing)
253+
254+
### Handle one task at a time
255+
256+
Keep conversations focused on a single objective for best results.
257+
258+
```txt title="Compare task scoping"
259+
Less effective: "Set up my phone number, fix the transfer issue, add
260+
Spanish support, and integrate with my CRM"
261+
262+
More effective: "First, let's set up my phone number"
263+
[Complete that task]
264+
"Great! Now can you help me fix the transfer issue?"
265+
```
266+
267+
### Ask Composer to explain
268+
269+
If you're unsure about Vapi features or want to learn the API, ask directly:
270+
271+
- "What's the best way to handle voicemail?"
272+
- "Should I use function calling or server URL for my integration?"
273+
- "Can you show me the API call you're making to create this agent?"
274+
275+
<Tip>
276+
Ask Composer for the full configuration of an agent it builds. Save it in version control to use as a template for similar agents.
277+
</Tip>
278+
279+
## Next steps
280+
281+
Now that you know how Composer works:
282+
283+
- **[Assistants quickstart](/assistants/quickstart):** Learn the fundamentals of building voice agents manually
284+
- **[Prompting guide](/prompting-guide):** Write effective system prompts for your agents
285+
- **[Tools overview](/tools):** Understand the tools and integrations available to your agents
286+
- **[Phone numbers](/phone-numbers/free-telephony):** Set up phone numbers for your agents

‎fern/docs.yml‎

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -115,6 +115,10 @@ navigation:
115115
- page: Vapi Guides
116116
icon: fa-light fa-book-open
117117
path: guides.mdx
118+
- page: Composer
119+
icon: fa-light fa-wand-magic-sparkles
120+
path: composer.mdx
121+
availability: pre-release
118122
- page: CLI quickstart
119123
icon: fa-light fa-terminal
120124
path: cli/overview.mdx

0 commit comments

Comments
 (0)