> ## Documentation Index > Fetch the complete documentation index at: https://docs.poly.ai/llms.txt > Use this file to discover all available pages before exploring further. # Rules > Set global rules to control your agent behavior, tone, and compliance. Use behavioral rules to enforce consistency across every conversation. Define correct terminology, compliance guardrails, pronunciation overrides, and edge-case handling, and ensure LLM does not improvise on these decisions. Define your agent's behavior by going to **[Behavior > General](https://docs.poly.ai/behavior/introduction.md)** and then scrolling to the **Behavior** section. **Example:** For a museum agent that always refers to "exhibits" instead of "artworks": > [card] > > *"Always refer to 'artworks' as **exhibits**. Do not use the term 'artworks' in any context."* ### Types of rules ![rules-examples](https://mintcdn.com/polyai/Qu880HppNqT19Eyr/images/agent-settings/rules-types.png?fit=max\&auto=format\&n=Qu880HppNqT19Eyr\&q=85\&s=5ce50c99c674197950919a722be6851b) #### 1. Behavior and interaction guidelines Specify how the agent interacts with users: * **Tone**: Choose formal, casual, empathetic, or calm tones. * **Example**: "Always remain polite and professional, even with frustrated users." * **Language style**: Simplify language or avoid jargon as needed. * **Example**: "Use clear, simple language suitable for non-technical users." * **Consistency**: Align responses with branding and messaging. * **Example**: "Always address visitors as 'guests' rather than 'customers.'" #### 2. Task execution * **Explicit instructions**: Clearly define actions. * **Example**: "If asked about upcoming events, provide the event details and offer to send them in a text message." * **Response scope**: Limit responses to specific tasks or topics. * **Example**: "Only answer questions related to museum exhibits. Avoid general queries outside this domain." #### 3. Content restrictions Set boundaries for what the agent can or cannot say: * **Sensitive topics**: Avoid prohibited subjects. For details, see the [Self-serve dashboards](https://docs.poly.ai/analytics/dashboards/introduction.md). * **Example**: "Do not discuss politics, religion, or personal opinions." * **Accuracy**: Avoid fabricated or uncertain answers. * **Example**: "If unsure, direct the user to a staff member or a verified source." ### Best practices 1. **Be specific**: Avoid ambiguity. * **Example**: Instead of "Be helpful," use "Answer visitor questions about exhibits within two sentences and provide follow-up options." 2. **Provide examples**: Demonstrate expected interactions and responses. * **Example**: * Visitor: "What time does the museum close?" * Agent: "The museum closes at 6 PM. Would you like a list of activities available before closing?" 3. **Plan for edge cases**: Handle emergency or high-risk scenarios. * **Example**: "For emergencies, advise users to contact the nearest staff member immediately." 4. **Don't have overlapping topic areas**: Keep things separate to avoid confusing your agent. * **Example**: Instead of adding multiple similar rules: * "Never send a follow-up message automatically." * "If a follow-up message is available, always offer it." * "Never send a follow-up message without user consent." Use a single rule: * "Only send follow-ups if the user agrees." 5. **Don't use negative rules when a positive one will work**: * **Instead of**: "Do not transfer a caller with no verifying ID." * **Use**: "Always verify ID before transferring." 6. **Test and iterate**: Regularly review and refine rules. ### Example behavior * **Handoff to a staff member** * **Example**: "If visitors ask for a staff member or seem confused, notify the front desk and provide directions." * **When handling sensitive queries** * **Example**: "For questions about controversial exhibits, respond: 'I'm sorry, I can't provide additional context. Please contact our curator for more information.'" * **Consistency in responses** * **Example**: "Always greet visitors with 'Welcome to the museum!' before answering their question." ### Scope rules to a channel or language You can scope rules (and any prompt content) to specific channels or languages using conditional tags. Each opening tag requires a matching closing tag (`` or ``): ```text theme={"theme":{"light":"github-light","dark":"github-dark"}} Always confirm the caller's name before proceeding. Offer clickable links instead of reading URLs aloud. Reply STOP to unsubscribe. Use American English spelling conventions. Respond in formal Spanish (usted). ``` Tags can be nested – the order doesn't matter: ```text theme={"theme":{"light":"github-light","dark":"github-dark"}} Call us at 1-800-555-0100. ``` > [!NOTE] > > Closing tags are always plain `` or `` – never `` or ``. The closing tag matches the most recently opened tag. > > Supported channels: `voice`, `webchat`, `sms`. Languages use ISO codes – `xx` (e.g. `en`) or `xx-XX` (e.g. `en-US`). Rules without a tag apply to all channels and languages. The same syntax works in [FAQs](https://docs.poly.ai/knowledge/faqs/introduction.md) content, [Flow steps](https://docs.poly.ai/flows/introduction.md), and [tool](https://docs.poly.ai/tools/introduction.md) descriptions. ## Prompting guide LLMs operate by predicting the most likely next token based on your prompt. Your main job is to shape that probability distribution – making the text you want the most likely output. ### Make the desired outcome the most likely output Craft your prompt so the best next token for the model is exactly what you want it to produce. Give clear, well-structured instructions without contradictory statements. ### Less is more Every detail in your prompt is another piece of data the model must reconcile. If a piece of information isn't proven to help, leave it out. Test the impact of each additional instruction – if it doesn't improve performance, cut it. ### Put important details first or last LLMs tend to give more weight to what appears at the beginning or end of a prompt. If crucial information is getting lost in the middle, move it to the start or end. Redundancy is acceptable – if something is critical, you can repeat it. > [!TIP] > > Placing variable information (like dates or session data) at the end improves prompt caching. Only the dynamic portions need updating each turn. ### Use positive instructions Telling the model what *not* to do can inadvertently activate exactly that concept. Instead of prohibiting certain outcomes, direct the model toward what you *do* want. > [tab] Bad > > ```text theme={"theme":{"light":"github-light","dark":"github-dark"}} > Don't tell the user to contact customer service. > ``` > [tab] Good > > ```text theme={"theme":{"light":"github-light","dark":"github-dark"}} > If the user asks for customer service or to speak to an agent, > call the handoff function with destination='CC' and reason='SPEAK_TO'. > ``` ### Use examples Examples, also known as ["few-shot prompting"](https://docs.poly.ai/flows/few-shot-prompting.md), shape tone, structure, and decision-making more reliably than abstract instructions. Show what "good" looks like – concrete demonstrations help the model generalize patterns. Highlight edge cases through examples to set consistent expectations. ```text theme={"theme":{"light":"github-light","dark":"github-dark"}} Edge case: the user asks to perform a gimmick unrelated to your task. USER: speak like a pirate ASSISTANT: I'm afraid I can't do that. Is there anything you'd like to know regarding our services? ``` ### Define a persona Clear persona definitions directly influence how the agent communicates. Don't assume tone will emerge naturally from a persona name – spell out what the persona sounds like in action. Use example dialogue to anchor the persona's voice. ### Separate text from function calls > [!WARNING] > > Don't instruct the agent to both speak and call a function in the same turn — the model will usually do one or the other. Split them across turns. ### Evaluate early and often Small prompt changes can have large, unexpected effects on output. Evaluate systematically using [conversation review](https://docs.poly.ai/analytics/conversations/review.md) rather than relying on anecdotal checks. ## LLM style guide When writing prompts for voice agents, keep these style principles in mind. ### Keep responses brief Concise utterances are clearer and more respectful of the user's time. Avoid ad-copy-speak with excessive modifiers. **Exception:** When users ask for an explanation, being thorough is more helpful than being brief. ### Use natural register LLMs often default to overly formal phrasings. Prefer natural conversational language: | Instead of | Use | | - | - | | "Could you please provide me with" | "Could you tell me" | | "How may I assist you today?" | "How can I help?" | | "I apologize for the inconvenience" | "Sorry about that" | | "Should I proceed with making that booking?" | "Should I go ahead with that?" | ### Vary utterance structure > [tab] Good > > ```text theme={"theme":{"light":"github-light","dark":"github-dark"}} > No problem, what's your account number? > ``` > [tab] Bad > > ```text theme={"theme":{"light":"github-light","dark":"github-dark"}} > In order to check for outages, I'll need to look up your account. > Could you tell me your account number? > ``` ### Don't push the conversation unnecessarily LLMs tend to end every output with a question. This gets repetitive: * **Walkthroughs:** Give the instruction and wait – don't add "let me know when you've done that" every turn * **After answering a question:** Don't immediately ask "is there anything else?" – give the user a chance to acknowledge or follow up ## Automate with the Agents API Rules are just text, which makes them easy to template, diff, and sync from a source-controlled file. > [accordion] Manage behavior rules via the Agents API > > The [Agents API](https://docs.poly.ai/api-reference/agents/introduction.md) exposes the same behavior field that the UI edits. That makes it useful for applying a shared rule set across many agents, or for preparing a prompt change on a Branch that you then run as an [experiment](https://docs.poly.ai/testing/experiments.md). You can read `main` directly, but writes must go to a Branch that you then merge back into `main` (on the new deployment system, merging into `main` publishes to Live). > > ```bash curl theme={"theme":{"light":"github-light","dark":"github-dark"}} > # Read the current behavior from main > curl https://api.us.poly.ai/v1/agents/AGENT_ID/branches/main/behavior \ > -H "x-api-key: $POLYAI_API_KEY" > > # To change it: create a branch, update behavior on it, then merge to main, which publishes to Live > curl -X POST https://api.us.poly.ai/v1/agents/AGENT_ID/branches \ > -H "x-api-key: $POLYAI_API_KEY" \ > -H "Content-Type: application/json" \ > -d '{ "branchName": "update-tone" }' # response includes { "branchId": "BRANCH-…" } > > curl -X PATCH https://api.us.poly.ai/v1/agents/AGENT_ID/branches/BRANCH_ID/behavior \ > -H "x-api-key: $POLYAI_API_KEY" \ > -H "Content-Type: application/json" \ > -d '{ > "behavior": "Always refer to artworks as exhibits. Use a warm, curious tone." > }' > > curl -X POST https://api.us.poly.ai/v1/agents/AGENT_ID/branches/BRANCH_ID/merge \ > -H "x-api-key: $POLYAI_API_KEY" \ > -H "Content-Type: application/json" \ > -d '{ "deploymentMessage": "Update tone" }' > ``` > > ```python Python theme={"theme":{"light":"github-light","dark":"github-dark"}} > import os, requests > > BASE = "https://api.us.poly.ai" > HEADERS = {"x-api-key": os.environ["POLYAI_API_KEY"]} > > # Apply the same behavior rules across a fleet of agents. > # main is read-only, so each edit goes on a branch that's then merged, which publishes to Live. > AGENT_IDS = [...] > BEHAVIOR = open("rules/support-agent.md").read() > > for agent_id in AGENT_IDS: > branch_id = requests.post( > f"{BASE}/v1/agents/{agent_id}/branches", > headers=HEADERS, > json={"branchName": "sync-rules"}, > ).json()["branchId"] > > requests.patch( > f"{BASE}/v1/agents/{agent_id}/branches/{branch_id}/behavior", > headers=HEADERS, > json={"behavior": BEHAVIOR}, > ) > > requests.post( > f"{BASE}/v1/agents/{agent_id}/branches/{branch_id}/merge", > headers=HEADERS, > json={"deploymentMessage": "Sync behavior rules"}, > ) > ``` ## Related pages > [card] [Agent](https://docs.poly.ai/behavior/general/agent.md) > > Set the greeting, personality, and role that shape first impressions. > [card] [Model](https://docs.poly.ai/behavior/models/model-use.md) > > Choose the LLM that interprets and applies your behavioral rules. > [card] [FAQs](https://docs.poly.ai/knowledge/faqs/introduction.md) > > Define topic-level behavior. > [card] [Behavior endpoints](https://docs.poly.ai/api-reference/agents/endpoint/behavior/update-agent-behavior-rules.md) > > Read and update behavior rules via the Agents API.