Design principles — read this first

Most "the agent gives bad answers" problems are configuration, not the model. Follow these before you build, and the results hold up. Ignore them and it is easy to assemble something that looks plausible and behaves badly — then mistake that for a platform limit.

One agent, one job

Give each agent a single, clearly bounded task. A "does everything" agent — support and sales and scheduling — has a diffuse task, competes with itself for attention, and answers each thing worse. If you have three jobs, build three agents.

Keep the skill count small

Attach only the skills this agent's job needs — roughly five or fewer. Skills are chosen by the model from their one-line description; the more you attach, the harder that choice, and the more often it loads the wrong one or none. A focused set with sharp "use this when…" descriptions beats a big pile.

• Each skill's description says when to reach for it, in one line.
• Procedures live in instructions (loaded on demand), never in soul (paid for every turn).
• If two skills overlap in when, merge them — overlapping triggers make the choice a coin-flip.

Ground facts; put boundaries in the task

• Facts (rates, policy, catalogue) belong in a knowledge base, which is retrieved every turn — not in the prompt, where they go stale and un-cited. See Build a knowledge base.
• Constraints belong in task, as negatives: "never promise a date", "for a quote, call a tool". Negative boundaries stop drift better than positive description. Don't put safety rules in soul — the platform appends global moderation for you.
• Turn on grounding_required when answers must come from the material, not the model's priors.

Prefer deterministic control where correctness matters

When an outcome must be reliable, don't leave it to the model. In Storylines, use rule / user_choice exits for routing and reserve ai exits for genuine judgment. Model loops with an explicit counter and a cap, not "the LLM will stop eventually". See Modelling a process as a Storyline.

Show the agent good patterns only

When you hand an agent examples, make them correct examples. Don't paste a "here's the wrong way" snippet next to the right one — the model may imitate the nearest example rather than read the caveat. Describe what to avoid in words; keep runnable examples exemplary.

Verify — writing is not working

After every change, check it did what you intended. Creating an agent doesn't mean it's configured the way you think; adding to a knowledge base doesn't mean the question retrieves.

get_agent(name="Support")                                   # confirm the config that landed
search_knowledge_base(kb_name="Company policy", query="…")  # confirm the answer is retrievable

An empty search result means that question will be answered as "not covered" — find that now, not from a customer.

Hand back a deliverable, not "done"

After every action, don't just report that you finished — tell the user what you produced, a clickable link to view it in the console, and one line on how to use it. They will ask "where do I see it?" and "how do I use it?" anyway; answer both up front. URL-encode names that contain spaces.

For example, after importing documents into a knowledge base, reply with how many chunks landed, the link above so they can open its knowledge starmap and see exactly what was ingested, and confirm whether it's now attached to an agent (or how to attach it). A bare "done" just makes them ask.