Persona & Prompt Engineering

Agents introduces personaPrompt as the agent’s identity, tone, and behavioral guardrails, kept deliberately separate from the step-by-step logic that lives in the workflow graph. That’s the right one-paragraph summary, but “write a good prompt” is really three different writing jobs depending on where the text runs:

1. A customer-facing persona — the personaPrompt on an agent that talks directly to an end user.
2. A voice-facing persona — the same field, but for an agent whose output is spoken aloud, where the platform already does some of the work for you.
3. A narrow-task prompt inside a workflow llm node — classification, intent detection, value extraction — which isn’t a persona at all and needs to be written like one.

Conflating these is the most common way a prompt underperforms. This page treats each separately.

1. Writing a customer-facing persona prompt

personaPrompt should answer four questions, and nothing more:

• Who is the agent? A name, a role, a domain.
• What tone does it use? Formal, warm, terse, playful — pick one and state it.
• What is it explicitly not for? Scope boundaries keep the agent from improvising answers to questions it has no business answering.
• What does it do when it doesn’t know? Every persona needs an explicit fallback instruction, or the model will guess rather than admit uncertainty.

Everything else — how many questions to ask, when to escalate, what tool to call — belongs in the workflow graph, not here. A persona prompt that tries to encode branching logic in prose is fighting the architecture: the model has to re-derive “where am I in the conversation” from raw text on every turn, instead of the graph simply routing there.

Weak vs. strong

Weak:

You are a helpful assistant. Answer questions about our library.

This has no tone, no boundary, and no fallback. It will confidently answer questions about topics the library has no data on, in whatever tone the model defaults to, which will drift across sessions.

Strong:

You are a friendly, knowledgeable library assistant. You help users find
books, check room availability, and navigate library services. Always be
concise. If you don't know, say so.

This is the actual example from Agents. It names the role, sets a tone (“friendly,” “concise”), scopes the domain (books, rooms, library services), and gives an explicit fallback (“if you don’t know, say so”). It says nothing about how many turns a conversation takes or what happens after — that’s the workflow’s job.

The HR screening agent recipe follows the same shape for a different domain — identity, tone, and a soft boundary — but deliberately leaves out how many questions to ask or when to close, since that’s driven by a turnCount-keyed condition node in the workflow, not the prompt. Whenever you’re tempted to add “and after 4 questions, wrap up” to a persona prompt, that’s usually a sign the logic belongs in a condition node instead.

2. Writing a persona for a voice-facing agent

If your agent is ever going to run through the voice/avatar integration path, there’s a real mechanic worth knowing before you write the prompt: the platform automatically appends spoken-medium formatting rules to your persona prompt for every voice turn. This isn’t a suggestion in a best-practices doc — it’s a wrapper the session layer applies on every LLM call in the voice path, appended after your personaPrompt text: keep replies to 1–3 sentences, ask one question at a time and then stop and wait, never use bullet points, numbered lists, or markdown, and speak the way a person would on a phone call.

The practical consequence: don’t duplicate this in your own personaPrompt. Writing “keep your responses short, no lists, one question at a time” into the persona itself is redundant for a voice agent — the platform already enforces it on the voice path, appended after whatever identity/tone text you write. Your persona prompt’s job stays the same as in section 1: identity, tone, scope, and fallback behavior. Let the platform own spoken-medium formatting.

Two things follow from this: a persona written purely around identity/tone/scope works fine for an agent used in both a text and a voice integration (see the maturity ladder in Core API Flow), since the voice-specific constraints only apply on the voice path. And this wrapper only covers the top-level conversational turn — it has no effect on workflow llm nodes. To format one specific node’s output for speech (a confirmation feeding a voice-facing response node, say), that’s a per-node decision, not a persona one — see applyVoiceFormatting on the LLM Node reference. Never set that flag on a node feeding a condition or router.

3. Writing a prompt for a narrow-task node

Everything above is about a persona that talks to an end user. A workflow llm node used for classification, intent routing, or extracting one specific value from free text is a different writing job entirely — it isn’t a persona, and writing it like one is a common source of unreliable workflows.

The failure mode is real and well-documented: a narrow-task node — say, one whose entire job is “extract this one value and output nothing else” — can drift into answering what the surrounding conversation is about instead of doing its own instruction, especially with small or fast models. A node meant only to extract an identifier from a message can instead generate a full reply confirming an action, because the conversation around it is thematically about that action and the model slips into acting as the assistant handling it, rather than as the narrow pipeline step it’s actually configured to be. This gets more likely, not less, the more conversational the surrounding context is — an instruction like “respond with ONLY the number” is competing against the model’s default instinct to be a helpful conversational partner.

The fix is explicit negative framing, not a longer positive instruction. Tell the model plainly:

• It is not talking to the end user.
• It must not generate a reply, confirmation, or any commentary of its own — a separate node handles that.
• It should output only the requested value, in the exact format needed downstream.

This pattern, and a full worked prompt example, is covered in depth in Workflow Design Best Practices → LLM nodes: extraction vs. conversation — read that section before writing any classification or extraction node. It’s worth calling out here specifically because it’s easy to reuse persona-writing instincts (“be warm, be helpful”) on a task node by accident, when the correct instinct for a task node is closer to the opposite: be terse, be mechanical, and explicitly disclaim any conversational role.

Prompt wording alone is also inherently probabilistic — hardening the instruction measurably reduces drift but doesn’t structurally guarantee it never happens, particularly with small/fast models. Where the downstream consumer is a system that needs a clean value (a tool call argument, a routing key), pair a hardened prompt with a structural safeguard rather than relying on wording alone. For matching a human-given value to an internal numeric ID, extractFirstInteger on the LLM Node config regex-extracts the first integer from the raw response instead of trusting the model to emit only digits — a fix that survives an off-task reply instead of depending on the prompt preventing one.

Which mode am I in?

A quick way to tell which of the three sections applies to the text you’re about to write:

You’re writing…	Use section	Key instinct
The personaPrompt field on an agent, text-only integration	1	Identity, tone, scope, fallback — nothing else
The personaPrompt field on an agent used in a voice/avatar integration	2	Same as above; skip spoken-format instructions, the platform adds them
An llm node’s promptTemplate feeding a condition, router, or a downstream tool call	3	Terse, mechanical, explicit “you are not the assistant” framing
An llm node’s promptTemplate feeding a response node the user will read or hear	Mostly 1, plus applyVoiceFormatting if the response is spoken	Conversational, matches the persona’s tone

Next steps

• Agents — the full personaPrompt and useCase field reference.
• Workflow Design Best Practices — templating rules and the full extraction-vs-conversation prompt pattern.
• LLM Node — applyVoiceFormatting and extractFirstInteger config reference.
• Cookbook Overview — complete worked examples, including the interview-agent persona referenced above.