> ## Documentation Index > Fetch the complete documentation index at: https://docs.cogniagent.ai/llms.txt > Use this file to discover all available pages before exploring further. # Prompting best practices > How to write actor system prompts and AI node instructions that produce reliable, on-tone, well-shaped output. Adapted from Anthropic's official prompting guide for Claude. A great flow lives or dies by the prompts you give its actors. The model is capable; the prompt is what tells it *how to be capable at your problem*. This page distils Anthropic's official [Prompting best practices](https://platform.claude.com/docs/en/build-with-claude/prompt-engineering/claude-prompting-best-practices) for Claude Opus 4.7, Sonnet 4.6, and Haiku 4.5, and translates each technique into how you'd apply it inside CogniAgent — actor system prompts, the [Ask AI](/nodes/actions/ask-ai) node, [Call AI Agent](/nodes/actions/call-ai-agent), and step-builder configurations. Most of these techniques are additive — you can mix and match. Start with **Be clear and direct**, **Use examples**, and **Add context**, and reach for the more specialized ones (XML structure, role, prefill replacements, thinking guidance) when the basics don't fully solve your problem. ## The golden rule > **Show your prompt to a colleague with minimal context on the task and ask them to follow it. If they'd be confused, the model will be too.** Think of the model as a brilliant new hire who has no idea about your norms, customer base, edge cases, or internal jargon. The more precisely you explain what you want, the better the result. ## Foundations ### 1. Be clear and direct State exactly what you want. If you want "above and beyond" behavior, *ask for it*. If the order of steps matters, number them. **Less effective:** ```text theme={null} Help users with their support requests. ``` **More effective:** ```text theme={null} You are a support agent for Acme. Your job is to: 1. Greet the user by name if they introduce themselves. 2. Ask one clarifying question if the issue isn't yet specific enough to act on. 3. Resolve the request by either: (a) answering directly from the knowledge base, (b) handing off to a human when the user asks for an agent, or (c) creating a ticket via the `create_ticket` capability if the issue can't be resolved live. 4. End by confirming what you did and asking if there's anything else. ``` This applies to actor system prompts, Ask AI node prompts, and the **Task** field in step-builder definitions. ### 2. Add context to improve performance Telling the model *why* a rule matters lets it generalize sensibly to edge cases you didn't anticipate. **Less effective:** ```text theme={null} NEVER use ellipses. ``` **More effective:** ```text theme={null} This actor's responses are read aloud by a text-to-speech engine in our phone channel, so never use ellipses since the TTS engine won't know how to pronounce them. ``` The second version also covers em-dashes, ASCII art, and other written-only quirks the model will infer are problematic for the same reason. When you write an actor system prompt, briefly tell the model **what channel it lives on** (widget, email, Telegram, phone), **who the user is** (paying customer, internal employee, lead), and **what success looks like** (booked meeting, ticket created, question answered). Three sentences of context outperform three pages of rules. ### 3. Use examples (few-shot prompting) Examples are the most reliable way to steer output format, tone, and structure. A few well-chosen examples often beat a paragraph of instructions. When adding examples to an actor or Ask AI prompt, make them: * **Relevant** — Mirror your real cases, including the awkward ones. * **Diverse** — Cover edge cases. Vary enough that the model doesn't pick up unintended patterns. * **Structured** — Wrap them in `` tags so the model can tell them apart from instructions. ```text theme={null} Here are examples of how to triage an inbound lead message: Hey, do you guys do annual plans? billing_inquiry Yes — our annual plan is 20% off the monthly rate. Want me to walk you through the pricing? I keep getting "401 Unauthorized" when I call /v1/users. technical_support That's almost always an expired API key. Can you check Settings → API Keys and try regenerating? cancel my subscription retention_risk I'm sorry to hear that. Before we cancel, can I ask what's not working for you? ``` Three to five examples is the sweet spot. You can also ask the model itself ("evaluate these examples for diversity") or have it generate new variants from your initial set. ### 4. Structure prompts with XML tags When a prompt mixes instructions, context, examples, and variable inputs, wrap each block in its own XML tag. The model parses these reliably and won't confuse the example tone for an instruction. ```text theme={null} You are a senior account executive at Acme. The user is a free-tier customer who has been on the platform for 14 days. They have not yet invited a teammate. 1. Recommend they invite a teammate to unlock collaboration features. 2. Use a warm, peer-to-peer tone — not a sales pitch. 3. Never make claims about features that aren't in . {{features_csv}} {{conversation_so_far}} ``` Use consistent tag names across the flow's actors so the model can pick up patterns. Nest tags when there's a natural hierarchy (e.g. `` containing ``). ### 5. Give the actor a role Setting a role focuses behavior and tone fast. Even one sentence helps. ```text theme={null} You are a calm, factual technical support agent who specializes in API authentication issues. You explain things in concrete terms and never speculate about features you can't verify. ``` In CogniAgent, the actor's **Name** and **Description** fields combine with the system prompt to set role. Spend a minute on them — they show up in the conversation UI and in handoff messages between actors, so they're not just metadata. ### 6. Long-context prompting For Ask AI, Call AI Agent, or actors that read long documents (20k+ tokens), structure matters: * **Put the long content at the top, queries at the bottom.** Queries placed after the documents can improve quality by up to 30% in Anthropic's tests. * **Wrap each document in `` tags** with `` and `` subtags. * **Ask the model to quote first.** For long-doc tasks, prompt it to extract relevant quotes into `` tags before reasoning. This cuts through noise. ```text theme={null} annual_report_2024.pdf {{ANNUAL_REPORT}} competitor_analysis_q2.xlsx {{COMPETITOR_ANALYSIS}} Find quotes from the documents relevant to Q3 strategy and place them in tags. Then, based on those quotes, recommend three Q3 focus areas in tags. ``` ## Output and formatting ### Control verbosity Claude Opus 4.7 calibrates response length to perceived task complexity. If your channel needs a specific shape, tell it. **To make outputs shorter:** ```text theme={null} Provide concise, focused responses. Skip non-essential context, and keep examples minimal. ``` **To make outputs longer / more thorough:** ```text theme={null} Provide a complete answer with relevant context. If there are multiple aspects to the question, address each one. Don't truncate explanations to be brief. ``` ### Tell the model what *to do*, not what *not to do* This generalizes everywhere. Positive instructions are followed more reliably than negative ones. | Instead of | Try | | -------------------------- | ------------------------------------------------------------------------------------------------------ | | "Do not use markdown" | "Write in flowing prose paragraphs with no bullet points or headings" | | "Don't be overly formal" | "Use a warm, conversational tone, like a teammate explaining over coffee" | | "Avoid hallucinating data" | "Cite the specific knowledge-base article or tool result you used. If you don't have a source, say so" | ### Channel-shaped output CogniAgent already injects channel-aware steering for some surfaces — phone actors get TTS-friendly guidance; Telegram actors get a MarkdownV2 nudge ([Telegram channel](/conversation-flows/channels/telegram)). For other channels, lean on the same pattern: ```text theme={null} This actor replies in our embeddable Web Widget. Keep responses to 1–3 short paragraphs. Markdown is supported (links, bold, italics). Long bulleted lists look cluttered in the widget — use them only when comparing 3+ items. ``` ### Match the prompt style to the desired output style If you write the prompt in dense markdown with deeply nested bullets, the output drifts that way. If you want flowing prose out, write the prompt in flowing prose. ## Tool use, capabilities, and proactive behavior CogniAgent actors get [capabilities](/conversation-flows/build/capabilities) (workflow apps, knowledge bases, hand-off, etc.). The model's decision to *call* a capability vs. just *talk about it* is steerable. ### Be explicit when you want action "Can you suggest some changes?" → the actor suggests. "Make these changes." → the actor acts. For an actor whose job is to *do* things on the user's behalf, set the bar in the system prompt: ```text theme={null} When the user describes a clear intent, complete it using the available capabilities rather than only describing what could be done. If intent is ambiguous, ask one clarifying question and then act. ``` For an actor whose job is to *advise* (compliance, security, financial planning), bias the other way: ```text theme={null} Do not invoke a capability that changes state (book, cancel, send, charge) unless the user has explicitly confirmed they want that action taken. Default to providing information and recommendations until you receive an unambiguous go-ahead. ``` ### Avoid over-aggressive language Older prompts often used `CRITICAL: You MUST always...`. With current models, that can cause *overtriggering* — calling tools or running checks when a simpler answer would do. Normal prompting language ("Use this capability when...") works better. ### Encourage parallel tool calls when independent For research-style actors that may need to consult multiple sources: ```text theme={null} When you need to call multiple capabilities and the calls don't depend on each other's results, invoke them in parallel. For example, when looking up three different KB articles, call all three searches at once. If a call's parameters depend on a previous call's result, run them sequentially. ``` ## Thinking and reasoning Claude's latest models use **adaptive thinking** — they decide when and how much to deliberate. You don't typically configure thinking from a flow prompt, but you can nudge it. ### Ask for self-verification For accuracy-critical actors (medical triage, legal research, code review): ```text theme={null} Before you finalize your answer, verify it against the source material you consulted. If you find a contradiction, revise your answer and note what changed. If you don't have enough source material, ask for it instead of guessing. ``` ### Manual chain-of-thought when thinking is off For lightweight actors running on Haiku 4.5 with no extended thinking: ```text theme={null} For multi-step questions, work through the problem in tags first, then give your final user-facing answer in tags. The reasoning is for you; only the content is shown to the user. ``` The flow's renderer can strip the `` block, leaving only the answer. ### Don't over-prompt reasoning A short, general nudge ("think this through carefully") often beats a prescriptive step-by-step plan. The model's natural reasoning frequently exceeds what a human would script. Avoid filling the system prompt with a 12-step decision tree unless you genuinely need that exact tree. When extended thinking is disabled, Claude Opus 4.5 is sensitive to the literal word "think." If you see weird behavior, swap "think" for "consider," "evaluate," or "reason through." ## Agentic patterns These apply most when you're using [Call AI Agent](/nodes/actions/call-ai-agent) inside a workflow, or when an actor runs many turns autonomously. ### State tracking and incremental progress For long-running agentic tasks, ask the actor to keep structured state and emphasize *incremental* progress over heroic one-shot attempts: ```text theme={null} This is a multi-step task. Track your progress in `progress.json` with this shape: { "completed": ["step-1", "step-2"], "in_progress": "step-3", "blocked": [], "next": "step-4" } After each step, update `progress.json` before moving on. If you get stuck, write the obstacle to `blocked` and continue with the next unblocked step rather than spinning on the current one. ``` ### Balance autonomy and safety By default, capable agentic models may take irreversible actions (delete, force-push, send, charge) without confirmation. For agents that touch shared systems: ```text theme={null} Consider the reversibility and blast radius of each action. Local, reversible actions (drafts, reads, tests) you may take freely. For destructive, irreversible, or externally-visible actions — sending messages, charging cards, deleting records, modifying shared infrastructure — confirm with the user before proceeding. ``` ### Reduce overengineering When a coding-style actor over-elaborates (adds files, abstractions, validators no one asked for): ```text theme={null} Keep solutions minimal and focused on what was asked. - Scope: Don't add features, refactor, or "improve" code that isn't part of the task. - Documentation: Don't add comments to code you didn't change. - Defensive coding: Don't add validation for scenarios that can't happen. Trust internal callers; only validate at system boundaries. - Abstractions: Don't create helpers for one-time operations. Don't design for hypothetical future requirements. ``` ### Minimize hallucinations For knowledge-base-backed actors that occasionally invent details: ```text theme={null} Never speculate about facts you haven't looked up. If the user references a specific policy, document, or customer record, search for it first using the available capabilities. If you can't find it, say so explicitly rather than guessing. ``` ## Replacements for response prefilling Older Claude models supported *prefill* — putting words into the assistant's mouth to force a particular start. Claude 4.6+ no longer supports prefill on the last assistant turn. Use these alternatives instead: | Old prefill use | Modern replacement | | ------------------------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------- | | Force JSON / YAML output | Use **Structured Outputs** with a schema, or ask for the structure and validate with a downstream Resolve Value node | | Skip `"Here is the requested summary:"` preamble | Add: `Respond directly without preamble. Do not start with phrases like 'Here is...', 'Based on...', etc.` | | Steer around unwanted refusals | Clear prompting in the user/system message — modern Claude refuses appropriately without prefill help | | Continue a truncated response | Pass the previous response into a new user turn: `Your previous response was cut off. Continue from where you stopped: [previous_text]` | | Inject mid-conversation reminders | Inject them as user-turn context or as tool results, not as fake assistant messages | ## Chaining prompts For complex tasks that span multiple decisions, splitting one big prompt into a chain of smaller prompts is often more reliable than asking one actor to do everything. In CogniAgent, you have two natural chaining patterns: 1. **Multi-actor flows.** Hand off between actors at well-defined boundaries. One actor triages, another resolves, a third confirms. Each actor gets a tightly scoped prompt instead of a megasystem-prompt that does it all. 2. **Multi-node workflows.** Use Ask AI / Call AI Agent / Resolve Value nodes in sequence: generate a draft → critique it → refine. Each node's output is structured input to the next. The most common chain is **self-correction**: draft → review against criteria → refine. Worth the latency cost for high-stakes outputs (customer-facing emails, generated SQL, anything legally consequential). ## A re-usable actor prompt template Use this as a starting skeleton when you're configuring a new actor. Fill in the bracketed pieces. ```text theme={null} You are [role: e.g. a senior customer success manager at Acme]. [Who the user typically is. What channel this actor lives on. What success looks like.] [Any non-obvious constraints — language, jurisdiction, compliance, tone.] 1. [First thing to do — usually greet / acknowledge.] 2. [Core job — what this actor exists for.] 3. [When to use which capability or knowledge base.] 4. [When to hand off to another actor or to a human.] 5. [How to end the turn.] [realistic user input] [ideal actor response] [edge case] [ideal handling] - Never [hard "no" — e.g. quote prices not in the official price sheet]. - If the user [trigger condition], [action — e.g. hand off to a human]. - For destructive or irreversible actions, confirm before acting. ``` ## Common pitfalls (and what to do instead) | Pitfall | Symptom | Fix | | ----------------------------------------------- | -------------------------------------------- | ---------------------------------------------------------------------------- | | **Vague instructions** | Inconsistent, drifty answers | Be specific. State the desired format, length, tone, and edge-case handling. | | **All negatives, no positives** | Model finds creative ways to break the rule | Replace each "don't X" with "do Y instead." | | **Wall-of-text system prompt** | Model ignores half of it; high latency | Split by purpose into XML-tagged sections. Cut anything not load-bearing. | | **Examples that all look the same** | Model overfits and gives one-note answers | Diversify examples — different lengths, tones, edge cases. | | **Over-aggressive `CRITICAL: MUST`** | Tool overtriggering, anxious behavior | Use calm, normal language. The model already takes instructions seriously. | | **Asking for action with "could you maybe"** | Model suggests instead of doing | Use imperatives: "Do X." "Make these changes." "Send the email." | | **Telling the model how to think step by step** | Reasoning becomes brittle and shallow | Ask for thoroughness in general terms; trust the model's own planning. | | **Long documents at the end of the prompt** | Model misses key details | Put long content first; queries last. | | **No channel hint** | Output looks fine in widget, broken on phone | Tell the actor which channel it's on so it can shape output accordingly. | ## Iterating on a prompt Treat prompts as software. The fastest improvement loop: Include the awkward ones — ambiguity, edge cases, the customer who never finishes a sentence. Use [Test a flow](/conversation-flows/operate/test-flow) with the current prompt. Capture outputs. Tone, accuracy, format, action taken. Note the worst failure. Add one example, tweak one instruction, clarify one ambiguity. Not five things at once. If the worst failure improved without regressing the others, keep the change. If something else got worse, revert and try a different lever. Save the test conversations in a file (or as a Conversation Flow snapshot) so you can re-run them after any prompt change. Prompts that look better often regress on cases you forgot about. ## See also Where the system prompt lives in the actor configuration UI. Give actors workflow apps, KB search, and hand-off tools. One-shot prompting inside a workflow. The source material this guide is condensed from.