Skip to navigation
AssistantsExamples

Documentation agent

Build a voice assistant that answers questions about your docs

Overview

Build a voice-powered documentation assistant step by step. Choose between using the Dashboard interface or programmatic APIs to suit your workflow.

You’ll learn to:

  • Index your docs with LlamaCloud
  • Create an API Request tool for document retrieval
  • Create an assistant with Claude Sonnet 4.6 and attach the tool
  • Use the Web SDK to create a React voice widget
  • Review completed calls and improve the quality of your assistant over time

Prerequisites

Get started

1

Index your documentation

Create a searchable index with LlamaCloud Index v2:

  1. Create a directory and add the documentation files you want to search.
  2. Create an index that uses the directory as its source.
  3. Wait until the index status is ready, then copy the index ID. You use this ID when you configure the Vapi tool.

Index v2 parses, chunks, embeds, and indexes the files automatically. LlamaCloud manages the chunking and embedding settings. For more details, see the LlamaCloud Index getting started guide.

2

Create the retrieval tool

Create an API Request tool that connects your assistant to your LlamaCloud index.

  1. Navigate to Tools in your Vapi Dashboard.
  2. Click Create Tool.
  3. Select API Request as the tool type.
  4. Under Base Configuration, enter:
    • Tool Name: docsquery
    • Description: Search the documentation index for relevant information
    • Request URL: https://api.cloud.llamaindex.ai/api/v1/retrieval/retrieve
    • Request HTTP Method: POST
  5. Under Authorization, select the Bearer Token custom credential that contains your LlamaCloud API key.
  6. Under Request Body, add a required String property named query with the description The search query to find relevant documentation.
  7. Under Static Body Fields, add a String field named index_id and set its value to your LlamaCloud index ID.
  8. Add a Number field named top_k and set its value to 5.
  9. Select Publish, then copy the tool ID.

Replace YOUR_LLAMACLOUD_INDEX_ID and YOUR_LLAMACLOUD_CREDENTIAL_ID with the values for your LlamaCloud index and saved Vapi credential. The index_id field identifies the index, and top_k limits each retrieval to five results. The model supplies query for each retrieval.

LlamaCloud returns matches in results; the retrieved text is available in each result’s content field.

3

Create an assistant with the tool

Create an assistant with the API Request tool attached.

  1. Navigate to Assistants in your Vapi Dashboard.
  2. Click Create Assistant.
  3. Configure the assistant:
    • Name: Docs agent
    • Model: Claude Sonnet 4.6 (Anthropic)
    • Voice: Elliot (Vapi)
    • First Message: Hey I'm Harry, a support agent. How can I help you today? You can ask me questions about Vapi, how to get started, or our documentation.
    • System Prompt: Use a helpful documentation assistant prompt with guidelines for using the docsquery tool
  4. Add the docsquery tool in the Tools section.
  5. Publish the assistant.

Replace YOUR_TOOL_ID with the tool ID from the previous step. Save the assistant ID from the response for the next step.

4

Update the assistant's first message

Change your assistant’s first message after creation.

  1. Navigate to your assistant in the Vapi Dashboard.
  2. Change the first message to Hello! I am your documentation assistant. What would you like to know about our platform?.
  3. Select Publish to make the draft current.

Dashboard edits remain in a draft until you publish them. See Versioning with assistants for the complete publishing workflow.

5

Test the assistant

Test important decisions and complete conversation outcomes before sharing the assistant with users.

Test decisions with Evals

Check whether the assistant uses the documentation tool, answers from the result, and redirects requests outside its scope.

Test outcomes with Simulations

Run complete conversations with different questions and caller behaviors, then check whether the user gets a useful answer.

Start with a greeting, a supported documentation question, an ambiguous question, a tool error, and an unrelated request. See testing voice agents for guidance on building and maintaining coverage.

6

Create a React voice widget

In an existing React project, use the Vapi Web SDK to create a voice widget for your documentation assistant.

npm install @vapi-ai/web

Replace YOUR_PUBLIC_API_KEY and YOUR_ASSISTANT_ID with your actual values:

import { useEffect, useState } from 'react';
import Vapi from '@vapi-ai/web';
type TranscriptEntry = {
  role: 'assistant' | 'user';
  text: string;
};
export default function VoiceWidget() {
  const [vapi, setVapi] = useState<Vapi | null>(null);
  const [isConnected, setIsConnected] = useState(false);
  const [transcript, setTranscript] = useState<TranscriptEntry[]>([]);
  useEffect(() => {
    const vapiInstance = new Vapi('YOUR_PUBLIC_API_KEY');
    setVapi(vapiInstance);
    vapiInstance.on('call-start', () => setIsConnected(true));
    vapiInstance.on('call-end', () => setIsConnected(false));
    vapiInstance.on('message', (message) => {
      if (
        message?.type === 'transcript' &&
        message.transcriptType === 'final' &&
        (message.role === 'assistant' || message.role === 'user') &&
        typeof message.transcript === 'string'
      ) {
        setTranscript((previous) => [
          ...previous,
          { role: message.role, text: message.transcript },
        ]);
      }
    });
    return () => {
      vapiInstance.removeAllListeners();
      void vapiInstance.stop();
    };
  }, []);
  const startCall = () => {
    setTranscript([]);
    void vapi?.start('YOUR_ASSISTANT_ID');
  };
  const endCall = () => void vapi?.stop();
  return (
    <div style={{ position: 'fixed', bottom: 24, right: 24, background: '#000', color: '#fff', borderRadius: 12, padding: 20, width: 300 }}>
      {!isConnected ? (
        <button onClick={startCall} style={{ background: '#12A594', color: '#fff', border: 'none', borderRadius: 8, padding: '12px 24px' }}>
          Start Voice Chat
        </button>
      ) : (
        <div>
          <div style={{ maxHeight: 200, overflowY: 'auto', marginBottom: 16 }}>
            {transcript.map((message, index) => (
              <div key={index} style={{ marginBottom: 8, textAlign: message.role === 'user' ? 'right' : 'left' }}>
                <span style={{ background: message.role === 'user' ? '#12A594' : '#333', padding: '8px 12px', borderRadius: 12, display: 'inline-block' }}>
                  {message.text}
                </span>
              </div>
            ))}
          </div>
          <button onClick={endCall} style={{ background: '#e5e7eb', color: '#000', border: 'none', borderRadius: 8, padding: '8px 16px' }}>
            End Call
          </button>
        </div>
      )}
    </div>
  );
}

For a complete implementation with waveform visualization, real-time transcripts, and responsive design, check out our voice widget component on GitHub.

7

Review calls and improve your prompts

After a call ends, review its transcript, messages, and tool activity. Look for the questions users ask, how the assistant searches the index, and where its answers need improvement.

  1. Navigate to Observe > Logs, then select Calls.
  2. Select a completed call to view its details.
  3. Review the transcript, messages, and tool activity.
  4. Use insights to improve your assistant’s prompts and responses.

Review several calls before drawing conclusions. Update the system prompt when the same misunderstanding appears repeatedly. Refine the docsquery description or request schema when the assistant searches with incomplete or irrelevant queries. For automated summaries and evaluations, configure structured outputs.

Prompting guide

Learn advanced prompting techniques to optimize your documentation agent’s responses and behavior.