Skip to main content
A reference is a link to something your agent can use, placed directly in a sentence of your instructions. Instead of writing the name of a tool and hoping the agent matches it up, you point at the real thing. References remove a whole category of small errors. A typo in a tool name, a tool that was renamed last week, two playbooks with similar names - none of those trip up an agent reading a reference, because the reference points at the resource itself rather than at whatever you typed. You can reference tools, system tools, playbooks, and workflows anywhere the editor appears: the global prompt, your agent instructions, and inside any playbook.

​
Adding a reference

1

Open the insert menu

Type / where you want the reference to appear. The menu opens with a Reference section listing Tools, System tools, Playbooks, and Workflows.Editor Reference Menu DocsA category with nothing in it appears greyed out and can’t be selected.
2

Pick a category

Select the category you want. The menu opens a searchable list of everything available in that category.Editor Reference Tools Docs
3

Search and select

Start typing to narrow the list, then press Enter or click to insert. The reference appears inline as a small chip showing the resource name and its icon.
You can also filter from the top level. Typing part of a category name after the slash, such as /work, narrows the menu down to Workflows, and pressing Enter opens it.
Adding a reference attaches that resource to your agent automatically, so there is no separate step to make it available. Playbooks and workflows are attached at the agent level, meaning they become reachable from anywhere in the agent.

​
What you can reference

Tools of every kind are grouped into one searchable list, so you don’t need to remember whether something was built as an API tool or a function.

​
Creating tools before you reference them

The reference menu selects from what already exists. It does not create anything. If the tool, playbook, or workflow you want isn’t in the list, create it first, then come back to your instructions and reference it. Once it exists, it appears in the menu straight away.

API tool

Connect to any REST API with a custom request.

Function tool

Run custom JavaScript logic mid-conversation.

MCP tool

Connect an MCP server and expose its tools.

Integrations

Pre-built connectors for Zendesk, Salesforce, Shopify, and more.
Playbooks and workflows work the same way. Create them from the Agent tab, from a playbook step or workflow step, or from the Playbooks and Workflows tabs in the sidebar.
Variables and secrets are the exception. Those can be created inline while you write, without leaving the editor.

​
Referencing system tools

System tools are built into Voiceflow and need no setup. Which ones appear in the menu depends on your agent, since some are specific to chat or voice:
  • Knowledge base - search your knowledge base for an answer
  • Buttons - offer clickable options instead of asking the user to type
  • Cards - show a rich card with a title, description, and image
  • Carousels - show several cards in a scrollable row
  • Call forward - transfer the call to a phone number or SIP address
  • Web search - look up current information on the web
  • Skip turn - stay quiet and wait rather than replying
  • End - close the conversation
Referencing a system tool is useful when you want to be specific about ordering. For a full description of each tool and how to configure its trigger, see system tools. In the editor a reference shows as a chip with the tool’s name. Read as plain text, the same instructions look like this:
Example
You don’t need to type these. Insert them with / and the editor writes the right one for you.

​
Editing and removing a reference

Click any reference to open its menu. Editor Reference Edit Docs From here you can:
  • Swap it for a different resource by picking another from the list, which replaces the chip in place
  • Open it by hovering the row and clicking Edit, which takes you to that tool, playbook, or workflow
  • Remove it by pressing Backspace or Delete
Renaming a resource elsewhere updates every reference to it automatically, so there is nothing to go back and fix.

​
When a reference goes missing

If a reference turns into a Missing reference warning, the resource it pointed at is no longer available to this agent. That usually means it was deleted, or it was removed from the agent’s tools. Editor Missing Reference Docs The warning is safe to leave while you sort it out, and clicking it opens the same menu so you can point it somewhere else or remove it. Variables and secrets behave the same way, showing Missing variable or Missing secret. Fix a missing reference by either recreating the resource, or selecting a replacement from the menu.

​
Referencing variables and secrets

Type { to insert a variable or a secret. The menu has a tab for each, a search field, and a Create variable button if the one you need doesn’t exist yet. Editor Variable Menu Docs Variables appear as coloured chips and are replaced with their live value when the agent runs, so {customer_name} in your instructions becomes the customer’s actual name in the conversation.
A few built-in variables are greyed out and can’t be inserted into a prompt, including vf_now, vf_time, last_utterance, and vf_memory. Their values change on every turn, which prevents the model from reusing its cache and makes your agent slower and more expensive.
Copying instructions into a plain text document writes each reference out in its @type:id form, and each variable as {name}. Pasting that text back into the editor turns them into working references again, so you can move instructions between agents without rebuilding them by hand.

​
Next steps

Markdown shortcuts

Format as you type, and paste markdown from anywhere.

Keyboard shortcuts

Every shortcut for formatting, blocks, and menus.