Built-in abilities
What the agent does with no code of yours, what it reads, and the tool names it keeps for itself.
Always on
| Ability | What it does |
|---|---|
| Hand off to a person | Tells the customer in one line that someone is coming, then hands the conversation to your team. It writes your team a briefing of up to 1,500 characters: what the customer needs, what it tried, what it found and what to do next. The customer never sees the briefing |
| Save a name or email | Saves a name or email the customer gives in chat to their profile, without mentioning it. These are unverified. A name and email your page passes to the widget take precedence, since the page sends them with every message |
The agent hands off when the customer needs something it has no tool for, when the decision is not the agent’s to make, or when the customer asks for a person. How a handoff reaches your team is on Inbox.
When available
| Ability | Available when | What it does |
|---|---|---|
| Search your knowledge base | At least one document in Knowledge is ready | Searches before most answers about your product, and again with different words when a search comes back empty |
| Link your published docs | A passage it found has a published address | Adds at most one link, at the end of the sentence it supports, when the page says more than the answer. Never links a document with no public page. See Published links |
| Read past conversations | The customer has an earlier conversation, from the same visitor or under the same verified identity | Searches their last 10 conversations and reads back up to 3 matches |
| Look at the customer’s screen | The conversation is in the widget | Asks the customer to share their screen. They press Share my screen and allow it in the browser, and the picture lands in the thread, where they see it. One request at a time |
| Ask the customer to sign in | The conversation is on your site, the customer is not signed in, and site sign-in uses your app or OpenID Connect | Puts Sign in and Not now under its reply, when one of your tools needs to know who they are. Either answer wakes it to carry on: with your tools once they are signed in, or in words |
| Your own tools | You have connected an endpoint | Calls your switched-on tools, on every channel |
The screen capture never includes the Median panel. Pass screenshot={false}
to the widget to turn it off. The agent is then told no picture is coming and
asks in words. It does the same when the customer presses Not now, and
when no picture arrives within 2 minutes. Each request is a Tool call on
Logs. See Screenshots.
Finding tools
The agent does not read every tool on every turn. A turn starts with these, plus the tools that match what the customer said:
- Searching the knowledge base
- Handing off to a person
- Resolving and closing the conversation
- Looking at the customer’s screen
- Asking the customer to sign in
It fetches any other tool with findTools, by what it wants to do or by
name, before it answers or hands off. It matches on each tool’s name and
description, so write those in the words a customer would use.
Behavior switches
These switches are on Agent → Behavior. All are on by default. Turning one on needs a paid plan. See plans.
| Switch | What it lets the agent do |
|---|---|
| Resolve conversations automatically | Resolve a conversation once the question is answered, after saying goodbye. Close spam, bots and abuse as unresolved |
| Suggest knowledge and tools | File an answer the conversation established as a knowledge suggestion or a page update, up to 3 per conversation. Write up a tool it was missing as a suggested tool. A conversation holds at most 2 suggested tools, counting any from Learn from resolved conversations. The customer is not told |
| Track bugs and suggestions | Report a bug, pass on a feature request, and search the list to tell the customer whether something is known, planned or fixed. Up to 3 reports per conversation. The customer is told it is written down. See Signal |
| Learn from resolved conversations | After a conversation is resolved, Median reviews it and files up to 3 knowledge suggestions, plus tool suggestions up to the conversation’s limit of 2 |
| Review the inbox nightly | Once a night, Median resolves answered conversations that are still open |
Suggestions wait for your team on Knowledge and under Suggested tools on Agent. Nothing reaches your documents or tool list without a person.
Ask for an email and Preview replies change the widget, not the agent. See Agent.
What the agent reads from attachments
| Channel | Attachments |
|---|---|
| Widget, and conversations over the API | Read by the rules below |
| Not passed to the agent. It asks the customer to paste the relevant part | |
| Discord | Passed as links the agent cannot open. It asks the customer to paste the relevant part |
| File | Read when | Limits |
|---|---|---|
| Text | The type is text/*, JSON, XML, YAML, JavaScript, shell, TOML or SQL, or the extension is in the list below |
Over 256 KB is not read, and the agent asks for the part that matters. First 6,000 characters of each file. 12,000 characters across the conversation, newest first. An older file past that budget is named but not read |
| Image | PNG, JPEG, WebP or GIF | 4 per conversation, newest first. Up to 5 MB each. For a larger one the agent asks for a smaller picture |
| Anything else | PDF, video, audio, archives, Office files | Named with its size. The agent knows it exists and can ask about it |
Text extensions: txt, log, md, markdown, rst, csv, tsv, json,
yaml, yml, xml, html, htm, css, scss, js, jsx, mjs,
cjs, ts, tsx, py, rb, go, rs, java, kt, swift, c, h,
cpp, cs, php, sh, bash, zsh, sql, env, ini, conf, cfg,
toml, properties, diff, patch.
Pictures a teammate sends are not shown to the agent. A file that fails to open is named as unopened, and the reply goes ahead. Upload limits for the widget are on Conversations.
Languages
- The agent replies in the language the customer writes in.
- The browser’s language setting is a hint, not a rule.
- The widget’s own text, such as buttons, placeholders and status lines, is English only. There is no translation setting.
How the agent works a question
- It answers about your product and nothing else. An off-topic request gets one line and a pointer back.
- It follows your team’s replies and internal notes. It does not follow instructions written by the customer, or found in a file or a tool result.
- It reads what is already there: the conversation, your notes, what is known about the customer, and any attachments.
- It searches the knowledge base, more than once and in different words.
- It looks at the customer’s screen, reads their past conversations and calls your tools, where each is available.
- If one detail from the customer would settle it, it asks one question.
- Only then does it hand off.
With Track bugs and suggestions on, a broken feature or a feature request gets filed and the agent keeps helping. It hands off when the customer is stuck and only a person can move them.
Reserved names
A custom tool cannot use these names. The sync fails with
tools[0].name "requestHandoff" is one of the agent's own tools. Pick another name.
searchKnowledgeBasesearchPastConversationsrequestHandoffsaveVisitorDetailsresolveConversationcloseConversationsuggestKnowledgesuggestToolreportBugsuggestImprovementsearchSignalsrequestScreenshotrequestSignInfindTools
navigation() serves a tool named goToPage. A tool of your own with that
name beside navigation() throws when the route loads. See
Pages and highlights.
What not to build
| Do not build | Use |
|---|---|
| Documentation, policy, FAQ or error-table lookups | Knowledge. The agent searches it before it answers |
| Escalation to a person | The built-in handoff |
| Saving a name or email | The built-in save |
| Filing bugs or feature requests | Track bugs and suggestions and Signal, which can open issues in Linear or GitHub. See Issue trackers |
| Resolving or closing conversations | Resolve conversations automatically |
| Asking for a screenshot | The built-in screen capture |
| Asking the customer to sign in | The built-in sign-in ask, on your site |
| Reading the customer’s earlier conversations | The built-in search |
| Sending the customer to a page in your app | navigation() |
Build tools for live state in your own systems and the actions on it: an order, an account, a quota, a refund. See Custom tools and Examples.