v3 Agent Best Practices

These are the practices that consistently produce good v3 bots. They come from teams that have shipped Nexus agents to production — read them once when you start, and revisit them before each release.

Start small

The single biggest mistake new builders make: building five agents on day one.

Do this instead:

1. Build one super agent. Get it answering 80% of common questions correctly.
2. Look at real (or test) transcripts. Find the place the bot consistently fails.
3. Then introduce an agent or a tool to handle that case.

Extra agents add complexity. Add them deliberately, not preemptively.

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.")

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	v2 and v3	v3 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 v3, both Welcome and Fallback let you go dynamic:

• Welcome → Instruct super agent (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 → Instruct super agent 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 v3 isn't a context-window slider — it's a typed key-value store, shared across all agents in a conversation (see Memory in v3 agents). 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.