Agent Best Practices
These are the practices that consistently produce good Nexus bots. They come from teams that have shipped Nexus agents to production - read them once when you start, and revisit them before each release.
Flip through them as flashcards - try to answer each question before you reveal it - or switch to Read as article for the full text.
Start small
The single biggest mistake new builders make: building five agents on day one.
Do this instead:
- Start with just the bot's configuration. Get it answering 80% of common questions correctly.
- Look at real (or test) transcripts. Find the place the bot consistently fails.
- Then introduce an agent or a tool to handle that case.
Extra agents add complexity. Add them deliberately, not preemptively.
The same restraint applies to tools within an agent. An agent with a long tool list and lots of inline "decide, then call, then decide again" logic becomes unpredictable - every extra tool is one more thing routing has to choose between, and every inline decision is a place the model can drift. Keep an agent's job conversational: understand the user, pick the right next step, talk back. Push deterministic multi-step logic - call API, branch on the result, call another API, format the output - into a workflow and attach it as a single tool the agent calls. The agent owns the conversation; the workflow owns the procedure. If you find an agent juggling many tool calls per turn, that's the signal to move the orchestration into a workflow (or a guided agent).
Treat bot identity as a contract
Your bot identity is the most important field on the entire platform. It's also the field most builders treat carelessly.
Do this:
- Lead with role, then responsibilities, then constraints, then tone.
- Be concrete about what the bot must NOT do. "You never quote pricing" stops bad behavior; "You're a helpful assistant" doesn't.
- Stable identity = stable behavior. Don't tweak identity casually - every change ripples through every conversation.
Don't do this:
- Don't write marketing copy. ("You're the best assistant on Earth!" - the model will not behave better.)
- Don't be vague. ("You help customers with anything" gives the model no constraints.)
- Don't pile on contradictions. ("Be brief. Always explain in detail.")
Writing prompts
Every prompt field rewards the same habits: short plain sentences, one instruction per line, concrete do's and don'ts, and saying what not to do as clearly as what to do. The bot identity above is the headline example, but the detailed, field-by-field guidance lives with each surface - keep this page as the index and follow the links:
- Agent instructions and Triggers - keep when to take over (Trigger) separate from how to behave (Agent instructions); see Conversational agents → Writing agent instructions.
- Memory variables - name only the variables a later turn actually reads, and prefer tool input mapping for single-turn values; see Memory in Nexus agents.
- Tool descriptions and calling - write descriptions like a docstring (what / inputs / when / when-not) so the model calls the right tool with the right arguments; see Tools - Best Practices.
Pick rules carefully
There are two rule lists, and people mix them up:
| Conversation Rules | Routing Logic | |
|---|---|---|
| What it shapes | Tone, do's and don'ts | Where messages get routed |
| Available on | Nexus and the legacy platform | Nexus only |
| Use when… | "The bot should always confirm before submitting" | "Billing questions must go to billing-agent" |
Both have the same per-rule limits in the studio (20-500 characters). Both let you add many rules.
Best practices:
- One rule, one concern. Compound rules are hard to debug.
- Phrase positively when possible - "Confirm the order ID before sharing details" beats "Don't proceed without an order ID."
- Test each rule with a single, dedicated test prompt. If you can't write that test, the rule is too vague.
Don't ship static welcome and fallback strings
A hardcoded "Hi! How can I help?" works for a hackathon, not for production. In Nexus, both Welcome and Fallback let you go dynamic:
- Welcome → Instruction lets the model pick the right opening based on context (returning user vs new, logged-in vs anonymous, channel-specific tone). Welcome can also trigger a welcome workflow if the greeting needs to look something up first (loyalty status, account info).
- Fallback → Instruction lets the model do real recovery - rephrase the user's intent, suggest a likely topic, or offer a hand-off - instead of a generic apology string. Pair it with the Retries count for validation failures.
If your welcome or fallback needs to act (search the KB, route to a human, render rich media), reach for a workflow - either picked directly in the welcome picker, or invoked as a workflow or knowledge-base tool the model calls from the Instruction prompt.
Don't put everything into Memory
Memory in Nexus isn't a context-window slider - it's a typed key-value store, shared across all agents in a conversation (see Memory). The temptation is to stash everything you might need later. Resist it.
Why restraint matters:
- Every variable you declare becomes a prompt input. More variables = larger prompts = more cost and latency per turn.
- Two agents writing to the same variable name silently overwrite each other.
- Memory persists for 2 days. Single-turn values don't belong there - pass them through tool input mapping instead.
Best practice: start with the minimum. Add a variable only when you can name the specific later turn (or specialised agent) that needs to read it.
Turn safety filters on before you ship
If your account has AI Safety & Conduct:
- Enable customer-query filters and AI-response filters before going live.
- Test adversarial prompts (jailbreaks, off-topic, hostile) in Testing Lab.
- Pair filters with a fallback that says something safe and helpful when a filter fires - silence is worse than a graceful redirect.
Test like you mean it
The Nexus testing tools are good. Use them.
- Playground (▶ on each agent) - test individual conversations as a user would.
- AI Trust Centre → Dataset - store a curated set of test cases.
- AI Trust Centre → Testing Lab - bulk-replay your dataset before every release.
A typical regression suite has 10-30 test cases covering: golden-path successes, common edge cases, every routing rule, every tool, and a few adversarial prompts. Saving these once pays for itself the first time you tweak identity and need to verify nothing regressed.
Voice ≠ chat
If your bot serves voice:
- Lower memory than chat (latency matters more).
- Lower validation retry limits (failed retries compound latency).
- Test in the Voice Playground specifically - TTS pacing, interruptions, and barge-in behave differently than chat.
Build a release checklist
Before each release:
- Identity changes reviewed and approved by stakeholders
- All routing rules have a test prompt that proves they fire
- Fallback uses an Instruction that can recover gracefully (not a static apology)
- Safety filters enabled and tested with adversarial prompts
- Regression dataset replayed and passing
- Voice playground spot-checked (if voice channel)
The first time this checklist saves you from a regression, you'll keep using it forever.
When to ask for help
If your bot is doing something genuinely puzzling - wrong agent fires consistently, identity instructions seem ignored - open the Playground (▶ on the misbehaving agent) and re-send the message. Read the bot's reply carefully, then re-check the agent's Trigger, identity, and any Routing Logic rules - most "weird behavior" traces back to one of those three.