Conversational Design

Follow these patterns to build agents that feel helpful rather than intrusive, and that consistently guide users to value. Quickstart connects activity to your AI support agent. This page covers what the agent should do with that context once it can read it.

​

Treat every proactive message as an interruption

No matter how good a suggestion is, being interrupted has a cost. Think of a retail store: even if someone walks up with a genuinely useful recommendation, the fact that they inserted themselves into what you were doing is what registers first. It can feel annoying regardless of how useful the suggestion turns out to be. The same is true for a proactive agent. Good timing from get_proactivity_criteria reduces how often this happens, but it does not eliminate the interruption itself. The agent is still choosing to speak before being asked. The fix is not to suppress proactive suggestions. It is to change how they are framed:

• Never assume the interruption is welcome just because the suggestion is good.
• For every interruption, say plainly that you have something useful to show and ask whether now is a good time before sharing it.
• Make declining effortless. “Not now” should require no explanation and should never lead to another ask in the same turn.

I have something that could help with what you’re working on. Would now be a good time for me to show you?

​

Introduce the agent before offering advice

People appreciate knowing what they are talking to and why before an agent starts making suggestions. A good introduction does three things: says who the agent is, explains what it is designed to help with, and asks permission before sharing anything.

Hi, I’m an agent designed to help you get set up with the product. I have a suggestion for you. Would now be a good time to share it?

This matters even more when the suggestion is personalized. Asking first signals that the agent is offering help rather than pushing an agenda, and gives the user an easy way to say “not now.”

​

Give new users something useful to respond to

Users are often too new to know what to ask. Do not open with an empty “How can I help?” That puts the burden on the user to know what is possible. Instead, use get_live_user_activity and get_onboarding_context to offer one to three likely next questions or actions as concrete choices.

It looks like you haven’t invited teammates yet. Want me to walk you through that, or show you how the dashboard works first?

If one action is clearly the most relevant, recommend only that action. Offer multiple choices only when they are genuinely useful alternatives.

​

Use a consistent vocabulary

Define a small vocabulary so the agent does not sound like it is improvising a new personality in every message.

• Choose one way to describe progress. For example, use “milestone” consistently rather than alternating between “step,” “stage,” and “level.”
• Prefer warm, plain language over internal product jargon.
• Use a consistent style for follow-up questions.

The agent should still mirror terminology the user introduces. Consistency should make the conversation easier to understand, not make it sound scripted.

​

Guide the user toward one valuable next action

The agent’s core job is to onboard the user and guide them to their next useful action, not only to answer questions. Once the user gives permission to continue, the conversation should follow three steps: Acknowledge progress → Suggest the next step → Explain its value

1. Acknowledge the user’s meaningful progress and connect it to related activity or existing progress. Do not use a generic “great job.”
2. Suggest one concrete next action.
3. Explain why that action is valuable for this user, not merely why it is a useful feature.

I can see your first automation is live, and you connected Slack earlier, so you’re set up for real-time alerts. I’d turn one on for that automation next. You’ll know the moment it fires instead of having to check back. Want me to help you set up the alert?

Treat the sequence as a structural reasoning pattern: Do not expose those labels in the response or repeat the same phrases mechanically. The result should read as one natural train of thought. The acknowledgement should demonstrate that the agent has been paying attention to more than the single event that triggered the message. Fold relevant context into the acknowledgement rather than treating it as a separate step. That is what earns the agent the standing to suggest a next action. Without context, the response feels scripted. Without the value, it feels like a directive rather than a reasoned suggestion.

​

Never tell users what they already know

Nothing breaks trust in a smart agent faster than explaining something the user clearly knows or suggesting an action they already completed. It signals that the agent is not paying attention. This is why get_onboarding_context and get_live_user_activity should be used together:

• Do not explain a UI element the user just used successfully.
• Do not suggest a milestone that onboarding context shows as complete.
• Do not narrate an action that live activity shows the user is already completing correctly.

If there is any doubt, check context first. Do not guess or default to over-explaining.

​

End with an easy, personalized follow-up

Default to a specific question the user can answer in one tap or a few words.

Want me to set up alerts for that next?

This is more useful than:

Let me know if there’s anything else I can help with.

Keep a generic “I’m looking for something else” path available as a fallback, but do not make it the primary close. If the user declines, requests a human, or ends the conversation, accept that without asking another question.

​

Continue with the agent configuration