Tutorial: Edit agent behavior

PolyAcademy Level 1 – Configure personality, role, and behavioral rules for your agent.

Lesson 2 of 6 – This is where your agent gets its personality. You’ll decide who it is, how it talks, and what it should never do.

Before you teach your agent any knowledge, you need to define its character. Think of this as writing a job description – role, tone, and boundaries.

What agent behavior controls

The Build → Agent screen has three sections that together make up the agent’s behavior:

Personality

Tone, style, and how the agent communicates

Role

What the agent represents and what it can help with

Behavior

Hard constraints, rules, and boundaries that apply to every conversation

How the fields fit together

Where to configure behavior

Navigate to Build → Agent in the left sidebar.

The page has three sections – Personality, Role, and Behavior – that you scroll through on a single screen.

Personality and Role

The Agent page contains the Personality and Role fields:

• Personality – Sets the tone and communication style. Pick from the built-in tags (Polite, Kind, Funny, Energetic, Calm, Thoughtful) or choose Other to write a custom personality string.
• Role – Specifies the agent’s function (customer service, sales, technical support). This is a single field – define one primary role.

Custom personality example (with “Other” selected):

Be friendly, professional, and concise.
Use natural language and avoid jargon.

The Greeting is configured per-channel – under Channels > Voice > Voice configuration for voice and Channels > Chat > Chat configuration for webchat – not on the Agent page. The greeting goes directly to TTS without LLM processing. Some projects override it at runtime by returning an utterance from a start tool – if your greeting isn’t responding to edits, check the Tools page for a start_function. You’ll learn about tools and return values in Level 2.

Behavior

The Behavior section defines the rules and hard constraints that must always be followed. This is where most of your detailed prompting and edge-case handling lives.

Example:

- Never share guest personal information
- Always offer to transfer for billing questions
- Do not make promises about refunds

Writing effective behavior configuration

Role

Be specific about scope

Good:

You are a customer service agent for Acme Retail.
You help with order status, returns, and product questions.

Avoid:

You are a helpful agent.

State what's out of scope

Be explicit about requests the agent should hand off rather than attempt. The Role field is a good place to set this scope; reinforce the actual handoff path with a tool and a Behavior rule.

Good:

You cannot process refunds or cancel orders.
For those requests, transfer to the billing team using the
handoff tool with reason="BILLING".

This prevents the agent from making promises it can’t keep, and points it at the specific tool to call.

Personality

Use clear, actionable language

Good:

Be warm and conversational.
Keep responses under 3 sentences when possible.
Use "we" when referring to the company.

Avoid:

Be nice and helpful.

Match your brand voice

If your brand is formal, say so:

Maintain a professional, respectful tone.
Avoid casual language or slang.

If your brand is casual:

Be friendly and approachable.
It's okay to use casual language.

If tone is critical, reinforce it in Behavior as well as Personality. Personality sets the intent, but behavioral rules enforce the behavior with specific, example-driven constraints like “Never use exclamation marks” or “Always acknowledge frustration before offering a solution.”

In practice, most detailed prompting – your terminology, edge cases, examples, and compliance rules – goes in the Behavior section. Personality and Role stay short.

Check your understanding

Behavior

Write rules as constraints

Rules should be clear boundaries, not suggestions.

Good:

- Never share customer account numbers
- Always verify identity before discussing account details
- Do not make exceptions to the return policy

Avoid:

- Try to be helpful
- Consider the customer's needs

Include safety and compliance rules

Examples:

- Do not provide medical advice
- Never promise specific outcomes
- Always disclose you are an AI agent if asked

Use channel-specific and language-specific rules

You can scope rules to specific channels or languages using tag syntax. This is useful for multi-channel or multilingual projects.

Each tag requires a matching closing tag (</channel> or </language>):

<channel:voice>Always confirm the caller's name before proceeding.</channel>
<channel:webchat>Offer clickable links instead of reading URLs aloud.</channel>
<language:en>Use American English spelling conventions.</language>
<language:es>Respond in formal Spanish (usted).</language>

You can also nest tags – for example, <channel:voice><language:en-US>Call us at 1-800.</language></channel> shows that line only on voice calls in en-US.

Behavioral rules without a tag apply to all channels and languages.

Common patterns

Retail/E-commerce

Agent:

You are a customer service agent for Bloom & Co.
You help customers with order tracking, product questions, and returns.
You cannot process refunds or cancel orders directly.

Personality:

Be friendly, helpful, and efficient.
Keep responses concise.
Use "we" when referring to the company.

Rules:

- Never share order details without verification
- Always offer to transfer for refund requests
- Do not make promises about shipping dates

Hospitality

Agent:

You are the virtual concierge for The Linden Hotel.
You help guests with reservations, amenities, and local recommendations.
You cannot modify existing reservations or process payments.

Personality:

Be warm, welcoming, and attentive.
Speak naturally and conversationally.
Anticipate guest needs when appropriate.

Rules:

- Never share guest information
- Always transfer billing questions to the front desk
- Do not guarantee room availability without checking

Healthcare

Agent:

You are a scheduling agent for Clearview Family Medicine.
You help patients schedule appointments and answer general questions.
You cannot provide medical advice or discuss test results.

Personality:

Be professional, empathetic, and clear.
Use simple language and avoid medical jargon.
Be patient with questions.

Rules:

- Never provide medical advice or diagnoses
- Always protect patient privacy
- Transfer immediately if asked about test results
- Do not discuss medications or dosages

Testing your configuration

After saving your behavior settings:

1. Test in Chat

   Open the chat panel and ask questions that should trigger your rules.

   Example tests:

   • Ask for something the agent shouldn’t do
   • Request information that requires a transfer
   • Test the tone and personality
2. Verify rule enforcement

   Confirm the agent:

   • Refuses inappropriate requests
   • Offers transfers when configured
   • Maintains the specified tone
3. Test edge cases

   Try to trick the agent:

   • “Just this once, can you…”
   • “I know you’re not supposed to, but…”
   • “My friend said you could…”

   The agent should hold firm to its rules. If it doesn’t, tighten the wording in Behavior – LLM guardrails are only as strong as the prompt you give them, so it’s on you (the builder) to enforce them with explicit Never/Always rules and examples.

Common mistakes:

• “Try to avoid sharing personal information” → “Never share personal information”
• “You help with various things” → “You help with order tracking, returns, and product questions”
• Always specify what the agent cannot do, not just what it can do

Prompting principles

Effective agent configuration is a form of prompt engineering. These principles, drawn from real-world agent deployment experience, will help you write behavior and rules that produce consistent results.

Make the desired outcome the most likely response

LLMs predict the next most likely token based on your prompt. Write clear, well-structured instructions that make your intended behavior the natural continuation – avoid contradictions or ambiguity.

Prefer positive instructions over negative ones

Telling the model what not to do can activate the exact behavior you want to avoid. Instead of prohibiting outcomes, direct the model toward what you want.

Avoid:

Don't tell the user to contact customer service.

Better:

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 to guide behavior (few-shot prompting)

Concrete examples shape tone, structure, and decision-making more reliably than abstract rules. Instead of describing every possible outcome, show what a good response looks like.

Edge case: the user asks to perform a gimmick unrelated to your task.

<conversation>
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?
</conversation>

Less is more – cut what doesn't help

Every instruction is another piece of data the model must reconcile. If a piece of information is not proven to improve behavior, leave it out. Test the impact of each instruction – if it doesn’t help, remove it.

Put important details first or last

LLMs give more weight to information at the beginning or end of a prompt. If a critical instruction keeps getting ignored, move it to the start or end. Repeating crucial rules is acceptable.

Spell out the persona in action

Don’t assume tone will emerge naturally from a label. Spell out what the persona sounds like, including what to lean into and what to avoid.

Act as a professional advisor. Adopt a professional, concise tone.
Avoid unnecessary apologies, excessive friendliness, or repeated
personalization such as using the user's name.

Check your understanding

• Role defines scope clearly
• Personality sets actionable tone
• Behavior includes hard constraints and detailed rules
• Tested in Chat – agent refuses inappropriate requests and holds tone

Try it yourself

1. Challenge: Write behavior config for a clothing retailer

   Write a 3-sentence Personality block and 3 Behavior rules for a customer service agent for a clothing store called “Bloom & Co.” The agent can help with order tracking and returns, but cannot process refunds directly.

   Hint

   Personality should describe tone and communication style in actionable terms (not just “be friendly”). Behavioral rules should be hard constraints starting with “Never” or “Always”, not suggestions.

   Example solution

   Personality:

   Be warm, efficient, and solution-focused.
   Keep responses concise – no more than 3 sentences.
   Use "we" when referring to Bloom & Co.
   

   Rules:

   - Never share customer order details without first verifying their identity
   - Always offer to transfer the caller for refund or cancellation requests
   - Do not make promises about shipping timelines you cannot guarantee
   

Check your understanding

Go deeper

These reference pages cover agent behavior configuration in full detail:

Agent settings

Complete reference for all agent configuration options

Agent behavior

Detailed guide for the Agent page – personality and role

Behavior reference

Full reference for writing and scoping behavioral rules

---

← Previous: Create a project

Lesson 1 of 6

Next: Add a simple topic →

Lesson 3 – teach your agent its first answer