Execution & Coding
Use these tools to inspect and edit files, run shell commands or Python, manage Docker resources, do exact arithmetic, and generate files and charts.
Tools On This Page
- [
filesystem] - Line-numbered reads, precise edits, writes, grep, file discovery, directory listing, and opt-in deletes;fileandcodingare other names for it. - [
shell] - Shell commands with time limits, environment passthrough, and PATH prepends. - [
terminal] - Persistent terminals beside the agent's shell commands, which people in the room can watch and type in when the agent's config allows it. - [
temporary_secrets] - Ask the user for a password, token, or code that the agent's shell commands receive and the agent never sees. - [
python] - Python code execution and package installation. - [
shared_directories] - Directories an agent creates and invites other agents to read. - [
docker] - Docker container, image, volume, and network management. - [
calculator] - Exact arithmetic without code execution. - [
reasoning] -thinkandanalyzescratchpad steps. - [
file_generation] - JSON, CSV, PDF, DOCX, HTML, text, and source-code file exports. - [
visualization] - Matplotlib charts. - [
sleep] - Intentional pauses.
Common Setup Notes
None of these tools needs credentials or dashboard setup; docker needs Docker daemon access in the runtime that runs it.
docker, file_generation, and visualization depend on the docker, reportlab and python-docx, and matplotlib packages, which install on first use unless automatic dependency installation is disabled.
Where these tools run
filesystem, shell, python, and docker run in a worker by default when a worker backend or sandbox proxy is configured, and reasoning always runs in the primary process.
Whether the other tools here also run in a worker depends on the execution mode.
Change this with defaults.worker_tools or agents.<name>.worker_tools, as described in Worker Routing.
worker_scope decides how worker runtimes are shared between agents and users; see Worker scopes.
With Agent Keys on, shell calls and worker-routed python calls of an agent with the egress_credentials tool can use stored API keys and connected accounts that the worker never sees.
Only a worker isolates shell, python, and docker, because they execute code and are never confined by the agent's file_access setting.
Workspace and tool output files
Every agent has a workspace: agents/<agent>/workspace/ in the storage directory, or the requester's private root for a private agent.
It is the working directory (base_dir) of filesystem, shell, and worker-routed python, and generated files and charts are saved inside it.
python in the primary process resolves its file functions against the workspace, but the code it runs uses the process's current directory, so relative paths such as open("data.csv") may miss workspace files.
base_dir is managed by MindRoom and cannot be set inline in config.yaml; a headless run can point it at a directory the caller chooses.
Supported tools also take an optional mindroom_output_path argument.
Set it to a workspace-relative file path to save the tool's full output to that file and return a short receipt to the model instead.
The path must name a file inside the workspace; absolute paths, .., paths that start with ~ or contain $ or %, symlinks, and paths inside a .git directory are refused.
Without mindroom_output_path, outputs larger than defaults.tool_output_auto_save_threshold_bytes (integer, at least 1, default 51200, which is 50 KiB) are saved under mindroom_tool_outputs/ in the workspace, and the model receives the path, size, format, a preview, and a note to read the file in parts, because reading it whole would only save it again.
MINDROOM_TOOL_OUTPUT_REDIRECT_MAX_BYTES sets the largest output either kind of save writes (default 64 MiB).
defaults:
tool_output_auto_save_threshold_bytes: 51200
agents:
code:
display_name: Code
role: Edit code, run local checks, and export artifacts
model: sonnet
tools:
- filesystem
- shell:
extra_env_passthrough:
- GITHUB_TOKEN
shell_path_prepend:
- /opt/custom/bin
- file_generation:
output_directory: exports
- visualization:
output_dir: charts
Here file_generation saves into exports and visualization into charts, both inside the agent workspace.
[filesystem]
filesystem provides read_file(), edit_file(), write_file(), grep(), find_files(), and ls(), and delete_file() when enable_delete_file is on.
The tool names file and coding select it too wherever a tool name is written anew, such as tools, worker_tools, MINDROOM_SANDBOX_PROXY_TOOLS, a new contact's tools, and subagent tools, and config saved through the dashboard or API writes filesystem.
An agent's tools and the defaults.tools it takes may name it by more than one of the three names only when none of those entries has settings and their defer and initial flags agree; it then stands where the first one stood, and otherwise the config fails to load, naming both entries.
What was saved under file or coding before the two became one toolkit is not carried over; see Upgrading to the filesystem toolkit.
read_file() returns line-numbered output with pagination hints when a file is truncated, and names an image it cannot decode instead of returning its bytes, pointing to view_file() when the agent has it.
edit_file() applies a list of edits to one file, each an old_text copied from the file and its new_text.
Every old_text matches the file as it was before the call, not the results of the other edits, and must match exactly one place unless its edit sets replace_all, which replaces every non-overlapping match from left to right, as Python's str.replace does; when it has no exact match, a match that differs only in whitespace and quotes is used.
Edits must not overlap, so an edit must not also target text that a replace_all edit's old_text matches.
When an edit fails validation, none is written: the error names the edit, lists the lines of an old_text that matches several places, and, for one that matches none, shows up to three distinct lines that come close, if any do.
A failure while writing the file is reported as a write error instead.
On success it returns the lines each edit changed in the new file, numbered as read_file() numbers them, not a diff; a match whose new_text equals the text it replaces is left out of those lines, though the edit still counts.
In a file whose lines all end in CRLF, old_text and new_text may use LF or CRLF and the file keeps CRLF, unless the file or an edit holds a lone CR; then, as with mixed endings, the file is matched and edited with its line endings as they are.
A byte order mark stays in the file once, also when an edit that starts at it copies it into old_text or new_text; any other U+FEFF is ordinary text.
In the primary, edit_file(), write_file(), and delete_file() calls on the same resolved path run one after another, so they never interleave; a later write_file() still replaces the whole file, an earlier edit included.
In a worker, calls serialize only when they lock the same stable, readable directory; one that waits too long for that lock returns a busy error without changing the file, and a directory the agent may enter but not read cannot hold the lock, so calls there run unlocked.
Primary and worker calls do not serialize with each other, with another primary, or with other writers such as shell commands.
grep() and find_files() skip gitignored paths and hidden paths below the directory they search, so naming a dot directory as the path searches it, and grep() still searches a file named directly as its path; ls() shows dotfiles and marks directories with /.
Under file_access: workspace, grep() skips a file over 64 MiB, which read_file() refuses to read.
delete_file() removes a file or an empty directory.
Paths follow the agent's file_access: workspace (the default) rejects paths outside the workspace and the agent's shared directories, and unrestricted allows any path the tool's process can reach.
write_file(), edit_file(), and delete_file() refuse paths inside a .git directory.
Configuration
| Option | Type | Required | Default | Notes |
|---|---|---|---|---|
enable_delete_file |
boolean |
no |
false |
Offer delete_file(); deletion is opt-in. |
Turn functions off with the toolkit filters every tool takes, for example exclude_tools: [write_file, edit_file] for an agent that only reads.
Example
read_file("src/app.py", offset=1, limit=120)
grep("TODO", path="src")
find_files("**/*.md", path="docs")
edit_file(
"docs/example.md",
edits=[
{"old_text": "old text", "new_text": "new text"},
{"old_text": "draft", "new_text": "final", "replace_all": True},
],
)
write_file("scratch/todo.txt", "first line\nsecond line\n")
ls("src")
delete_file("scratch/todo.txt")
[shell]
shell provides run_shell_command(), which accepts a shell command string or a list of argv strings.
It runs commands only in a worker unless defaults.allow_shell_without_worker: true lets them run in the MindRoom process; otherwise each call there is refused.
Command strings run through non-login bash -c; pass ["bash", "-lc", "command"] when login-shell startup files are needed, and use a multi-item argv list when exact argument boundaries matter.
The tool returns the last tail lines of stdout (default 100), then the last tail lines of any stderr under Stderr:, each capped at the last 50 KiB; on a non-zero exit, an Exit code <code> line comes first, followed by stdout under Output: and all of stderr under Stderr:.
When tail or the cap leaves lines out of a successful result, it starts with a notice for each stream that lost lines, such as [Showing the last 100 of 230 lines. Pass a larger tail, or narrow the command.] or [Showing the last 100 of 230 stderr lines. ...].
Blank lines count as lines in a notice and in the tail; output shown whole loses only its trailing newlines, and stderr of only blank lines still gets its Stderr: heading.
A result that leads with a status line keeps it first and puts the notice at the start of the stream it describes: Exit code <code> on a failure, Stopped after <timeout>s. at the timeout, and Status: FINISHED or Status: RUNNING when a background command is checked.
The command runs in the agent's workspace, or in its workdir, and the result holds only the command's output.
With mindroom_output_path, the complete output is saved to that file instead, and the receipt includes exit_code whenever the command exits non-zero or is killed, such as by the OOM killer, even when no file is saved; a command stopped at its timeout reports the stop instead.
A successful command saves its stdout alone, and when it also printed to stderr, the receipt gives its size as stderr_bytes; add 2>&1 to the command to save that text too.
A command still running after timeout seconds is stopped together with the processes it started, and the tool returns its output so far after Stopped after <timeout>s.; a stopped command saves no mindroom_output_path file.
Without timeout, a call that runs as a background job has no time limit, even while the reply waits for it, and any other command stops after 120 seconds.
While a job's command runs, job(action="list") shows the last lines of its output, and cancelling the job stops the command.
A command that exits non-zero still returned its result, so its job ends completed; its summary in job(action="list"), the first 500 characters of that result, includes the Exit code <code> line, or, with mindroom_output_path, is the receipt with its exit_code.
A process started with nohup cmd > out.log 2>&1 & keeps running after its command ends on its own, but not after a stop; only a process started in its own session, such as with setsid, survives a stop.
For how stopping a response and worker restarts affect running commands, see Stopping and background commands.
Worker-routed shell sees only a small default environment; which variables pass by default and which extra_env_passthrough never passes are listed in Shell environment and PATH.
Configuration
| Option | Type | Required | Default | Notes |
|---|---|---|---|---|
enable_run_shell_command |
boolean |
no |
true |
Enable run_shell_command(). |
all |
boolean |
no |
false |
Enable all shell functions. |
extra_env_passthrough |
text or string[] |
no |
null |
Additional exported process environment variable names or glob patterns passed to shell commands; comma- or newline-separated in text form. It matches the exported process environment, not entries in the config's .env file. |
shell_path_prepend |
text or string[] |
no |
null |
Directories prepended to PATH for shell commands only, with duplicates removed; comma- or newline-separated in text form. |
Example
agents:
ops:
tools:
- shell:
extra_env_passthrough:
- GITHUB_TOKEN
- INTERNAL_API_*
shell_path_prepend:
- /run/wrappers/bin
- /opt/custom/bin
run_shell_command("git status --short", tail=50)
run_shell_command(["git", "status", "--short"], tail=50)
run_shell_command(["bash", "-lc", "make test"], timeout=900)
run_shell_command("nohup npm run dev > dev.log 2>&1 &")
Per-workspace environment
An agent can set its own environment variables for worker-routed shell and python, such as PATH entries, npm prefixes, or package indexes, by exporting them from .mindroom/worker-env.sh in its workspace.
The hook's behavior, limits, and the variables it cannot override are described in Workspace env hook.
mkdir -p .mindroom .local/bin .cache/npm
cat > .mindroom/worker-env.sh <<'EOF'
export NPM_CONFIG_PREFIX="$PWD/.local"
export NPM_CONFIG_CACHE="$PWD/.cache/npm"
export PATH="$PWD/.local/bin:$PATH"
EOF
[terminal]
terminal gives an agent persistent terminals: interactive Bash shells in its workspace that keep running between calls, which people in the room can watch live and type in from a chat client that shows terminals, as far as the agent's terminals setting allows.
Use it for work people should see or that keeps state between commands, such as a dev server, a REPL, an interactive program, or a long build.
terminal_open(cwd)opens a terminal incwd, a folder of the workspace, by default the workspace itself.terminal_run(session_id, command, timeout_s)types one command line while the shell waits at an empty prompt, waits up totimeout_sseconds (default 30, at most 600) for its next prompt, and returns the output and exit status; a command still running then keeps running.terminal_send(session_id, keys)types text and named keys, such as<enter>,<tab>,<up>, and<ctrl-c>, without waiting for a command;<ctrl-c>goes on its own, since the terminal may drop keys typed right after it.terminal_read(session_id)returns the terminal's recent output as text.terminal_list()lists the workspace's terminals, including the ones people opened.
An agent has terminals only when it also has [shell] with run_shell_command and that shell runs in a worker; otherwise it is offered none of these functions.
A terminal runs in that worker with the environment and workspace of the agent's shell commands, except that it never gets the response's mindroom-agent CLI access, because it outlives the response.
It also starts with INPUTRC=/dev/null, so it and the readline programs started in it keep their built-in key bindings and read no readline settings, such as a ~/.inputrc in the workspace.
Everyone whose turns reach the same agent workspace in the same worker shares its terminals.
With terminals: type, people who may post messages in the room type in them where the worker mounts the agent's workspace, a dedicated Docker or Kubernetes worker or a static_runner with MINDROOM_STATIC_RUNNER_AGENT_STORAGE; everyone else who may use the agent watches.
After keys typed while a command runs, such as an answer to its prompt, terminal_run refuses until the agent sends <ctrl-c> at the prompt that follows, and inside a shell started in the terminal, such as bash or nix-shell, it refuses until that shell exits, so the agent types into it with terminal_send.
A terminal ends 30 minutes after its last input while nobody watches, and when its worker stops.
An agent types in terminals only while its run_shell_command calls never ask for approval: the first approval rule that matches run_shell_command is auto_approve, or no rule matches and tool_approval.default is auto_approve; a rule with an approval script counts as one that may ask.
Otherwise the agent is offered only terminal_read and terminal_list, and its instructions tell it to run commands with run_shell_command; people the agent's terminals setting lets type still type in the terminals.
The rules can't judge typing into a terminal, because what a line runs there depends on what ran in it before, such as aliases, functions, shell options, and programs reading the keys.
[temporary_secrets]
temporary_secrets lets an agent ask for a secret that a shell command needs and that the agent must not see, such as a sudo password, a token for a host without an Agent Keys service, a passphrase, or a pairing code.
It provides request_temporary_secret(name, reason), where name is the environment variable the commands should receive and reason is what the user reads on the card.
The agent can also give a label that says what the secret is, the url of a page where the user gets or creates it, and a placeholder for the empty field.
- MindRoom Chat shows the requester a card with the reason, the variable, and a masked field. Other people in the thread see who the card waits for.
- A
labelbecomes the card's title and aplaceholderthe hint in the empty field, each cut to one line of 80 characters. Aurlbecomes a button that names the page's host and opens it in the browser, and it must be anhttporhttpslink with a host, nouser:password@part, and no spaces. The agent chooses the link, so the user should check the host on the button before signing in there. - The requester chooses how long MindRoom keeps the value: 15 minutes in the memory of the MindRoom process, which is the default, or 24 hours, for which MindRoom also writes it to a file that only its own account can read, under
temporary_secrets/in the storage directory. A restart forgets a value kept in memory and reads back one kept in a file. The file is deleted at the first tool call or answer after the value expired. - Chat sends the value to this MindRoom's API with the user's client session, so it never goes through Matrix or the model.
- While it is kept, the value is the environment variable
nameof that agent'sshellcommands (run_shell_command) in the same room and thread, in turns of the same requester, whether they run in the MindRoom process or in a worker. MindRoom gives it to no other agent, conversation, or person's turn, and not to a [terminal], whose shell would keep it past its lifetime. In a worker that several people's turns share, another person's command can still read the environment of a command while it runs, and a process that a command leaves running keeps the variable for as long as it runs. - The tool returns
providedwith the minutes the variable stays set,declined, orexpiredwhen no answer came in 15 minutes. It waits, stops, and continues as a background job the wayrequest_secretdoes, and needs the same access for Chat: its origin inMINDROOM_COMPUTER_ALLOWED_ORIGINSand a homeserver that binds OpenID tokens to this deployment.
Unlike an Agent Keys key, a temporary secret reaches the agent's commands, so a command can print it or send it elsewhere.
MindRoom tells the agent to use the variable only inside the command that needs it, and replaces exact copies of the value in tool results and in the output a running command shows, before the model or the room reads them, but neither stops an agent that works around them.
What a command prints can also end up in the agent's workspace, in a file the command writes or in the file MindRoom saves a large result or a mindroom_output_path result to; those files hold the output as the command printed it.
Give the tool to agents you would trust with the secret, and prefer an Agent Keys service for an API key that a service's hosts take in a header.
[python]
python provides run_python_code(), save_to_file_and_run(), run_python_file_return_variable(), pip_install_package(), uv_pip_install_package(), read_file(), and list_files().
It runs arbitrary code, so its file functions are never confined to the workspace and it always has unrestricted file access; isolate it with worker_tools.
Both install functions install into the interpreter running the tool, which is the worker's environment when python is worker-routed.
Worker-routed code can import modules saved in the workspace, but installed and standard-library modules take precedence over same-named workspace files, and user site-packages under the workspace home are not loaded.
Example
run_python_code("total = sum(i * i for i in range(10))", variable_to_return="total")
save_to_file_and_run("scripts/demo.py", "result = 6 * 7", variable_to_return="result")
run_python_file_return_variable("scripts/demo.py", variable_to_return="result")
pip_install_package("rich")
[shared_directories]
shared_directories lets an agent create a directory, write files into it, and invite other agents to read them.
It provides create_shared_directory(name), invite_to_shared_directory(name, agent_name), remove_from_shared_directory(name, agent_name), delete_shared_directory(name), list_shared_directories(), accept_shared_directory(owner, name), and decline_shared_directory(owner, name), and has no configuration fields.
Setup
- Run tools in dedicated Docker or Kubernetes workers.
Set the environment variable
MINDROOM_WORKER_BACKEND=dockeras in dedicated Docker workers, or the runtime chart's Helm valueworkers.backend: kubernetesas in Kubernetes dedicated worker mode. Sharing also works without workers and with the Kubernetesstatic_runnersidecar, with weaker limits; see Access by deployment. - Give the sharing agent
shared_directoriesand a tool that writes files, such asshellorfilesystem. - Give each reading agent
shell,python, orfilesystem. It also needsshared_directoriesto accept invitations from users who cannot use it, as in Sharing between personal agents. - When the user who asks for the invitation can use the reading agent outside the current room, the invitation applies at once, as described under Rules; in the example below, every member of
lobbycan.
agents:
researcher:
display_name: Researcher
rooms: [lobby]
tools:
- shell
- shared_directories
writer:
display_name: Writer
rooms: [lobby]
tools:
- filesystem
Then ask researcher in lobby, for example: "Save your notes in a shared directory called report and invite writer."
It calls create_shared_directory("report") and invite_to_shared_directory("report", "writer"), and from then on both agents see the directory's path in their prompts.
list_shared_directories() shows each directory an agent owns or joined, with its path and access, the pending invitations of each directory it owns, and the invitations waiting for it.
Sharing between personal agents
When each person has an agent only they may use, an invitation from one person waits until the other accepts it through their own agent.
agents:
ann_assistant:
display_name: Ann's Assistant
access:
users: ["@ann:example.org"]
tools: [shell, shared_directories]
ben_assistant:
display_name: Ben's Assistant
access:
users: ["@ben:example.org"]
tools: [shell, shared_directories]
team_helper:
display_name: Team Helper
access:
users: ["@ann:example.org", "@ben:example.org"]
tools: [shell, shared_directories]
Ann asks ann_assistant: "Share your notes with ben_assistant in a shared directory called notes."
Ann cannot use ben_assistant, so the invitation is pending, and ben_assistant sees only the directory's owner and name, never its path or files; list_shared_directories() also shows who asked and when.
When Ben next talks to ben_assistant, its prompt mentions the invitation; Ben says "Accept the notes directory from ann_assistant", and it calls accept_shared_directory("ann_assistant", "notes") and reads the files from then on.
The same works from ben_assistant to ann_assistant, and between team_helper and either person's agent: team_helper invites at once when the person asking can use the invited agent, and otherwise that agent's person accepts.
Rules
Only the agent that created a directory can invite, remove, or delete, and deleting a directory removes every file in it.
Names use 1 to 64 lowercase letters, digits, -, or _, starting with a letter or digit.
Private agents can neither create nor join shared directories.
Creating or deleting a directory, and adding or removing a member, restarts each affected agent's dedicated worker on its next tool call, which ends that worker's background shells, tmux sessions, and computer sessions.
An invitation applies at once when the user who asks for it may use the invited agent outside the current room.
Access through access.users, administrator rights, access.members_of_rooms, or the default grant to members of the agent's managed rooms counts, but access.current_room_members does not; see Responder access.
Otherwise the invitation is pending until a user who may use the invited agent, by the same rule, accepts it through that agent with accept_shared_directory(owner, name) or declines it with decline_shared_directory(owner, name).
A pending agent sees no path or file of the directory and its worker mounts nothing until the accept; inviting it again while pending changes nothing.
An agent holds at most 10 pending invitations; a further invitation fails until it accepts or declines one, or an owner cancels one.
The owner's remove_from_shared_directory and delete_shared_directory also cancel a pending invitation.
Under file_access: workspace, filesystem accepts paths inside the agent's shared directories when it runs in a worker or when MindRoom runs without workers.
When MindRoom uses workers but an agent's filesystem runs in the primary process, workspace keeps it out of shared directories; add it to the agent's worker_tools.
Other path tools, such as attachments and matrix_message, stay inside the workspace, so copy a shared file into the workspace before sending it.
Access by deployment
Where tools run decides who reaches a shared directory:
| Where tools run | Owner | Invited agents | Other agents |
|---|---|---|---|
| Dedicated Docker or Kubernetes workers | Read and write | Read only | No access |
Kubernetes static_runner sidecar |
Read and write | Read and write | Read and write |
No workers, through filesystem under file_access: workspace |
Read and write | Read only | No access |
shell, python, and tools under file_access: unrestricted that run in the primary process read and write every shared directory, whoever owns it, even when other tools use workers.
The documented Compose and host-container static_runner setups mount only scratch storage, so tools running there cannot reach shared directories; use dedicated Docker workers instead.
A worker_scope: user worker serves several agents, so each of them reaches every directory any of them owns or joined, with the widest access among them.
[docker]
docker manages containers with functions such as list_containers(), run_container(), exec_in_container(), start_container(), stop_container(), remove_container(), get_container_logs(), and inspect_container().
It also manages images, volumes, and networks with functions such as pull_image(), build_image(), tag_image(), list_volumes(), create_volume(), list_networks(), and connect_container_to_network().
Docker daemon access is privileged host control, so docker runs in a worker by default, and the runtime that runs it needs a reachable Docker daemon or socket.
get_container_logs(stream=True) returns a message asking for non-streaming mode instead of a live stream.
Configuration
| Option | Type | Required | Default | Notes |
|---|---|---|---|---|
include_tools |
string[] |
no |
null |
Docker functions to expose; unset exposes all of them. |
Example
list_containers()
run_container("postgres:16", name="postgres", detach=True, environment={"POSTGRES_PASSWORD": "example"})
get_container_logs("postgres", tail=50)
[calculator]
calculator provides add(), subtract(), multiply(), divide(), exponentiate(), factorial(), is_prime(), and square_root() for exact arithmetic without the risk of python.
Each function returns a small JSON result, and errors such as division by zero, negative factorials, and negative square roots come back as JSON errors.
factorial() accepts n up to 1558 and is_prime() accepts n up to 10**12; larger arguments return a JSON error.
calculator has no configuration fields.
[reasoning]
reasoning gives an agent a scratchpad for its own step-by-step reasoning rather than user-facing output.
think() records an intermediate thought and an optional next action.
analyze() records the result of a step and a next_action of continue, validate, or final_answer.
Steps are kept for the current run, so later steps see earlier ones.
The agent's prompt includes the default reasoning instructions, which tell the model to call think() before every tool call or reply, only while both think() and analyze() are enabled; instructions you set with instructions are always included.
Configuration
| Option | Type | Required | Default | Notes |
|---|---|---|---|---|
enable_think |
boolean |
no |
true |
Enable think(). |
enable_analyze |
boolean |
no |
true |
Enable analyze(). |
add_few_shot |
boolean |
no |
false |
Add few-shot examples to the default reasoning instructions. |
instructions |
text |
no |
null |
Replace the default reasoning instructions entirely. |
few_shot_examples |
text |
no |
null |
Replace the built-in few-shot examples; used only when few-shot examples are added. |
all |
boolean |
no |
false |
Enable all reasoning functions. |
Example
[file_generation]
file_generation provides generate_json_file(), generate_csv_file(), generate_pdf_file(), generate_docx_file(), generate_html_file(), generate_text_file(), and generate_code_file().
Each function returns the generated file in its tool result.
Filenames are generated when omitted, and a missing extension is added for the export type.
generate_json_file() accepts dicts, lists, or strings, and wraps a string that is not valid JSON.
PDF and DOCX generation are disabled when reportlab or python-docx is unavailable, even if enabled in config.
Files are also saved to disk when output_directory is set or save_files is true.
Saved files go into output_directory inside the agent workspace, or the workspace root when only save_files is set, and overwrite files of the same name.
output_directory must be a relative path that stays inside the workspace.
Configuration
| Option | Type | Required | Default | Notes |
|---|---|---|---|---|
output_directory |
text |
no |
null |
Directory inside the agent workspace where generated files are saved. |
save_files |
boolean |
no |
false |
Save generated files; when output_directory is unset, they go to the workspace root. |
enable_json_generation |
boolean |
no |
true |
Enable generate_json_file(). |
enable_csv_generation |
boolean |
no |
true |
Enable generate_csv_file(). |
enable_pdf_generation |
boolean |
no |
true |
Enable generate_pdf_file(). |
enable_docx_generation |
boolean |
no |
true |
Enable generate_docx_file(). |
enable_txt_generation |
boolean |
no |
true |
Enable generate_text_file(). |
enable_html_generation |
boolean |
no |
true |
Enable generate_html_file(). |
enable_code_generation |
boolean |
no |
true |
Enable generate_code_file(). |
all |
boolean |
no |
false |
Enable all file-generation functions. |
Example
generate_csv_file([{"name": "alpha", "value": 1}, {"name": "beta", "value": 2}], filename="data.csv")
generate_pdf_file("Quarterly summary", filename="report.pdf", title="Q1 Report")
generate_docx_file("Quarterly summary", filename="report.docx", title="Q1 Report")
[visualization]
visualization provides create_bar_chart(), create_line_chart(), create_pie_chart(), create_scatter_plot(), and create_histogram().
Bar, line, and pie charts accept a dict, a list of dicts, or a JSON string; scatter plots take x and y lists, and histograms take a list of numbers.
Each function saves a PNG in output_dir inside the agent workspace and returns the file path.
A chart's filename must be a plain file name; when omitted, the chart is named after its type and numbered, such as bar_chart_3.png.
Charts overwrite files of the same name, and output_dir is created when missing.
Because charts are in the workspace, attachments and matrix_message can send them under the default file_access: workspace.
Configuration
| Option | Type | Required | Default | Notes |
|---|---|---|---|---|
output_dir |
text |
no |
"charts" |
Directory inside the agent workspace where charts are saved; absolute paths and .. are rejected. |
enable_create_bar_chart |
boolean |
no |
true |
Enable create_bar_chart(). |
enable_create_line_chart |
boolean |
no |
true |
Enable create_line_chart(). |
enable_create_pie_chart |
boolean |
no |
true |
Enable create_pie_chart(). |
enable_create_scatter_plot |
boolean |
no |
true |
Enable create_scatter_plot(). |
enable_create_histogram |
boolean |
no |
true |
Enable create_histogram(). |
all |
boolean |
no |
false |
Enable all chart functions. |
Example
create_bar_chart({"Mon": 12, "Tue": 18, "Wed": 9}, title="Requests per day")
create_scatter_plot(x=[1, 2, 3], y=[2, 5, 7], title="Experiment results")
create_histogram([1, 1, 2, 3, 5, 8, 13], title="Value distribution")
[sleep]
sleep() waits for 0 to 300 seconds and returns a confirmation; other durations return an error without waiting.
The response stays open until the delay ends or the response is stopped.
| Option | Type | Required | Default | Notes |
|---|---|---|---|---|
enable_sleep |
boolean |
no |
true |
Enable sleep(). |
all |
boolean |
no |
false |
Enable all sleep functions. |