Insert a reference to link an instruction directly to a tool, playbook, or workflow. The reference points to the resource itself, so a renamed tool or a similar name does not depend on a text match.

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.

Resource reference picker in the instructions editor
Insert a resource reference while writing instructions.

A 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.

Tool reference being inserted into instructions
Reference a tool directly where the agent should use it.
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.

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.

Reference popover with editable name and trigger
Open a reference to review or edit the resource it points to.

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.

Missing reference highlighted in the instructions editor
Resolve missing references before running the agent.

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.

Variables and secrets picker in the editor
Insert variables and secrets without typing their names manually.

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

Use the up and down arrow keys to select a result, Enter to open it, and Escape to close the search.