🧠 Designing Smarter Agents in Johan.Chat: Mastering Context, Instructions, Behavior, and Notes

After creating your first agent and custom functions, the next step isn’t adding more tools — it’s thinking better. That begins with how you shape your agent’s mind.

Building an agent in Johan.Chat is less about stuffing information into it and more about designing its mental architecture. The way you use Context, Instructions, Behavior, and Notes has a direct impact on how clearly, efficiently, and intelligently your agent thinks and responds.

This article is your guide to using each part with purpose — and knowing when to change them.

📌 1. Context: The Identity Layer

“Who am I? What is my role here?”

The Context defines the agent’s general purpose. It’s not where you give instructions or information — it’s where you define the agent’s reason for existing.

🧠 Use Context to describe:

• The agent’s field (support, sales, HR, etc.)
• What kinds of problems it helps solve
• Its overall scope — broad, but not too technical

✅ Example:

“I am a virtual assistant that helps users troubleshoot connectivity issues and understand their telecom plans.”

Think of Context as the agent’s job description — clear and short.

📋 2. Instructions: The Governance Layer

“What should I always do — no matter what?”

Instructions are rules that guide the agent’s behavior. These are short, imperative statements that define what must or must not happen during the conversation.

✅ Good Instructions:

• Always greet the user by their first name, if available.
• Use “---” to split the message when it has more than one part.
• Never mention internal tool names or APIs.
• If the user asks something unclear, ask a clarifying question.

✅ The fewer Instructions you have, the more powerful they become. Only include rules that are always true.

💡 Pro Tip: Formatting instructions (like how to split answers, bold text, or bullet points) are better placed here than in Behavior. This ensures consistency.

⚙️ 3. Behavior: The Personality Layer

“How should I sound and structure my answers?”

Behavior is where you shape the agent’s communication style and internal reasoning flow. It defines not only the tone and format, but also how the agent thinks before speaking.

📌 Use Behavior to:

• Set tone (friendly, neutral, professional)
• Explain how to break down complex or sensitive topics
• Give formatting guidance (e.g. use lists, summaries, dividers like ---)
• Define reasoning steps or stages for structured replies

✅ You can also include support flow stages such as:

• First, acknowledge the user’s message
• Then, clarify the request if needed
• Next, provide the main answer clearly
• Finally, suggest a next action or ask a follow-up question

🧠 Example Behavior:

“The agent responds in a calm and professional tone. For technical topics, it starts with a simple explanation, then expands if needed. When presenting multiple options, it uses bullet points. The agent follows a 3-step response: (1) Acknowledge the request, (2) Deliver the answer, (3) Suggest the next step. It avoids filler words and focuses on clarity.”

🎨 Think of Behavior as the agent’s voice, rhythm, and logic flow — not its factual knowledge or hard rules.

🗂️ 4. Notes: The Modular Memory Layer

“What should I know — but only when it’s relevant?”

Notes are small knowledge blocks that activate only when the user’s message closely matches their content. They keep your agent’s core logic clean while allowing rich, situational knowledge.

📌 A Note includes:

• A title (used to classify)
• A text body (the actual content)
• Gets triggered by semantic similarity (no need for exact matching)

✅ Example Note:

• Title: Plan Upgrade Policy Text: Users can upgrade their plan at any time. Downgrades are allowed only after 30 days.

🧩 Think of Notes like flashcards — they’re only shown to the agent when the topic matches. Perfect for prices, policies, product details, or FAQs.

✳️ Place information in Notes if it’s specific, referential, or not always relevant.

🧘 Designing with Clarity: Principles That Work

Here are five key principles that will make your agents better thinkers — and more reliable performers:

1. Everything Has a Place

Before adding anything, ask:

“Is this a rule? A tone? A fact? A definition?”

• Rules → go in Instructions
• Tone, style, steps → go in Behavior
• Identity → stays in Context
• Specific info → becomes a Note

2. Make Each Layer Do Less, Not More

A powerful agent is not the one with the most data — it’s the one that knows only what it needs, exactly when it needs it.

Cut overlap. If something is already in Behavior, don’t repeat it in Instructions. If a rule is situational, move it from Instructions to Notes.

3. Think in Triggers and Lifespans

Ask yourself:

“Does the agent need to know this all the time, or just in some cases?”

If it’s conditional, time-sensitive, or too detailed — it belongs in a Note.

4. Define Formatting in Instructions, Not Behavior

If you want the agent to always format output a certain way (like using "---" to separate sections), don’t rely on tone. Make it a clear rule in Instructions:

Use “ ---” to split the message when it has multiple logical sections.

5. Refactor Often — Not Just Add

Every time your agent behaves unexpectedly, don’t just patch it. Look at what caused the confusion:

• Was it a vague instruction?
• Did the context suggest something else?
• Is the note too broad?

Rewriting or removing often solves more than stacking.

⚠️ Common Pitfalls to Avoid

Here are a few mistakes that often lead to confusion, verbosity, or contradiction:

❌ Contradictory Instructions Don’t tell the agent to summarize and be detailed in different places. Choose one — or give clear conditions.

❌ Mixed Layers Avoid placing rules in Behavior, or personality details in Instructions. Each layer has a job — let it do only that.

❌ Context Overflow Don’t dump everything into Context. Keep it tight and timeless. Move temporary or case-based info to Notes.

✅ Hidden Formatting Rules If you want consistent formatting, define it explicitly as an instruction, not as a style preference.

🧠 Final Thought: Think Like an Architect, Not a Librarian

You’re not building a storage unit for information — you’re designing a mind.

The cleaner the mind, the clearer the thought. And the clearer the thought, the better the conversation.

Use:

• Context to define who the agent is.
• Instructions to say what it must always do.
• Behavior to show how it should speak.
• Notes to inject what it should know — but only when relevant.

🎯 Don’t give your agent more to think about. Give it less, but more precisely.