diff --git a/docs/voice-agent/agent.mdx b/docs/voice-agent/agent.mdx index e017e35a..40bbb753 100644 --- a/docs/voice-agent/agent.mdx +++ b/docs/voice-agent/agent.mdx @@ -3,4 +3,111 @@ title: "Agent Node" description: "Agent node contains the prompts that drives the conversation with the Voice Agent" --- -The Edges connected with Agent Nodes are pathways that the LLMs can take depending on how the conversation has been going so far. +## Video Tutorial + + + +Agent Node is the core building block of every Dograh workflow. It holds the LLM prompt that drives the conversation, any tools the agent can call, and knowledge base documents to reference. You can have multiple Agent Nodes in a single workflow, each handling a distinct phase of the conversation. + +The Edges connected with Agent Nodes are pathways that the LLMs can take depending on how the conversation has been going so far. + +## What goes in an Agent Node + +**Prompt** + +The instructions for how the agent should behave at this step. Be explicit about sequence: if the agent should confirm identity before discussing payment, say so in the prompt. Vague prompts produce inconsistent behavior. + +**Tools** + +External functions the agent can call during this step - for example, looking up account balances or updating a CRM record. Add tools via the "HTTP & Tools" or "MCP" tabs in the node settings panel. + +**Allow Interruption** + +When on, the caller can interrupt the agent mid-utterance. + +**Add Global Prompt** + +When on and a Global Node exists, the Global Prompt is prepended to this node's Prompt at runtime. On by default. + +**Knowledge Base Documents** + +Files the agent can reference when answering questions - product guides, FAQs, policies. Attach them via the "Manage Documents" button in the node settings panel. + +## Configuring edges + +Each outgoing edge has a condition written in plain language. The LLM evaluates the conversation and picks the edge whose condition best matches. + +Write edge conditions as specifically as possible: + +| Vague (avoid) | Specific (use) | +|---------------|----------------| +| "Debtor responds" | "Debtor confirms their identity and is ready to discuss the account" | +| "Call ends" | "Debtor commits to a specific payment option and states the amount" | +| "Problem" | "Debtor disputes owing the debt or requests validation documentation" | + + +If the agent keeps routing to the wrong edge, make the condition more specific. Conditions like "user responds" or "conversation ends" are too broad and will route unpredictably. + + +## Extracting variables + +Agent Node can extract structured data from the conversation after the node completes. Enable this in the node settings under "Enable Variable Extraction." + +Once enabled, configure two things: + +- **Extraction Prompt:** overall instructions telling the LLM how to approach the extraction. +- **Variables to Extract:** a list of variables, each with a name, a data type (`string`, `number`, `boolean`), and a per-variable hint describing what to capture. + +For example: + +```text +Extraction Prompt: +Extract the payment outcome from this debt collection call. + +Variables: +- amount_user_will_pay (string): Amount the user said they will pay. +- payment_method (string): How they said they will pay, e.g. card, bank transfer. +- sentiment (string): User tone: cooperative, hesitant, angry, refused. +``` + +Each extracted value is stored in `gathered_context`. It is not available in any node's Prompt - reference it in [Webhook node](./webhook) payloads as `{{gathered_context.variable_name}}`, or read it from the run record after the call completes. + +## Using multiple Agent Nodes + +Break complex conversations into phases. Each Agent Node handles one part of the flow. A debt collection workflow, for example, might chain three Agent Nodes: identity verification, offer presentation, and objection handling. + +Nodes pass context forward automatically, but not into prompts. Variables extracted in one node are stored in `gathered_context` and merged with variables from later nodes as the call progresses. `gathered_context` is not available in any node's Prompt - it can only be referenced in [Webhook node](./webhook) payloads and in the run record after the call completes. If a later Agent Node needs to react to something extracted earlier, that logic has to live in the prompt's own instructions, not in a `{{gathered_context...}}` reference. + +## Common mistakes + +**No outgoing edges.** Every Agent Node needs at least one edge. A dead-end node has no exit path and will trap the call. + +**Putting global instructions in the Agent prompt.** Rules that apply across the entire workflow - persona, tone, compliance guardrails - belong in the [Global Node](./global), not repeated in every Agent Node. + +**Vague edge conditions.** The LLM picks the edge that best matches the conversation state. Overly broad conditions cause unpredictable routing between nodes. + +## Next Steps + + + + Terminate the conversation with a closing message. + + + Write shared instructions that apply to every node. + + + Understand how `gathered_context` is built and where it can be referenced. + + + Evaluate agent performance automatically after each call. + + diff --git a/docs/voice-agent/end-call.mdx b/docs/voice-agent/end-call.mdx index b3332afd..4b73c150 100644 --- a/docs/voice-agent/end-call.mdx +++ b/docs/voice-agent/end-call.mdx @@ -2,6 +2,82 @@ title: "End Call" description: "You can use End Call node to configure how the Agent says its final message right before the call is terminated" --- - -You should have only one End Call node per Voice Agent. - \ No newline at end of file + +## Video Tutorial + + + +End Call is the terminal node in a workflow. It fires right before Dograh terminates the connection, giving your agent one last chance to speak. Every path through your workflow must eventually reach an End Call node. + +## When it runs + +End Call executes after all conversation logic is complete. The agent delivers its closing message, then the call drops. + +You can have multiple End Call nodes in one workflow, each reached by a different edge condition. For example, one for a successful outcome and one for a wrong-number path. Each can have its own distinct Prompt. + +## Fields + +**Name** + +Short identifier shown in the canvas and call logs. Use names that describe the ending context, for example "Successful close" or "Polite decline". + +**Prompt** + +System instructions for what the agent says before the call ends. You can make this conditional by describing different outcomes in the prompt. + +For example: + +```text +If the caller committed to a payment, confirm the arrangement: the +exact amount and expected processing time. If no commitment was made, +thank them for their time and let them know they can call back to +discuss options. Always close professionally. +``` + +The Prompt cannot reference `gathered_context` - variables extracted by this or earlier nodes are not available in any node's Prompt. To act on extracted data, send it out via a [Webhook node](./webhook) instead. + +**Add Global Prompt** + +When on and a Global Node exists, the Global Prompt is prepended to this node's Prompt at runtime. On by default. + +**Enable Variable Extraction** + +When on, an LLM extraction pass runs after this node's turn to capture structured data from the conversation into `gathered_context`. + +## Common mistakes + +**Leaving the Prompt empty.** An empty Prompt means the agent says nothing before the line drops. The caller experiences an abrupt silence. + +**Routing all paths into one End Call when outcomes need different closing lines.** Multiple End Call nodes are supported. If a wrong-number path and a successful-commitment path need different closing lines, use two End Call nodes with distinct Prompts rather than cramming both into one. + +**Agent Nodes that never route to End Call.** Any node without a downstream path to End Call leaves calls in an unresolvable state. + + +Check every Agent Node for a path to End Call before publishing. Nodes with no downstream connection to End Call will drop the call without a closing message. + + +## Next Steps + + + + Automatically evaluate calls after they end. + + + Sync call outcomes to your CRM or external systems. + + + Configure the conversation logic that routes into End Call. + + + Learn where `gathered_context` can and cannot be referenced. + + diff --git a/docs/voice-agent/global.mdx b/docs/voice-agent/global.mdx index 978ac1cf..18e7be54 100644 --- a/docs/voice-agent/global.mdx +++ b/docs/voice-agent/global.mdx @@ -1,12 +1,69 @@ --- title: "Global Node" -description: "Global Node contain the common prompt that is appended to the prompt of every node, in which `Add Global Prompt` is turned on." +description: "Global Node contains the common prompt that is prepended to the prompt of every node, in which `Add Global Prompt` is turned on." --- +## Video Tutorial + + + You should have only one Global node per Voice Agent. ![Add Global Prompt Selector](../images/global-node.png) -This node typically contains common instructions, that the Voice Agent should always follow, like tone of the conversation, any objection handling etc. +Global Node is a shared prompt layer for your entire workflow. Write your agent's persona, tone guidelines, and compliance rules once in the **Global Prompt** field. Any Agent Node or Start Call node with "Add Global Prompt" turned on will receive this content prepended to its own prompt before each LLM call. + +## What goes in the Global Node + +Use Global Node for instructions that apply across every step of the conversation: + +- **Persona:** Who is the agent? What company do they represent? +- **Tone rules:** How formal or warm should they be? +- **Compliance guardrails:** What must the agent never say? +- **Objection handling:** How should the agent respond to pushback? + +Avoid putting step-specific logic here. Instructions like "offer the settlement option after the debtor confirms their identity" belong in the Agent Node prompt, not in Global. + +## How it works + +Global Node does not run as a separate step in the call. It has no edges and cannot be connected to other nodes. The Global Prompt is silently prepended to each node's prompt where "Add Global Prompt" is enabled. + +The LLM sees one combined prompt: the global content first, followed by the node-specific instructions. The caller never notices the seam. + +## Enabling it on an Agent Node + +Each Agent Node and Start Call node has an "Add Global Prompt" toggle in its settings panel. Nodes with the toggle off receive no global content for that step. + + +Turn the toggle off selectively when a specific node needs different behavior. An escalation node, for example, may need a more formal tone that should not inherit your default persona. + + +## Common mistakes + +**Putting node-specific logic in the Global Node.** Global is for rules that always apply, not for conversation-specific decisions. Sequence and outcome logic belong in each Agent Node prompt. + +**Leaving the Global Node prompt empty with toggles on.** A blank Global Node prepended to every prompt does nothing harmful, but it is also pointless. Either fill it in or leave the toggle off. + +**Adding a second Global Node.** Each workflow supports exactly one. Adding a second throws an error. + +## Next Steps + + + + Configure how your agent opens the conversation. + + + Build the core conversation logic that inherits your global prompt. + + diff --git a/docs/voice-agent/introduction.mdx b/docs/voice-agent/introduction.mdx index bb260534..297a32c0 100644 --- a/docs/voice-agent/introduction.mdx +++ b/docs/voice-agent/introduction.mdx @@ -24,10 +24,10 @@ A workflow should have only one **Start Call** node and typically ends at an **E | --- | --- | | [**Start Call**](/voice-agent/start-call) | Starts the call and configures the agent's greeting. Should have only one per workflow. | | [**Agent**](/voice-agent/agent) | Holds the prompt that drives conversation at a given stage; connects to other nodes via pathways. | -| [**Global**](/voice-agent/global) | Common instructions (tone, objection handling) appended to every node with "Add Global Prompt" enabled. | +| [**Global**](/voice-agent/global) | Common instructions (tone, objection handling) prepended to every node with "Add Global Prompt" enabled. | | [**QA**](/voice-agent/qa) | Runs automated post-call quality analysis against criteria you define. | | [**API Trigger**](/voice-agent/api-trigger) | Exposes an endpoint so external systems (n8n, Zapier, your backend) can start outbound calls. | -| [**End Call**](/voice-agent/end-call) | Configures the agent's final message before the call is terminated. Should have only one per workflow. | +| [**End Call**](/voice-agent/end-call) | Configures the agent's final message before the call is terminated. A workflow can have multiple End Call nodes, each with a distinct Prompt. | | [**Webhook**](/voice-agent/webhook) | Sends call results to an external system (CRM, Zapier, n8n) when a run ends. | Beyond nodes, you can extend an agent with: diff --git a/docs/voice-agent/qa.mdx b/docs/voice-agent/qa.mdx index b43b17be..55d546b1 100644 --- a/docs/voice-agent/qa.mdx +++ b/docs/voice-agent/qa.mdx @@ -3,12 +3,99 @@ title: "QA" description: "QA node allows you to run post-call quality analysis on your Voice Agent runs" --- -The QA node lets you define quality analysis criteria that are automatically evaluated after each call ends. Use it to score agent performance, check compliance, or extract structured insights from conversations. +## Video Tutorial -### Creating a QA Node + -You can add a QA node to your workflow from the Voice Agent Builder. Once added, configure the analysis criteria that you want to evaluate for each call. +The QA node runs an LLM quality review on the call transcript after each conversation ends. Use it to score agent performance, flag compliance issues, and surface patterns across calls, without listening to recordings manually. -### Viewing QA Results +## When it runs + +QA Node runs post-call only. It is not part of the live call flow - it reads the completed transcript after the conversation ends. It has no edges and cannot connect to any other node in the workflow. + +This means QA does not affect call behavior. It only measures it. + +## Where it sits on the canvas + +Add QA Node anywhere on the canvas. It does not need to connect to other nodes - most builders place it off to the side to make clear it is a standalone evaluator. The node runs automatically for every eligible call once the workflow is published. + +## Configuring the System Prompt + +The core configuration is a single **System Prompt**: instructions to the reviewer LLM that describe how to evaluate each call. The LLM reads the transcript and returns a structured JSON result. + +The default prompt already covers common quality dimensions out of the box: + +- **Tags**: named issues detected in the transcript. The default tag set includes `DEAD_AIR`, `USER_FRUSTRATED`, `ASSISTANT_IN_LOOP`, `ASSISTANT_REPLY_IMPROPER`, `USER_NOT_UNDERSTANDING`, `HEARING_ISSUES`, `UNCLEAR_CONVERSATION`, `USER_REQUESTING_FEATURE`, `ASSISTANT_LACKS_EMPATHY`, and `USER_DETECTS_AI` +- **Call quality score**: 1-10 rating +- **Overall sentiment**: positive, neutral, or negative +- **Summary**: 1-2 sentence description of the call segment + +You can replace the default System Prompt with your own instructions when you need domain-specific evaluation. Write the prompt as instructions to the QA reviewer LLM, and specify the JSON structure you want it to return. + +For compliance use cases, for example: + +```text +You are a compliance reviewer for a debt collection workflow. + +Review the transcript and return a JSON object with the following fields: +- "identity_verified": true or false — did the agent confirm the caller's identity before discussing the account? +- "options_presented": true or false — did the agent offer all three payment options before accepting a decision? +- "tone_score": 1-5 — how calm and professional was the agent throughout? +- "summary": one sentence describing the call outcome. +``` + + +Be specific about what counts as a pass or a valid score. Include the exact behaviors you want the LLM to look for. Vague instructions produce inconsistent results across calls. + + +## Additional settings + +| Setting | Default | What it does | +|---------|---------|--------------| +| Enabled | On | Toggle to disable QA without removing the node | +| Use Workflow's LLM | Off | When on, uses the same LLM configured for the workflow instead of the default QA model | +| Minimum Call Duration (seconds) | 15 | Calls shorter than this are skipped | +| Include Voicemail Calls | Off | When off, voicemail calls are skipped | +| Sample Rate (%) | 100 | Run QA on a percentage of calls rather than all of them | + +## Viewing QA Results After a call completes, the QA analysis runs automatically. You can view the results on the **Run Detail** page for each individual run. + +Open a run and scroll to the **QA Analysis** section. The result shows the full JSON output your QA System Prompt requested - tags, scores, sentiment, and summary for the default prompt, or whatever structure you defined. + +## Common mistakes + +**Expecting QA to affect the live call.** QA Node is read-only at runtime. It evaluates what happened; it does not change what happens. + +**Connecting QA Node to other nodes.** QA has no edges. Drawing a connection from QA to another node is not possible - edges will snap back when you try. + +**Writing a vague System Prompt.** "Was the agent good?" produces unhelpful scores. Define specific, observable behaviors and the exact JSON fields you want back. + +**Not specifying output format.** The LLM follows your instructions, but if you do not specify a return format, the output may be inconsistent across calls. Always describe the exact JSON structure in the System Prompt. + +## Next Steps + + + + Configure the conversation logic that QA evaluates. + + + Send call outcomes to external systems after the call ends. + + + Learn how `gathered_context` is built during the call. + + + Configure the final message before the call drops. + + diff --git a/docs/voice-agent/start-call.mdx b/docs/voice-agent/start-call.mdx index 2744e5e9..1f4e6c09 100644 --- a/docs/voice-agent/start-call.mdx +++ b/docs/voice-agent/start-call.mdx @@ -2,6 +2,142 @@ title: "Start Call" description: "You can use Start Call node to Start the call and configure how Agent greets the user when the conversation starts." --- + +## Video Tutorial + + + You should have only one Start Call node per Voice Agent. + +Start Call is the entry point for every conversation. It fires the moment a call connects and controls the first thing your agent says. Every workflow must have exactly one. + +## When it runs + +Start Call executes before any Agent Node. No other node can precede it in the call flow. + +After Start Call completes, the conversation moves to the next node - typically your first Agent Node. If the caller hangs up immediately or reaches a wrong-number condition, Start Call can route directly to End Call instead. + +## Fields + +**Name** + +Short identifier shown in the canvas and call logs. Has no runtime effect on what the agent says. + +**Greeting Type** + +Whether the greeting is spoken via TTS from text or played from a pre-recorded audio file. Defaults to "Text (TTS)". + +**Greeting Text** + +Optional fixed line spoken via TTS the moment the call connects, before the AI's conversational turn begins. Supports `{{template_variables}}`. Leave empty to skip the greeting and let the Prompt handle the opening. + +For example: + +```text +Hi {{initial_context.debtor_name}}, this is Alex from Apex Recovery Solutions. +``` + + +See [Pre-recorded Audio](./pre-recorded-audio) to use a recording file instead of TTS text. + + +**Prompt** (required) + +System instructions for the AI's opening conversational turn. Runs after Greeting Text (if set). Supports `{{initial_context.field_name}}` and variables from Pre-Call Data Fetch. + +For example: + +```text +After greeting the caller, confirm you are speaking with +{{initial_context.debtor_name}}. If they confirm, move to Debt Disclosure. +If they say wrong number, move to End Call. +``` + + +If a variable referenced in Greeting Text or Prompt is missing from the API request payload, the agent speaks the raw placeholder out loud - for example, "Hi `{{initial_context.debtor_name}}`" - instead of the caller's name. Test with a complete payload before publishing. + + +**Allow Interruption** + +When on, the caller can interrupt the agent mid-utterance. Off by default on Start Call. + +**Add Global Prompt** + +When on and a Global Node exists, the Global Prompt is prepended to this node's Prompt at runtime. On by default. + +**Delayed Start** + +When on, the agent waits before speaking after the call connects. Useful for outbound calls where the called party needs a moment to settle. Duration can be set between 0.1 and 10 seconds. + +**Enable Variable Extraction** + +When on, an LLM extraction pass runs after this node's turn to capture structured data from the conversation into `gathered_context`. + +**Tools** + +Functions the agent can call during the opening turn. Add via the "HTTP & Tools" tab (HTTP API and built-in tools) or the "MCP" tab (MCP server tools). + +**Knowledge Base Documents** + +Documents the agent can reference during this step. Attach via "Manage Documents." + +**Pre-Call Data Fetch** + +When on, Dograh makes a POST request to an external API before the call starts and merges the JSON response into the call context as template variables. + +## Outgoing edges + +Start Call can have multiple outgoing edges, each with a user-defined label and a condition written in plain language. The LLM reads the conversation and picks the edge whose condition best matches. + +Each edge needs two things: + +- **Label:** a short name shown on the canvas (you define this) +- **Condition:** the instruction that tells the LLM when to take this edge + +A typical Start Call has two edges: + +```text +Label: "caller confirmed" +Condition: "The caller confirmed they are the right person and are ready to continue." + +Label: "wrong number" +Condition: "The caller says this is the wrong number, asks not to be called, or refuses to confirm their identity." +``` + +You can add more edges if the opening turn needs to branch further. + +## Common mistakes + +**Leaving Greeting Text empty with no Prompt.** If both Greeting Text and Prompt are empty, the agent says nothing at the start of the call. The caller hears silence. + +**Confusing Node Name with the agent's spoken name.** Node Name is a canvas label for your own reference. The name the agent introduces itself as comes from the Greeting Text or Prompt content, or the persona you define in the [Global Node](./global). + +**Adding a second Start Call node.** Each workflow has one entry point. A second Start Call node will throw an error. + +## Next Steps + + + + Build the core conversation logic that follows the greeting. + + + Set persona and tone rules that apply across all nodes. + + + Learn how `initial_context` variables flow through a call. + + + Configure the agent's final message before the call drops. + +