Agent tools
Agents act through tools.
An agent’s turn offers only tools whose minimum tier the speaker meets.
The tiers are the defaults.
toolTiers in roundtable.config.ts can change them; see Access tiers.
A tool with no declared tier needs the owner.
Agents, groups, and channels
Section titled “Agents, groups, and channels”These tools belong to the agent server. Ask an agent, usually the coordinator, and it calls them for you. For how they work in practice, see Create agents, Groups, Temp knights, and Archive and channels.
| Tool | What it does | Minimum tier |
|---|---|---|
agent_list |
Lists every agent and group with channel and status, and the Agents and Groups categories in server order. | member |
agent_get |
Reads an agent’s display name, status, channel, model, thinking level, skills, look, and prompt. | member |
agent_create |
Creates an agent with its own channel and a character picture (class and color optional), and starts it on an opening task. The name is permanent. |
admin |
agent_update |
Changes an agent’s display name, prompt, model, or thinking level. The change applies from its next turn. | admin |
agent_avatar |
Changes an agent’s look: its class, color, or single parts. What is left out stays as it is. |
admin |
message_agent |
Sends a self-contained request to another agent. The answer comes back as a new turn. A seat in a group does not have it. | member |
helper_create |
Makes a temp knight, a helper for one self-contained task, that starts at once and answers back as a new turn. A temp knight cannot make agents, groups or temp knights. | member |
helper_end |
Archives your own temp knights, by name or every finished one. | member |
group_create |
Creates a group channel with 2 to 8 agents and an optional host. | admin |
group_update |
Changes a group’s display name, members, or host. | admin |
archive |
Archives an agent or a group. The channel and its history are kept under the Archive category. The coordinator and the calling agent cannot be archived. | admin |
channel_arrange |
Sorts agent and group channels into categories and orders them. A wrong entry refuses the whole call. | admin |
channel_read |
Reads messages of a channel or thread of the agent server, oldest first. Read-only. | member |
Skills and memory
Section titled “Skills and memory”The skill tools exist while the skills addon is on, and the memory tools while the memory addon is on.
See Skills and memory.
| Tool | What it does | Minimum tier |
|---|---|---|
skill_list |
Lists the skills with their kind, description, groups, and the agents that carry them. | member |
agent_skills |
Adds and removes skills an agent carries. Built-in skills stay. | admin |
skill_create |
Writes a new skill into the registry. | admin |
skill_update |
Replaces an agent-written skill’s description or body. | admin |
skill_delete |
Deletes an agent-written skill and detaches it from every agent. | admin |
skill_link |
Registers the skills in a folder of a managed repository. Linked skills are read-only. | admin |
skill_unlink |
Removes a linked skill from the registry. A skill that comes from a package is refused, with the package named. | admin |
skill_group_set |
Creates or replaces a skill group, a named list of skills. Agents carry skills, not groups. | admin |
skill_group_delete |
Deletes a skill group. Its skills are untouched. | admin |
memory_add |
Remembers a fact as core, note, or event. |
member |
memory_search |
Searches everything remembered. | member |
memory_remove |
Forgets every remembered fact that contains the given text. | member |
Memory belongs to the speaker. A member’s memory tools read and change their own memory.
Schedules, background work, and notices
Section titled “Schedules, background work, and notices”Schedule tools act on the schedules of the channel they run in. See Schedules and background work.
| Tool | What it does | Minimum tier |
|---|---|---|
schedule_create |
Schedules a task for the agent, once or repeating. | admin |
schedule_list |
Lists the channel’s schedules with their next run. | member |
schedule_update |
Changes a schedule’s title, prompt, or timing. | admin |
schedule_cancel |
Deletes a schedule. | admin |
delegate_task |
Hands web research to a cheaper worker model in the background. Its report comes back as a new turn. | admin |
notify |
Sends the person the conversation serves a notice on the conversation’s own surface: the web app’s notice and push from a web room, a Discord direct message from Discord. Older configurations that name it notify_owner keep working until 1.0. |
owner |
Shell and files
Section titled “Shell and files”Agent sessions carry Pi’s shell and file tools.
They run as the host account, in the shared workspace (workDir).
| Tool | What it does | Minimum tier |
|---|---|---|
bash |
Runs a shell command. | owner |
read |
Reads a file. | owner |
edit |
Edits a file. | owner |
write |
Writes a file. | owner |
Reading runs, except a secret file.
A shell command that is destructive or changes the system, and a write or edit outside the workspace, is held until the owner approves it on a card.
So is reading a secret: printing the environment (env, printenv), reading a secret file such as .env, ~/.ssh/* or /proc/*/environ, gh auth token, and git’s stored credentials (the class shell.secret-read, which yolo mode always cards); and docker run, exec, create and cp.
The shell gets only part of the host’s environment: the paths, the user, the locale, the terminal, TMPDIR and the proxies, plus what shellEnv adds in the settings.
Bot tokens, model logins, DATABASE_URL and the other secrets the host holds stay in the host process, and any of their values a tool prints is replaced with **** before the model reads it.
These holds are not a sandbox.
The shell runs as the host’s user, so a determined command can still read what that user can read, such as /proc/<host pid>/environ or a file the rule does not know.
The environment whitelist and the secret-read hold stop casual and accidental leaks.
To keep secrets from the agents, run their shells under a dedicated account that is not in the docker group (that group equals root), or use the sandbox package.
Discord administration
Section titled “Discord administration”These tools belong to the discord-admin addon, which discord.admin: false leaves out.
They manage the server on the owner’s behalf, and a call checks that both the owner and the bot hold the Discord permission involved.
All these tools need the owner by default.
| Tool | What it does |
|---|---|
discord_list_servers |
Lists the servers the owner and the bot share, with the permissions each holds. |
discord_list_channels |
Lists a server’s channels and categories. |
discord_list_roles |
Lists a server’s roles, highest first, with their permissions. |
discord_find_members |
Finds members whose username or nickname starts with a query. |
discord_create_channel |
Creates a text, voice, or announcement channel, or a category. |
discord_delete_channel |
Deletes a channel, category, or thread. |
discord_list_threads |
Lists a server’s active threads, or a channel’s archived ones. |
discord_create_thread |
Starts a thread in a text or announcement channel. |
discord_edit_thread |
Renames, archives, locks, or changes the auto-archive time of a thread. |
discord_create_role |
Creates a role. |
discord_edit_role |
Changes a role’s name, color, display, or permissions. |
discord_delete_role |
Deletes a role. |
discord_add_member_role |
Gives a member a role. |
discord_remove_member_role |
Takes a role from a member. |
discord_set_nickname |
Sets or clears a member’s nickname. |
discord_timeout_member |
Stops a member from talking for some minutes. 0 lifts it. |
discord_kick_member |
Removes a member from the server. |
discord_ban_member |
Bans a user, optionally deleting their recent messages. |
discord_unban_member |
Lifts a ban. |
discord_get_channel_info |
Reads a channel’s server, name, and topic. |
discord_get_messages |
Reads a channel’s recent messages. |
discord_search_messages |
Searches a channel’s messages. |
discord_get_pinned_messages |
Reads a channel’s pinned messages. |
discord_send_message |
Sends a message, optionally with images or files. It triggers no mentions. |
discord_edit_message |
Edits a message the bot itself sent. |
discord_delete_message |
Deletes one message. |
discord_pin_message |
Pins one message. |
discord_unpin_message |
Unpins one message. |
discord_edit_channel |
Changes a channel’s name, topic, slowmode, and similar settings. |
discord_set_channel_permissions |
Sets a role’s or member’s permission overwrite in a channel. |
discord_delete_channel_permissions |
Removes a role’s or member’s permission overwrite in a channel. |
Tools of every turn
Section titled “Tools of every turn”Three tools come with the runtime and need only the member tier.
| Tool | What it does | Minimum tier |
|---|---|---|
ask_user |
Asks one to four related questions on one card with buttons in the channel, with options, previews and a note on the whole set, and waits a short while for the answers; a later answer starts a new turn. A chat that shows one question at a time is asked them one after another. | member |
read_attachment |
Reads a text or PDF file someone attached in the channel. | member |
compact_session |
Compacts the session’s context. It refuses the resume option. |
member |
The core also declares the tiers of web_search, fetch_content, and get_search_content, the tools of pi-web-access, as member.
The delegation worker loads those tools.
Tools from plugins
Section titled “Tools from plugins”A plugin’s tool carries the minTier its author gave it.
See What plugins can add.
The web package, with its rooms pane, adds a permanent knight’s incoming webhooks, acting only on the caller’s own room; a temp knight and a group seat are refused.
| Tool | What it does | Minimum tier |
|---|---|---|
webhook_create |
Makes a webhook for the room and returns its URL once, which belongs only in a secret store. At most 10 that never expire and 20 that do; an expiry is at most 7 days; once revokes it after its first post. |
owner |
webhook_list |
Lists the room’s live webhooks, never their URLs. | owner |
webhook_revoke |
Revokes one of the room’s webhooks by id. | owner |