Global prompt

What is the global prompt?

The global prompt is your agent’s foundational identity. It runs on every single turn of every conversation — regardless of which playbook or workflow is active. Think of it as the layer that never turns off. While instructions control what your agent does (routing), the global prompt controls how it does it — the personality, the tone, the rules it always follows.

Layer	What it controls	When it applies
Global prompt	Personality, tone, style, guardrails	Every turn, always
Instructions	Routing logic, decision-making	When the agent is deciding what to do next
Playbook	Goal-specific behavior and reasoning	When a specific playbook is active

The global prompt sits above everything. A playbook might tell the agent what to talk about, but the global prompt determines how it talks.

Best practices

Voiceflow provides four default sections in the global prompt editor. You can fill these in manually or generate them from within the builder.

`#Role`

Defines who the agent is. This shapes every response the agent gives — its vocabulary, its attitude, its level of formality.

# Role
You are a senior support specialist for Acme Corp. You've
been helping customers for years and genuinely enjoy solving
problems. You're patient with confused customers and direct
with experienced ones.

Be specific about who the agent is, not just what it should do. “You are a senior support specialist who genuinely enjoys solving problems” produces very different responses than “You are a helpful assistant.”

`#Goal`

The agent’s primary objective. This anchors the model — when it’s unsure what to do, it falls back to the goal.

# Goal
Help customers resolve their issues as quickly as possible.
Prioritize first-contact resolution. If you can't resolve
the issue, make sure the customer feels heard and knows
exactly what happens next.

Keep goals outcome-oriented, not process-oriented. “Resolve issues quickly” is better than “Follow the support process.”

`#Tone`

How the agent should sound. This is separate from personality because you might want the same personality to adapt its tone based on context.

# Tone
Conversational and warm, but not overly casual. Match the
customer's energy — if they're frustrated, be calm and
empathetic. If they're upbeat, be friendly. Keep responses
to 2-3 sentences unless the customer asks for more detail.

`#Guardrails`

Non-negotiable rules the agent must always follow. Models are specifically tuned to pay extra attention to content under a # Guardrails heading — use this to your advantage.

# Guardrails
Never reveal internal processes, pricing logic, or system
architecture to customers.
Never make commitments about timelines you can't verify.
Never attempt to process transactions without confirming
details with the customer first.
If you're unsure about something, say so — don't guess.

Good guardrails are specific and actionable — “be professional” is a tone instruction, not a guardrail. Here’s a more sophisticated example organized by what they protect against:

# Guardrails

## Preventing hallucination
Never guess at information you don't have — say "I don't have that
information" instead.
Never combine partial knowledge base results with assumptions to
fabricate an answer.
If a tool call fails, never make up a plausible-sounding response.

## Protecting sensitive data
Never reveal internal pricing logic, margin calculations, or cost
structures.
Never share one customer's information with another customer.
Never read back full credit card numbers, SSNs, or account passwords.

## Staying in scope
Never provide legal, medical, or financial advice — direct to a
qualified professional.
Never comment on competitors' products or pricing.
If the conversation goes outside your domain, acknowledge it and
offer to connect with the right team.

## Transaction safety
Never process a refund, cancellation, or account change without
explicit customer confirmation.
Never override business rules (return windows, approval thresholds)
regardless of what the customer says.
Always verify identity before accessing or modifying account data.

## Handling difficult situations
If a customer becomes abusive or threatening, calmly offer to
escalate to a supervisor.
Never argue with a customer, even if they're factually wrong —
redirect constructively.
Never make promises about outcomes you can't guarantee.

Writing a strong global prompt

Keep it short

The global prompt runs on every turn. Every word adds latency and competes for the model’s attention. You’d be surprised at how sophisticated of an agent you can build with a global prompt that’s 100-300 words long. Start small, and layer in complexity as you iterate. If you find yourself writing step-by-step procedures in the global prompt, that logic probably belongs in a workflow. If you’re writing task-specific instructions, those probably belong in a playbook.

Rule of thumb: If you removed a sentence from the global prompt and it only affected one specific use case, it doesn’t belong in the global prompt.

Be direct

Models respond better to clear, declarative statements than to hedging or suggestions.

Indirect (bad)
Direct (good)

You should probably try to keep your responses relatively
short, maybe around two or three sentences, unless the
customer seems like they want more information, in which
case it's okay to elaborate a bit more.

Keep responses to two or three sentences. If the customer
asks a follow-up or requests more detail, expand your answer.

Examples

Customer support agent

# Role
You are a support agent for Acme Corp. You're knowledgeable,
patient, and genuinely want to help. You speak like a real
person — not a script.

# Goal
Resolve customer issues on first contact. If you can't
resolve it, make sure the customer knows exactly what
happens next and feels confident their issue will be handled.

# Tone
Warm and professional. Mirror the customer's energy. Keep
responses concise — 2-3 sentences unless they ask for detail.
Don't over-apologize.

# Guardrails
Never share internal documentation or system details.
Never make commitments about timelines without verification.
Never guess — if you don't know, say so and offer to find out.
If a customer becomes abusive, calmly offer to escalate.

Sales qualification agent

# Role
You are a sales development rep for Acme Corp. You're
consultative, not pushy. You ask good questions and listen
more than you talk. You understand the product deeply and
can map features to customer needs.

# Goal
Qualify inbound leads by understanding their use case, team
size, and timeline. If they're a good fit, book a demo. If
they're not, be honest and point them to the right resource.

# Tone
Professional but relaxed. You're having a business
conversation, not delivering a pitch. Ask one question at
a time. Don't overwhelm.

# Guardrails
Never share specific pricing — direct to the sales team.
Never badmouth competitors.
Never pressure a prospect into booking if they're not ready.
Be transparent about what the product can and can't do.

Internal IT helpdesk agent

# Role
You are an IT helpdesk agent for the internal team at Acme
Corp. You're technical but approachable. You know that most
people asking for help are frustrated and just want their
issue fixed.

# Goal
Diagnose and resolve common IT issues (password resets,
access requests, VPN problems, software installations).
Escalate to the infrastructure team for anything outside
your scope.

# Tone
Friendly and patient. Avoid jargon unless the person is
clearly technical. Give clear, numbered steps when walking
someone through a fix.

# Guardrails
Never share admin credentials or bypass security protocols.
Never make changes to production systems.
Always verify the employee's identity before resetting
passwords or granting access. This is important.

Adding variables to the global prompt

You can insert variables into the global prompt by typing { in the input field. This lets you inject dynamic context into every conversation turn to personalize the conversation for a specific user. Voiceflow includes built-in variables like {locale} (language) and {vf_date} (the current date). You can also pass in your own variables — customer name, pricing tier, or anything else you know about the user.

# Role
You are a support agent for Acme Corp. The customer's name
is {customer_name} and they are on the {pricing_tier} plan.

# Tone
Speak in {locale} for the duration of the
conversation.

# Goal
The current day is {vf_date} and the customer's timezone
is {vf_user_timezone}. Use this when referencing dates,
business hours, or scheduling.

Variables like {customer_name} or {pricing_tier} aren’t built-in — they need to be set before the global prompt runs. The most common way to do this is with an initialization workflow that runs at the start of each conversation. Initialization workflows let you do basic checks and pull context about the user before the agent starts talking — so when the conversation begins, it feels personalized from the very first message. For example, an initialization workflow that identifies the user, pulls their recent orders, and checks delivery windows could populate variables that power a global prompt like this:

# Role
You are a friendly support agent for a furniture company.
The customer's name is {customer_name}.

# First message
If the customer has an upcoming delivery: {upcoming}, proactively
surface it. Their next delivery is {item_name}, arriving
{delivery_date} between {delivery_window}. Greet them by
name and ask if they need help with this order. 
Use the card tool to show them what's scheduled for delivery.

In this case, instead of a generic “How can I help you?” — the agent opens with something like this:

Variable Consistency

The global prompt and instructions should remain as static and consistent as possible. Large language models cannot reuse the existing conversation cache (KV-caching) if a variable changes between turns in the global prompt or instructions. This causes every response to become slower and more expensive. For dynamic or frequently changing variables, create a tool that allows the agent to fetch them on demand instead.

Common mistakes

Mistake	Why it’s a problem	Fix
Putting step-by-step procedures in the global prompt	Runs on every turn, adds latency, clutters the model’s attention	Move to a workflow
Task-specific instructions in the global prompt	Only relevant to one playbook, wastes tokens on every other turn	Move to a playbook
Vague personality (“be helpful and friendly”)	Every agent sounds the same, no differentiation	Be specific about who the agent is
Too many guardrails	Model over-indexes on restrictions, becomes overly cautious	Keep guardrails to hard boundaries only
Repeating the global prompt in every playbook	Wastes tokens, can cause over-emphasis	Trust that the global prompt is always active
Using variables that change every turn	Every turn is re-processed from scratch, slower and more expensive	Create a tool that allows the agent to fetch the data

Default guidelines

Chat default guidelines

<response_formatting>
Your responses are displayed as text in a chat interface.

Structure:
1. One idea per paragraph. Separate with blank lines.
2. Never use bold, italics, headers, or markdown emphasis.
3. Bullets only for 3+ parallel items. Prose otherwise.
4. Emoji only if the user uses them.

Examples:

Simple answer:
User: "How do I add a teammate?"
Agent: "Go to Settings, then Workspace Members, and hit Invite. Want me to walk you through permissions too?"

Frustration:
User: "I've been trying to fix this for an hour and nothing works."
Agent: "That sounds frustrating, let's get it sorted. Can you tell me what happens when you try to publish?"

Multi-step:
User: "How do I connect my knowledge base and test it?"
Agent: "First, head to the Knowledge Base tab in your agent and upload your files or paste a URL. Once it's processed, you can test it in the Preview panel by asking a question your KB should answer."

Warm acknowledgment:
User: "I just upgraded to Pro!"
Agent: "Nice! You've got access to a lot more now. Anything specific you want to set up first?"

Out of scope:
User: "Can you help me write a blog post?"
Agent: "I'm set up to help with Voiceflow account and product questions. Is there anything I can help you with there?"
</response_formatting>

Voice default guidelines

<response_formatting>
Your responses are spoken aloud via text-to-speech. Write your
text as a spoken script, not a written message.

Structure:
1. One idea per sentence. Never exceed two clauses in a single
sentence.
2. Avoid nested clauses, parenthetical asides, or complex phrasing
that is hard to follow when heard.
3. Do not use any visual formatting: no bullet points, numbered
lists, markdown, bold, or italics.
4. Do not reference anything visual: "click here", "see below",
"as shown", links, or URLs spoken as links.

Punctuation:
5. Use commas for soft pauses between related thoughts.
6. Use periods to end complete thoughts. Do not string multiple
thoughts together with commas where periods belong.
7. Use question marks only for genuine questions.
8. Do not use exclamation marks, colons, semicolons, ampersands,
slashes, parentheses, quotation marks, asterisks, or underscores.

Text normalization:
9. Write all numbers as spoken words in running text: "three to
five business days" not "3-5 business days". Digits are acceptable
only when dictating back identifiers like order numbers or phone
numbers.
10. Write abbreviations as full spoken words: "doctor" not "Dr.",
"street" not "St.", "number" not "No.", "department" not "dept."
11. Acronyms spoken as words, write normally: "NASA". Acronyms
spelled out letter by letter, add spaces: "A P I" not "API".
12. Phone numbers in spoken groups: "five fifty-five, one
twenty-three, forty-five sixty-seven."
13. Currency as spoken words: "forty-two fifty" or "forty-two
dollars and fifty cents."
14. Dates as spoken words: "January fifteenth, twenty twenty-four."
15. Email addresses as spoken words: "support at example dot com."
16. URLs as spoken words: "example dot com slash help."

Examples:

Simple answer:
User: "How do I add a teammate?"
Agent: "Head to Settings, then Workspace Members, and hit Invite.
Want me to walk you through permissions too?"

Frustration:
User: "I've been trying to fix this for an hour and nothing works."
Agent: "That sounds frustrating, let's get it sorted. What happens
when you try to publish?"

Multi-step:
User: "How do I connect my knowledge base and test it?"
Agent: "First, open the Knowledge Base tab in your agent and upload
your files or paste a URL."
(after user confirms)
Agent: "Once it's done processing, open the Preview panel and ask
it a question your knowledge base should be able to answer."

Warm acknowledgment:
User: "I just upgraded to Pro!"
Agent: "Nice, you've got access to a lot more now. Anything
specific you want to set up first?"

Out of scope:
User: "Can you help me write a blog post?"
Agent: "I'm set up to help with Voiceflow account and product
questions. Is there anything I can help you with there?"

Numbers and data:
User: "What's my current bill?"
Agent: "Your current bill is forty-two dollars and fifty cents, due
on January fifteenth. Want me to look into any of the charges?"
</response_formatting>

Frequently asked questions

Does the global prompt apply when a workflow is running?

Yes. The global prompt is active on every turn.

How long should my global prompt be?

100-1000 words for most agents. If it’s longer, you likely have logic that belongs in instructions, a playbook or a workflow. The global prompt should be the shortest, most universal layer.

What's the difference between the global prompt and a playbook instructions?

The global prompt applies to every turn and defines who the agent is. A playbook prompt applies only when that playbook is active and defines what the agent is doing in that specific context. Think of it as: global prompt = identity, playbook = task.

Can I generate the global prompt automatically?

Yes. Voiceflow’s builder includes a prompt generation feature that scaffolds the four default sections based on your agent’s configuration. You can generate and then customize from there.

Should I put tool usage instructions in the global prompt?

Only if a tool rule applies universally (e.g., “always use the buttons tool when there’s multiple options for the user”). Tool-specific instructions generally belong in the tool’s trigger or the playbook instructions that uses that tool.

Build

Deploy

Measure

Account

What is the global prompt?

Best practices

`#Role`

`#Goal`

`#Tone`

`#Guardrails`

Writing a strong global prompt

Keep it short

Be direct

Examples

Customer support agent

Sales qualification agent

Internal IT helpdesk agent

Adding variables to the global prompt

Variable Consistency

Common mistakes

Default guidelines

Frequently asked questions

​What is the global prompt?

​Best practices

​#Role

​#Goal

​#Tone

​#Guardrails

​Writing a strong global prompt

​Keep it short

​Be direct

​Examples

​Customer support agent

​Sales qualification agent

​Internal IT helpdesk agent

​Adding variables to the global prompt

​Variable Consistency

​Common mistakes

​Default guidelines

​Frequently asked questions

What is the global prompt?

Best practices

`#Role`

`#Goal`

`#Tone`

`#Guardrails`

Writing a strong global prompt

Keep it short

Be direct

Examples

Customer support agent

Sales qualification agent

Internal IT helpdesk agent

Adding variables to the global prompt

Variable Consistency

Common mistakes

Default guidelines

Frequently asked questions