Agent 工具
agent 透過工具行動。
只有 speaker 的層級不低於工具的最低層級時,這一輪才會提供這個工具,所以 member 看不到下面那些需要 admin 或 owner 的工具。
這裡列的是預設層級。
可以用 roundtable.config.ts 的 toolTiers 修改;見存取層級。
沒有人指定層級的工具,需要 owner。
Agent、群組和頻道
Section titled “Agent、群組和頻道”這些工具屬於 agent server。 你很少自己呼叫它們:你對 agent 說,通常是協調者,由它去呼叫。 實際怎麼運作,見建立 agent、群組、臨時騎士和封存與頻道。
| 工具 | 作用 | 最低層級 |
|---|---|---|
agent_list |
列出每個 agent 和群組的頻道與狀態,以及依伺服器順序排列的 Agents 和 Groups 類別。 |
member |
agent_get |
讀取 agent 的顯示名稱、狀態、頻道、模型、thinking level、技能、外觀和提示詞。 | member |
agent_create |
建立一個有自己頻道和角色頭像(class、color 選填)的 agent,並讓它從一個開場任務開始。名稱建立後不能改。 |
admin |
agent_update |
修改 agent 的顯示名稱、提示詞、模型或 thinking level。修改從它的下一輪起生效。 | admin |
agent_avatar |
改 agent 的外觀:class、color 或單一 parts;沒提到的維持原樣。 |
admin |
message_agent |
傳一個自成一體的請求給另一個 agent。回答會以新的一輪回來。群組裡的席位沒有這個工具。 | member |
helper_create |
做一位臨時騎士,為單一、自成一體的任務幫忙;他立刻開始,回答以新的一輪回來。臨時騎士不能建立 agent、群組或臨時騎士。 | member |
helper_end |
封存你自己的臨時騎士,指定名字,或封存每一位已結束的。 | member |
group_create |
建立一個有 2 到 8 個 agent、可以指定主持人的群組頻道。 | admin |
group_update |
修改群組的顯示名稱、成員或主持人。 | admin |
archive |
封存 agent 或群組。頻道和歷史紀錄保留在 Archive 類別底下。協調者和發出呼叫的 agent 不能被封存。 |
admin |
channel_arrange |
把 agent 和群組的頻道分到各個類別並排序。只要有一筆錯誤,整個呼叫就會被拒絕。 | admin |
channel_read |
由舊到新讀取 agent server 的頻道或 thread 裡的訊息。唯讀。 | member |
skills addon 開著時才有技能工具,memory addon 開著時才有記憶工具。
見技能與記憶。
| 工具 | 作用 | 最低層級 |
|---|---|---|
skill_list |
列出技能,附上種類、描述、群組,以及帶著它的 agent。 | member |
agent_skills |
增減 agent 帶的技能。內建技能不會被移除。 | admin |
skill_create |
把新技能寫進 registry。 | admin |
skill_update |
取代 agent 自己寫的技能的描述或內容。 | admin |
skill_delete |
刪除 agent 自己寫的技能,並從每個 agent 身上卸下。 | admin |
skill_link |
註冊受管理的儲存庫某個資料夾裡的技能。連結進來的技能是唯讀的。 | admin |
skill_unlink |
把連結進來的技能從 registry 移除。來自套件的技能會被拒絕,訊息會指出套件名稱。 | admin |
skill_group_set |
建立或取代技能群組,也就是一份有名稱的技能清單。agent 帶的只有技能本身。 | admin |
skill_group_delete |
刪除技能群組。裡面的技能不受影響。 | admin |
memory_add |
把一項事實記成 core、note 或 event。 |
member |
memory_search |
搜尋所有記住的內容。 | member |
memory_remove |
忘掉每一項包含指定文字的事實。 | member |
記憶屬於 speaker。 member 的記憶工具讀寫的是那位 member 的記憶,不是 owner 的。
排程、背景工作和通知
Section titled “排程、背景工作和通知”排程工具作用在它所在頻道的排程上。 見排程與背景工作。
| 工具 | 作用 | 最低層級 |
|---|---|---|
schedule_create |
為 agent 排一個工作,一次或重複都行。 | admin |
schedule_list |
列出這個頻道的排程和下次執行時間。 | member |
schedule_update |
修改排程的標題、提示詞或時間。 | admin |
schedule_cancel |
刪除排程。 | admin |
delegate_task |
把網路研究在背景交給比較便宜的 worker 模型。報告會以新的一輪回來。 | admin |
notify |
在這段對話自己的 surface 上通知它服務的人:從 web room 是 web app 的通知加推播,從 Discord 是 Discord 私訊。舊設定裡寫 notify_owner 的仍可使用,直到 1.0。 |
owner |
Shell 和檔案
Section titled “Shell 和檔案”agent session 帶有 Pi 的 shell 和檔案工具。
它們以 host 的帳號身分,在共用的工作區(workDir)裡執行。
| 工具 | 作用 | 最低層級 |
|---|---|---|
bash |
執行 shell 指令。 | owner |
read |
讀取檔案。 | owner |
edit |
編輯檔案。 | owner |
write |
寫入檔案。 | owner |
讀取直接執行,祕密檔案除外。
具破壞性或會改變系統的 shell 指令,以及工作區之外的寫入或編輯,會被擱置,等 owner 在卡片上核准。
讀取祕密也一樣:印出環境變數(env、printenv)、讀取 .env、~/.ssh/*、/proc/*/environ 這類祕密檔案、gh auth token、git 存下的憑證(類別 shell.secret-read,yolo 模式一律出卡片);docker run、exec、create、cp 也是。
shell 只拿到 host 環境的一部分:路徑、使用者、語系、終端機、TMPDIR 與 proxy,再加上設定裡 shellEnv 額外給的。
bot token、model 登入、DATABASE_URL 等 host 持有的祕密留在 host process 裡;工具輸出若印出它們的值,model 讀到前會換成 ****。
這些擱置不是沙箱。
shell 以 host 的使用者身分執行,所以刻意的指令仍讀得到那個使用者讀得到的東西,例如 /proc/<host pid>/environ 或規則不認得的檔案。
環境變數白名單和祕密讀取的擱置,擋的是隨手和意外的外洩。
要讓 agent 碰不到祕密,請讓它們的 shell 以不在 docker 群組裡的專用帳號執行(這個群組等同 root),或改用 sandbox 套件。
Discord 管理
Section titled “Discord 管理”這些工具屬於 discord-admin addon;設了 discord.admin: false 就不會載入它。
它們代 owner 管理伺服器,每次呼叫都會檢查 owner 和 bot 是否都有相關的 Discord 權限。
每一個預設都需要 owner。
| 工具 | 作用 |
|---|---|
discord_list_servers |
列出 owner 和 bot 共同所在的伺服器,以及各自擁有的權限。 |
discord_list_channels |
列出伺服器的頻道和類別。 |
discord_list_roles |
由高到低列出伺服器的身分組和它們的權限。 |
discord_find_members |
找出使用者名稱或暱稱以查詢文字開頭的成員。 |
discord_create_channel |
建立文字、語音或公告頻道,或建立類別。 |
discord_delete_channel |
刪除頻道、類別或 thread。 |
discord_list_threads |
列出伺服器目前活躍的 thread,或某個頻道已封存的 thread。 |
discord_create_thread |
在文字或公告頻道開一個 thread。 |
discord_edit_thread |
重新命名、封存、鎖定 thread,或修改它的自動封存時間。 |
discord_create_role |
建立身分組。 |
discord_edit_role |
修改身分組的名稱、顏色、顯示方式或權限。 |
discord_delete_role |
刪除身分組。 |
discord_add_member_role |
給成員一個身分組。 |
discord_remove_member_role |
拿掉成員的一個身分組。 |
discord_set_nickname |
設定或清除成員的暱稱。 |
discord_timeout_member |
讓成員在指定的分鐘數內不能發言。0 表示解除。 |
discord_kick_member |
把成員移出伺服器。 |
discord_ban_member |
封鎖使用者,也能一併刪除他最近的訊息。 |
discord_unban_member |
解除封鎖。 |
discord_get_channel_info |
讀取頻道所屬的伺服器、名稱和主題。 |
discord_get_messages |
讀取頻道最近的訊息。 |
discord_search_messages |
搜尋頻道的訊息。 |
discord_get_pinned_messages |
讀取頻道的釘選訊息。 |
discord_send_message |
傳送訊息,也能附上圖片或檔案。它不會觸發任何提及。 |
discord_edit_message |
編輯 bot 自己傳送的訊息。 |
discord_delete_message |
刪除一則訊息。 |
discord_pin_message |
釘選一則訊息。 |
discord_unpin_message |
取消釘選一則訊息。 |
discord_edit_channel |
修改頻道的名稱、主題、慢速模式等類似設定。 |
discord_set_channel_permissions |
設定頻道裡某個身分組或成員的權限覆寫。 |
discord_delete_channel_permissions |
移除頻道裡某個身分組或成員的權限覆寫。 |
每一輪都有的工具
Section titled “每一輪都有的工具”有三個工具隨 runtime 一起來,只需要 member 層級。
| 工具 | 作用 | 最低層級 |
|---|---|---|
ask_user |
在頻道裡用一張附按鈕的卡片問一到四個相關的問題,每題可以附選項和預覽,回答的人也能對整組答案寫一則備註;它會等一小段時間,之後才回答的話,會開新的一輪。只能一次顯示一題的聊天介面,會一題一題問。 | member |
read_attachment |
讀取有人附在頻道裡的文字檔或 PDF。 | member |
compact_session |
壓縮 session 的 context。它會拒絕 resume 選項。 |
member |
核心也宣告了 web_search、fetch_content 和 get_search_content 的層級為 member,這三個是 pi-web-access 的工具。
委派的 worker 會載入這些工具。
外掛的工具,帶著它的作者給的 minTier。
見外掛能新增什麼。
web 套件開啟聊天室頁面時,會加上正式騎士的傳入 Webhook工具,只作用在呼叫者自己的聊天室;臨時騎士和群組席位會被拒絕。
| 工具 | 作用 | 最低層級 |
|---|---|---|
webhook_create |
為聊天室建立 Webhook,並只回傳一次網址,網址只能放在機密儲存處。永不到期的最多 10 個、會到期的最多 20 個;期限最長 7 天;once 會在第一次發文後撤銷。 |
owner |
webhook_list |
列出聊天室有效的 Webhook,不會再顯示網址。 | owner |
webhook_revoke |
依 id 撤銷聊天室的一個 Webhook。 | owner |