Agent

The agent's profile, what it does on its own, and the tools it can call in your product.

Updated Oct 1, 20269 minute read

The Agent page has three tabs, Profile, Behavior and Tools. Everyone in the workspace can open them. Only admins and owners can change anything. Members see Only admins and owners can change these settings. at the top of each tab.

Profile

Field	Accepts	Default	Saves
Picture	PNG, JPEG, WebP, GIF or AVIF, up to 4 MB	None	As soon as you pick or remove one
Name	2 to 40 characters. Repeated spaces collapse to one	`Median AI`	On Enter, or when you click away. Escape puts the saved name back
Personality	Up to 2,000 characters	Empty	When you click away. Saved appears once it lands

The name and picture appear on the agent's replies in the widget and the inbox.
The agent uses the name in every channel, including email and Discord.
The personality sets tone and style. The agent reads it on every reply. Facts still come from your knowledge and your tools.
Changes reach the widget without a redeploy.
A member viewing an empty personality sees No instructions added.

Error	Cause
`Enter an agent name.`	The name is empty
`Use at least 2 characters for the agent name.`	The name is one character
`Use 40 characters or fewer for the agent name.`	The name is too long
`Keep personality instructions to 2000 characters or fewer.`	The personality is too long
`Choose a PNG, JPEG, WebP, GIF, or AVIF image.`	The picture is not one of those types
`Choose an image no larger than 4 MB.`	The picture is over 4 MB
`We could not upload that picture. Check your connection and try again.`	The upload did not reach Median

Behavior

Switch	Default	Plan	What it does	Widget prop
Ask for an email	On	Any	The widget asks for an email before a visitor's first message. A visitor you pass an email for is never asked	`requireEmail={false}`
Preview replies	On	Any	The closed widget shows the first lines of an unread reply	`messagePreview={false}`
Resolve conversations automatically	On	Standard or Pro	The agent resolves a conversation once it is answered, and closes spam and dead ends. See Automatic resolving	None
Learn from resolved conversations	On	Standard or Pro	Each resolved conversation is reviewed for knowledge worth keeping and tools the agent was missing	None
Suggest knowledge and tools	On	Standard or Pro	The agent files knowledge and tool suggestions while a conversation is open	None
Review the inbox nightly	On	Standard or Pro	A nightly run resolves answered conversations that are still open	None
Track bugs and suggestions	On	Standard or Pro	The agent files bugs and ideas customers report to Signal	None

A switch saves as soon as you flip it. If the save fails, it flips back and the row shows the error.
A widget prop can only turn its feature off. When either the switch or the prop is off, the feature is off. See Support widget.
The five AI switches need Standard or Pro. On Explore the page shows Available on Standard and Pro. A switch that is off cannot be turned on there. See Plans.
Turning Track bugs and suggestions off also stops the feedback panel and crash reports from filing anything. Reporters of existing signals still hear back when a signal is marked Done.
Nothing the agent learns is published on its own. Knowledge goes to Suggested knowledge and tools go to Suggested tools, where an admin or owner decides.
For what each switch adds to the agent's built-in abilities, see Built-in abilities.

What feeds the suggestion queues

Source	Switch	When	Cap
The agent, mid-conversation	Suggest knowledge and tools	When a conversation teaches it something or a customer needs a tool it lacks	3 knowledge suggestions and 2 tool suggestions per conversation
The review after resolve	Learn from resolved conversations	About 8 seconds after a conversation is resolved. Closed conversations are never reviewed	3 knowledge suggestions per review. The 2 tool suggestions per conversation are shared with the agent

The review reads the last 80 messages. It skips conversations with no customer message, and conversations it already read with nothing new since. Resolving again after new messages starts a new review.

Automatic resolving

Three things can end a conversation without a teammate.

	The agent	Auto-resolve	Nightly review
Started by	The agent, at the end of its own reply	Anyone in the workspace, from the wand in the inbox queue header	A daily run at 00:30 UTC
Switch	Resolve conversations automatically	None. It runs regardless of the switches	Review the inbox nightly
Reads	The conversation it is answering	Up to 100 open conversations, most recently active first. The last 40 messages of each	Up to 50 open conversations quiet for at least 1 hour, oldest first. The last 30 messages of each. Snoozed ones are skipped
Can resolve	Yes, after a goodbye line	Yes	Yes
Can close	Yes, for spam, bots, abuse and messages with no question in them	Yes, for conversations that need no reply	No
When unsure	Leaves it open	Leaves it open	Leaves it open
Thread line	`{agent name} marked this resolved`	`Auto-resolve marked this resolved`	`The nightly review marked this resolved`

Closing writes ... closed this conversation in the same way.
Auto-resolve asks first with Auto-resolve the inbox? Its button is hidden in the Archived view.
One Auto-resolve run at a time per workspace. A second start fails with An inbox review is already running. Wait for it to finish. The wand's tooltip reads Reviewing conversations while it runs.
For Auto-resolve and the nightly review, a new message that arrives while a conversation is being judged cancels the verdict for it.
Auto-resolve and the nightly review never reply. None of the three archives or deletes a conversation.
All three use AI, so they need Standard or Pro and credits. See Plans.

Tools

A tool is a function on your server the agent can call. Custom tools shows how to write one. This tab lists what Median synced from your endpoints.

The tool list

Each row shows the tool's icon, name and a one-line summary. Median writes a name, summary and input labels for each new tool, and again when a tool's description or inputs change. The list reads Writing tool descriptions... while it does. Until then, a row shows the function name split into words, such as Issue refund for issueRefund, and the tool's own description.

Click a row to expand it.

Detail	Shows
Inputs	Each input with its type, `required` when it is, and the allowed values for a choice. Types are Text, Number, Whole number and Yes or no. A tool with no inputs shows No inputs required.
Run permissions	What the risk level means for the agent
Small print	The function name, and for admins the endpoint URL

The badge on a row comes from the tool's risk level. See Risk levels.

Risk	Badge	Run permissions line
`low`	None	The agent can run this without approval.
`medium`	Agent asks first	The agent asks the customer before running this.
`reviewed`	Requires review	The agent asks the customer first, then a review checks the call. Uncertain requests go to a teammate.
`high`	Team approval, in red	Requires a teammate to approve the request in the conversation.

Deciding those requests happens in the inbox. See Approvals and tool runs.

Turn a tool off

The switch on each row turns one tool on or off without touching your code. Off removes it from the agent's next turn onward.

A newly synced tool arrives switched on.
Later syncs keep the switch where you left it.
A tool that disappears from your manifest is deleted. If it comes back, it arrives switched on.
Members see no switches.

Endpoints

Endpoints lists the URLs Median syncs your tools from. Only admins and owners see it.

Press Add endpoint. With no endpoints yet, the button in the empty list reads Add an endpoint.
Enter the URL. A missing scheme becomes https://, or http:// for localhost and 127.0.0.1.
Press Add endpoint. Median syncs it straight away.

Each endpoint shows a status dot and a status line. The dot pulses while a sync runs, turns green after a good sync and red after a failed one.

Status line	Means
`Syncing`	A sync is running
`3 tools · synced 5m ago`	The last sync worked
`Not synced yet`	No sync has finished
`Sync failed: ...`	The last sync failed. See Tool errors

The Endpoint options menu on each row:

Item	Does
Sync	Reads the manifest again now. Up to 10 in a burst and 60 an hour per workspace. Past that, the status line reads `Too many requests. Wait a moment and try again.` until the next sync, and the last sync's result stands
Change endpoint	Opens Change endpoint. Saving syncs the new URL
Remove endpoint	Asks Remove this endpoint?, then deletes the endpoint and its tools. Requests for those tools that wait on a teammate or on review expire, with a line in each conversation

Median also syncs on its own. See How tool calls run.

Error	Cause
`Enter a valid URL.`	The URL does not parse
`Use an HTTPS URL, or HTTP on localhost for testing.`	Plain HTTP on a public host
`That address points inside a network, not at the internet.`	A private or internal address
`Endpoint URLs have to be 512 characters or fewer.`	The URL is too long
`An endpoint with this URL is already connected.`	Change endpoint was given a URL another endpoint already uses. Adding a URL that is already connected syncs that endpoint again instead
`You can connect 10 tool endpoints at once. Remove one before adding another.`	The workspace has 10 endpoints
`Create a Median key in Settings under API before connecting tools. That key belongs in MEDIAN_KEY on your server.`	The workspace has no Median key. See Settings

Empty states

Message	Seen by	Means
Export your tools with median(), then point Median at the route.	Admins	No endpoint yet. The Tool setup guide link opens Custom tools
No tools were found during the last sync.	Admins	Endpoints exist, but the last sync returned no tools
The agent has no tools yet.	Members	No tools

Suggested tools

Suggested tools sits above the tool list when a suggestion is waiting. It shows a count and the newest 50. Only admins and owners see it. The dashboard lists the same suggestions under Suggested tools. See Overview.

The agent files a suggestion when a customer needs something done that no tool can do. The review after resolve files them too. See What feeds the suggestion queues.

The card

Hover or tab into a card to expand it.

Part	Shows
Title and age	What the tool would do, in a few words
`From "{subject}"`	A link to the conversation it came from
Summary	One line about the tool
Why	What the customer needed that the agent could not do
Proposed behavior	What the tool should do when called
Inputs	Up to 8 inputs, each Text, Number, Yes or no or Choice, with `required` when it is
Use case	When the agent should call it
Run permissions	The suggested risk level, as the same line the tool list shows. Suggestions are `low`, `medium` or `high`. `medium` when none was given
Small print	The suggested function name, such as `issueRefund`

Actions

Button	Does
Dismiss	Removes the card
Mark as built	Removes the card. Press it once the tool ships. Median does not match it to a synced tool
Copy prompt	Copies a build prompt for a coding agent

A settled suggestion stays on record. A new suggestion with the same title, in any conversation, is not filed again, whether the first was pending, built or dismissed. A second person settling the same card gets This suggestion has already been reviewed.

The copied prompt contains:

The tool name, summary, why, behavior, inputs, use case and risk level.
A median.config.ts snippet with the tool's description, risk and input fields, and an execute body left as a TODO.
An instruction to add it beside your existing tools.
Notes to return a small object of facts, and to throw a readable error when the work cannot be done.
A rule to use context.visitor.externalId only when context.visitor.verified is true.
A rule to use context.toolCallId as an idempotency key for anything that changes state or moves money.
A reminder to open the route once after deploying so Median syncs it, and a link to Custom tools.

To stop new suggestions, turn off Suggest knowledge and tools and Learn from resolved conversations on Behavior.

Still need help?

Message us Share an idea