Set up a model provider
Mole Agent needs a model provider before a chat can answer. An administrator withagent.manage adds one:
- Open Mole Agent → Settings → Models & reasoning and select Add model provider.
- Choose the Provider type: OpenAI, Anthropic, or an OpenAI-compatible endpoint.
- Enter a Display name, the Default model, and the API key. The key is write-only, and the page and the API never return it.
- Set the Base URL for an OpenAI-compatible endpoint. Leave it empty to use the official endpoint of OpenAI or Anthropic.
- Adjust No-response timeout and Max output tokens when the provider default does not fit. Choose the Currency and fill in the prices to see cost in usage, then save.
Retry-After asks when the provider sends it; retries happen only before an answer arrives. An Anthropic provider without Max output tokens uses 4096.
Prices are per million tokens, in the provider’s Currency, the same for every model of the provider: Input price, not cached, Input price, cached for input the provider serves from its cache, and Output price. Fill in the cached price only for a provider that bills cache hits apart; otherwise all input costs the price not cached. Leaving the prices empty only skips the cost; usage and budgets work the same.
The currencies to choose from are kept under Currencies, below the model providers. An administrator adds one by its ISO 4217 code, with a name and symbol when the standard ones do not fit. A currency that a model provider uses cannot be deleted, and costs recorded in a deleted currency still show in it.
Model calls go through the Model Gateway. Leave an existing key field empty while editing to keep the saved key, or enter a value to rotate it. The environment variables MS_AGENT_OPENAI_API_KEY, MS_AGENT_ANTHROPIC_API_KEY, and MS_AGENT_COMPATIBLE_API_KEY are a development fallback. See Configuration.
Chat
Open Mole Agent → Chat, choose an available model, set the time range, and describe the symptom. Pin a service, alert, environment, or stream as investigation context. While no AI model is enabled, the chat says so above the message box. An administrator withagent.manage follows the link there to Models & reasoning.
The response can include:
- a plain-language conclusion;
- tool calls and evidence summaries;
- links to source logs, metrics, traces, or incidents;
- token and model-cost metadata (cost appears when the model provider has prices);
- a prompt template version and content hash for reproducibility.
Write a message
The message box reads as it will be sent:- starts a list, 1. a numbered list, # a heading, > a quote, [ ] a task, and ``` a code block, while **bold** and `code` format as you type. Enter sends. In a list or a code block, Enter goes on with it, and Enter on an empty item leaves the list; ⌘ Enter or Ctrl Enter sends from anywhere. Shift Enter starts a new line. Pasted Markdown keeps its formatting; paste as plain text (⌘ Shift V or Ctrl Shift V) to keep the text as it is. The message goes out as Markdown.
Execution modes
The mode under the message box sets what Mole Agent may run in the chat. While its menu is open, the numbers 1 to 5 pick a mode.
In every mode, a change that the organization’s tool policy sends for approval still goes to its approvers, and a disabled tool stays disabled. Bypass permissions is offered only when the chat’s agent profile allows it with Allow Bypass permissions under Approval policy, and asks for confirmation before it is on. If the profile stops allowing it while a question waits its turn, that answer asks before each change and says so.
Chat names
A new chat is named while its first question is answered: a few words on what the chat is about, in the language of the question, the way ChatGPT and Claude name a conversation. A greeting has nothing to name yet, so the chat keeps its first words until a question with a subject comes. A chat is named once. Select the pencil beside a chat in the list to rename it: Enter keeps the name and Esc leaves it, and Mole Agent no longer names that chat. Memories show the chat they came from by its current name. Naming counts toward model usage like any other call.Personal and team chats
A chat is personal unless a team is chosen for it before its first message. Choose one in Team under the message box, or type/team <team>. The list offers the teams a person is in, and every team to a holder of agent.manage. A chat keeps its team once its first message is sent.
Tools always run as the person who sent the message, with that person’s permissions and own credentials. In a team chat, a question from someone else shows that person’s name. In a personal chat, calling a skill or an MCP prompt of one of the person’s teams brings that team’s skills and MCP servers into the chat for the rest of it. The chat list marks team chats with their team; once there are team chats, All, Personal, and Team filter the list.
Slash commands
Type/ at the start of the message box to open the command menu; keep typing to filter by name or description. Use ↑ ↓ to choose, Enter to run, Tab to complete without running, and Esc to close the menu. Once a command that takes an argument is completed, the menu lists the arguments to choose from. Commands work on the chat page and in the Mole Agent panel that ⌘J opens anywhere.
/query, /dashboard, and /rca go out as a message: the chat shows the command as a label followed by its argument, and regenerating runs the same command again. The mode of /query applies to that message only. /rca looks from 30 minutes before the incident started to when it ended, or to now while it is still open. The other commands only change the settings of the message box and send nothing.
When a command does not exist, misses its argument, has a wrong argument, or needs a permission you lack, it is not sent and the reason appears above the message box. To send plain text that starts with /, write \/ at the start; the backslash is removed when the message is sent. A path with a second slash, such as /var/log/app.log, goes out as plain text.
Skills and MCP prompts are commands too, under Skills and MCP in the menu:
/name [request]runs a skill the chat can use. When skills of two teams share the name, write/name@team; in a personal chat this also brings the team in./<server>:<prompt> [arguments]gets a prompt from an MCP server with the sender’s own credential and sends it as the question. Arguments are filled in order, the last one taking the rest of the text, or by name asname=value; quote a value that holds spaces.
Knowledge and memory
Open Mole Agent → Knowledge. Knowledge holds the Markdown files that chats read: the organization’s and each team’s. Start withMOLE.md as the entry and point to other files with @path, or run /init to have Mole Agent look at what is set up, ask a few questions, and write each file once you confirm it. Holders of agent.manage change the organization’s knowledge, and members change their team’s.
- New makes a file, or a folder for its first file; a path such as
runbooks/api.mdmakes the folder and the file at once. - Upload takes files or a whole folder.
- A file opens in Preview. Edit shows the file as it reads while you write, the same way the message box does, and Source edits its Markdown. A file with Markdown that the editor would not keep, such as an HTML comment, is edited in Source.
- AI opens a chat that changes the file for you.
agent.manage turns on, the model picks what is worth remembering half an hour after a chat stops, using the organization’s model budget.
Investigations
Turn a complex question into a tracked investigation. An investigation records:- status and current step;
- evidence and the resulting effect on the conclusion;
- competing hypotheses and confidence;
- related chat, approvals, and executions;
- the final summary and recovery verification.
Automations
An automation has Mole Agent do a job with nobody in the chat: on a schedule, for each new incident, when a CI/CD job calls, or by hand. Each run is kept as a chat, and its result can go to notify channels and, for an incident, become the incident’s RCA. See Automations.Quality
Every answer is scored by rules; evaluators the organization sets up score a sample of them with a model, and low scores and unhelpful ratings wait for review on the Quality tab. An organization prompt for chats or RCAs is checked against the present default before it becomes the default. See Quality.IM
Mole Agent also answers in Feishu, Slack, DingTalk, WeCom, Google Chat, and Microsoft Teams through a connector: mention it in a group or message it directly, and the chats there also appear here. See Mole Agent in IM.Approvals and executions
Write-capable tools never bypass the server execution policy.
An approval stores the proposed operation and expires after the policy window. Before execution,
the server revalidates permission, resource state, parameters, risk, and idempotency. The execution
record keeps outcomes and recovery verification.
Log inspections
Mole Agent also reads a log stream and writes a report about it, once from Logs or on a schedule in the background. A scheduled inspection keeps every report and notifies when a report says something is wrong. See Log inspections.Skills
A skill is a folder holding aSKILL.md: instructions for one kind of task, in the open Agent Skills format, and the files they refer to. Mole Agent sees the names and descriptions of the skills a chat can use, reads the instructions of a skill when a request fits it, and reads its other files when the instructions point to them. Every skill is also a slash command.
The built-in skills include
/init, which writes the knowledge, /insight, which looks back at how Mole Agent was used and what to improve; see Automations, and /rum-triage, which triages a problem real users have from the overview of a RUM application to its issues, sessions, and traces. A holder of agent.manage can turn built-in and instance-folder skills off for the organization. When skills share a name, a chat takes the person’s own first, then the team’s, the organization’s, the instance folder’s, and the built-in one. The instance folders are read at startup and again whenever their files change; see Configuration.
Write a skill
SKILL.md starts with YAML frontmatter:
In the instructions,
$ARGUMENTS stands for the text after the command and $1 to $9 for its words. Without them, the text follows the instructions.
A package is a .zip, .skill, or .tar.gz of up to 20 MiB with one skill folder in it: at most 300 files and 20 MiB unpacked, 8 MiB per file. Links and paths that leave the folder are refused. Uploading a skill with a name already taken in the scope asks before replacing it. Try in a chat in the skill detail opens Mole Agent with the command typed.
Skill repositories
A repository is read from a branch or a tag, downloaded as one archive. Each folder holdingSKILL.md, in the whole repository or under the Folder given, is a skill; a repository holds at most 50 skills in an archive of up to 64 MiB. GitHub, GitLab, Gitea and Forgejo, and Bitbucket are read from the address; for another host, give an archive address with {ref} in it. A private repository needs an access token, which is write-only.
Saving a repository synchronizes it once. Synchronize does it again, and Synchronize every day keeps it current. A synchronization adds, updates, and removes the repository’s skills and lists the folders it could not import, with the reason. Deleting a repository removes its skills.
Organization, team, and personal resources
Skills, skill repositories, and MCP servers belong to the organization, a team, or one person. Belongs to sets it when one is added, and an editor can move a resource to another scope that the editor manages.
A team that still has skills, repositories, or MCP servers cannot be deleted: Identity & Access → Teams names them, so move or delete them first.
Repositories and MCP servers added by teams and individuals reach only the public internet, plus the internal hosts and ranges a holder of
agent.manage lists in Mole Agent → Settings → Network policy → Internal network for team and personal connections. They always verify TLS certificates. Organization repositories and servers follow their own settings.
Agent settings
Open Mole Agent → Settings. The sections stand as a row under the Mole Agent tabs:
Credentials remain encrypted and are never returned by the API.
Tools & capabilities
Tools are listed in groups by product domain. The groups are folded when the section opens. Unfold a group, or search to open the groups that hold a match. The filters All, Read-only, Automatic, Approval, and Disabled each show how many tools they hold. A tool shows its title and description in the interface language. The tool detail also shows the definition that the model is given, which is English in every interface language.MCP servers
Open Tools & capabilities → MCP Servers to add a server, test it, and import its tools. Each server shows whose it is. Members manage personal and team servers here too.
Test connection lists the server’s tools. Sync selected tools imports the chosen ones: new tools stay off until someone turns them on, and their risk floor follows the server’s annotations. Tools and prompts shows the tools with a switch each, and Enable all read-only tools turns on the read-only ones at once; tool policies and approvals still apply. The prompts a server offers become commands written
/<server>:<prompt>.
About every hour, Mole Agent checks each synchronized server again. A tool whose input schema changed, that the server no longer lists, or that the server now marks as riskier becomes unavailable until someone reviews it and synchronizes again. Servers that take member credentials are left out of this check.
Import takes the MCP configuration of Claude Desktop, Claude Code, Cursor, or VS Code and adds its servers. Values that refer to variables, such as ${input:token}, are not imported and are listed to fill in. A server with a command is a stdio server: it is imported only into the organization, and only with a command the instance allows.
On a server that takes member credentials, Add my credential saves the member’s own value. When a chat calls one of its tools without that value, or the server turns down the saved one, the answer waits on an Authorize to continue card that says which tool needs it and shows the server’s instructions. Save and continue saves the credential, as Add my credential does, and runs the tool again; Skip leaves the server out of the rest of that answer. Only the person who asked can fill in the card, since the credential is theirs; others in a team chat see whose turn it is. The card waits up to an hour. Where nobody can be asked, the tool answers that the credential is missing, and Mole Agent asks the member to add it.
Prompt management
A built-in prompt is read-only and appears under its name in the interface language. Select Create override on a built-in prompt to replace it for the organization or for one user. Setting an organization prompt for chats or RCAs as the default goes through the organization’s check first; see Quality.Run limits of an agent profile
These apply to each chat answer that uses the profile. Without an active profile, the defaults apply:
Once the tool calls or the time are used up, Mole Agent stops calling tools and answers with the results it already has.
Usage and budget
Open Mole Agent → Settings → Usage to see the organization’s token usage today, its daily budget, and the usage of the last 30 days. Usage counts per UTC day; a token count is input plus output. These sources count:
When model providers have prices, the page shows cost too, in each provider’s currency. Costs in different currencies are shown apart and never added up. Calls to a model provider without prices add no cost, and an amount that leaves such calls out is marked ≥: the real cost is at least that much.
The daily budget defaults to the instance setting
[agent].daily_token_budget (0 means no limit). See Configuration. An administrator with agent.manage can give the organization a Custom limit or No limit, and choose what chats and on-demand analyses do once the budget is used up:
Once the budget is used up, automatic root cause analysis, log inspections, and LLM functions stop calling the model: an inspection run fails with the budget as its reason, automatic analyses wait until the budget resets, and an LLM function step fails. When usage reaches the warning threshold (80% by default,
[agent].budget_warning_percent), the chat says so above the message box. The budget is checked against a status cached for about fifteen seconds, and an answer under way is not cut off, so usage can end up slightly above the limit.
Each model call also writes a row to the internal stream _agent_model_traces, which you can query in Logs. Common fields are origin (chat, rca, inspection, llm_eval, automation, evaluation), provider, model, prompt_tokens, cached_prompt_tokens (the part of the input the provider served from its cache), completion_tokens, total_tokens, latency_ms, cost, cost_currency, status, error, tool_calls, streaming, chat_id, user_id, profile_id, and prompt_hash. cost and cost_currency are written only when the model provider has prices. user_id is who the call counts for: the person who asked in a chat or the run-as user of an inspection; calls for root cause analysis and LLM functions have no such field.
Data handling
Mole Agent sends the conversation to the configured model provider, including the results of the tools that it calls. With no provider configured, nothing leaves the deployment. These controls limit what the agent can reach:- Data access limits the environments, services, and streams that the default profile can read. Cross-organization access is always forbidden.
- Network policy decides whether the profile can use tools that need the network. New profiles block networking. Arbitrary HTTP, shell, browser, and open MCP tools are not enabled by this switch.
- Approval policy requires approval for write operations by risk level, and decides whether chats using the profile may pick Bypass permissions.
- Skills and MCP servers add instructions and tools without widening the policy: a skill’s allowed tools and every MCP tool keep the organization’s execution modes and approvals.
Permissions
agent.useopens chat, investigations, automations, and execution history, shows usage, and rates answers and analyses. It also adds personal skills, repositories, and MCP servers, and manages those of the person’s teams.agent.manageconfigures providers, prompts, tools, profiles, workflows, the daily budget, and the organization’s skills and MCP servers. It also opens the Quality tab: scores, reviews, and evaluators.agent.automations.managecreates, changes, and runs automations; see Automations.agent.approvereviews controlled operations.
Inbound MCP
Connect Codex and other external AI clients to the governed runtime.
Tool catalog
Review discovery, IAM, risk policy, approvals, and execution behavior.
Log inspections
Have Mole Agent inspect a log stream on demand or on a schedule.
Alerting
Start an investigation from an active incident.