Skip to content

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.

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

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.

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

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.

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.

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.

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