# Set up your agent

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

The **Agent** tab has three pages in its sidebar, **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 page.

## 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](/articles/build-your-knowledge-base) and your
  [tools](https://docs.median.sh/agent/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 |
| --- | --- | --- | --- |
| **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 |
| **Preview replies** | On | Any | The closed widget shows the first lines of an unread reply |
| **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](#automatic-resolving) |
| **Learn from resolved conversations** | On | Standard or Pro | Each resolved conversation is reviewed for knowledge worth keeping and tools the agent was missing |
| **Suggest knowledge and tools** | On | Standard or Pro | The agent files knowledge and tool suggestions while a conversation is open |
| **Review the inbox nightly** | On | Standard or Pro | A nightly run resolves answered conversations that are still open |
| **Track bugs and suggestions** | On | Standard or Pro | The agent files bugs and ideas customers report to [Signal](/articles/triage-bugs-and-suggestions) |

- Your developer can also turn **Ask for an email** and **Preview replies** off in code. See [Support widget](https://docs.median.sh/components/support-widget).
- 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](https://docs.median.sh/components/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](/articles/manage-your-plan-and-credits#plans).
- Turning **Track bugs and suggestions** off also stops the
  [feedback panel](https://docs.median.sh/components/feedback) and
  [crash reports](https://docs.median.sh/components/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
  [Review](/articles/build-your-knowledge-base#review) and tools go to
  [Suggested tools](#suggested-tools), where an admin or owner decides.
- For what each switch adds to the agent's built-in abilities, see
  [Built-in abilities](https://docs.median.sh/agent/built-in-tools).

### 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. Snoozed ones are skipped | 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** tab.
- 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.
- Both skip conversations where the agent is waiting on an answer from your
  team.
- **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](/articles/manage-your-plan-and-credits#plans).

## Tools

A tool is a function on your server the agent can call.
[Custom tools](https://docs.median.sh/agent/tools) shows how to write one. This page 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](https://docs.median.sh/agent/tools#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
[Approve tool calls and run tools](/articles/approve-tool-calls-and-run-tools).

### 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.

1. Press **Add endpoint**. With no endpoints yet, the button in the empty list
   reads **Add an endpoint**.
2. Enter the URL. A missing scheme becomes `https://`, or `http://` for
   `localhost` and `127.0.0.1`.
3. 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](https://docs.median.sh/agent/troubleshooting) |

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](https://docs.median.sh/agent/running-tools).

| 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](/articles/manage-workspace-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](https://docs.median.sh/agent/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. Home shows
each one as a **Suggested tool** item too, with **Dismiss**, **Mark as built**
and **Copy prompt**. See
[Home](/articles/find-your-way-around-the-dashboard#home).

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](#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 is written for a coding agent. It describes the tool, says
which risk level it needs, and carries a `median.config.ts` starting point and
the safety rules the tool has to follow. Hand it to your developer, or paste
it into a coding agent. See [Custom tools](https://docs.median.sh/agent/tools).

To stop new suggestions, turn off **Suggest knowledge and tools** and
**Learn from resolved conversations** on [Behavior](#behavior).