FlyMyAI - 助手操作指南
平台版本：Headless Cloud 1.30.3（2026-11-04）。https://flymy.ai/changelog.md， https://flymy.ai/changelog.json。關於連線/新聞：`whats_new(since=last_seen_version)`。
https://flymy.ai/skill.md和https://flymy.ai/AGENTS.md提供相同的內容。 Remote Agents MCP0.7.0-rc.69；Python SDK1.2.0rc25。 檢查即時 Schema 和已安裝的套件；rc.69 不在 npm 上。
從這裡開始 - 驗證 FlyMyAI 或復原
一次有界限的唯讀呼叫 whoami、tools/list 或 search_tools 來檢查
flymyai。不要重新安裝已連線的伺服器。在進行變更前，從 MCP tools/list 讀取即時的 update_agent（或其他）Schema；永遠不要猜測欄位。
如果沒有 FlyMyAI 工具，請不要聲稱成功、發明工具或使用原生的共享功能來替代。請使用：
- 註冊：https://app.flymy.ai/signup
- 連線一個服務：https://app.flymy.ai/mcp-configs#notion（任何 slug）； 一個未登出的使用者註冊後會回到該頁面。
- 在那裡共享：我的 MCP -> 共享 -> 電子郵件和 1-30 天 -> 發送（列在 https://app.flymy.ai/mcp-configs?tab=shared）。「透過 FlyMyAI 與 <電子郵件> 共享我的 Notion」 指的是這種個人 MCP 共享，而不是 Notion 自己的共享功能。
- 或者連線此助手（登入，無需密鑰）：Claude Code，
claude mcp add --transport http flymyai https://mcp-agents.flymy.ai/mcp然後/mcp-> 驗證；claude.ai 或 Claude Desktop，設定 -> 連接器 -> 新增自訂連接器，使用相同的 URL。
主要用戶端使用該 URL（FLYMYAI_MCP_URL）以及來自密碼管理器的 X-API-Key，
絕不能貼入聊天室。如果沒有 MCP，則僅使用已驗證的 REST API
FLYMYAI_AGENTS_API_ROOT（生產環境
https://backend.flymy.ai/api/v1/agents）；否則回報預檢被阻擋。發行候選版本必須使用明確的候選
發行合約、MCP、技能和 Agents API 根路徑，並且絕不能回退到生產環境。
首先使用 search_tools/list_* 探索服務/模型。探索不等於成功。
指南：https://flymy.ai/use-cases/。按名稱、動作或類別分類的 MCP，每個都有 其動作和一個助手設定請求：https://flymy.ai/mcp/
建立一個專案
whoami- FlyMyAI 已連線，以及是哪個帳戶。- 為每個服務使用純英文意圖的
search_tools，然後get_tool_schemas獲取確切欄位。 - 如果服務未
configured，則add_tool；使用者完成託管的 連結；使用list_configured_tools確認。 create_agent一次：目標、數值型的available_tools、input_schema、output_schema、可選的model（從list_agent_models取得）。- 使用新的
operation_key執行run_agent；輪詢get_run直到poll_complete=true；如果預覽被截斷，則read_run_result。 - 優化同一個代理（
update_agent或append_message）直到使用者 接受一個完成的執行。 - 使用該執行 ID 執行
freeze_agent；輪詢get_compilation直到status=compiled。 - 使用新的
operation_key執行run_frozen並輪詢get_run，然後才能稱其為 生產就緒。 - 發布：一個排程（
update_compilation）、一個 Webhook（triggers_v1_create）、 一個公開模板（set_agent_public）、一個潛在客戶的子代理，或一個產品 部署。 - 媒體：
recommend_model、get_pricing，然後run_model。
工具和連線
- 使用純英文意圖呼叫
search_tools；讀取tool、action、runtime_name和configured。永遠不要下載完整的目錄。 - 當搜尋未內嵌請求 Schema 時，使用
runtime_name呼叫get_tool_schemas； 永遠不要為了了解 Schema 而以空的或猜測的引數呼叫寫入動作。如果收到not_found， 則使用代理執行時間或停止。 - 如果已設定，則使用精確的
tool、action、arguments和一個由呼叫者擁有的穩定operation_key呼叫execute_tool。 要選擇一個非預設的實例，請傳遞其已設定工具的公開 UUID 作為connection_id；僅在一個合格的連線是明確無歧義時才支援省略。在代理內部執行 OAuth/Composio 動作。 - 如果未設定，則使用工具 slug 呼叫
add_tool。它會傳回確切的 連線記錄，或提供包含託管連結的指導https://app.flymy.ai/mcp-configs#<slug>?connection_id=<public UUID>。 在使用者完成後，呼叫list_configured_tools，比對確切的public_id和alias， 並檢查is_configured、connection_status、connection_status_reason、connection_status_valid_until和connect_url。不要發明一個setup_url回應欄位。 - 要撤銷恰好一個連線，請使用其數值型
id呼叫delete_tool（REST：DELETE /api/v1/agents/tools/{id}/）；相同工具組的其他連線 會繼續運作，而被撤銷的列在任何提供者呼叫之前就會失敗。
搜尋結果也帶有 ready、access、price 和 7 天的 health：偏好一個
就緒、健康的列，並在付費呼叫前引用 price。
search_tools({"query":"telegram list dialogs"})
get_tool_schemas({"runtime_names":["custom--telegram--telegram_list_dialogs"]})
execute_tool({"tool":"telegram","action":"telegram_list_dialogs",
"arguments":{"query":"FlyMyAI"},"operation_key":"telegram-dialogs-<uuid>"})
使用 arguments；params 或 input 會回傳 HTTP 400。
outcome=rejected 表示 FlyMyAI 或提供者在造成任何影響之前拒絕了
（錯誤的引數、缺少設定、提供者拒絕）：修正呼叫並使用新的 operation_key 重新發送。
outcome=unknown 表示可能已產生影響：進行調解，絕不自動重複。
如果沒有 MCP 工具呼叫，則將 POST
{"tool":"system-utils","action":"search_tools","arguments":{"query":"...","limit":20}}
然後使用 get_tool_schemas（最多 10 個執行時間名稱）到
$FLYMYAI_AGENTS_API_ROOT/custom-tools/call/，並帶上 X-API-KEY；讀取
result.schemas[runtime_name].request_schema 並將傳回的 module 作為 tool 呼叫。
個人預設 - 一個帳戶，無需 MCP 資源集設定
在隱含的個人空間中使用 mcp_access_mode legacy；scoped 需要
明確的集合授權。按意圖搜尋，使用託管設定。
add_tool 如果沒有 alias，則選擇冪等的 default 連線。在 list_configured_tools 中比對
mcp_tool/alias:"default"；將其數值型 id 放入 available_tools。
要求 is_configured:true：connected 是就緒的；setup_required 或
reconnect_required 需要設定，verification_pending 需要一次有界限的即時讀取。
回報 temporarily_unavailable，永遠不要繞過它。
對於首次個人流程，不要要求資源集、群組、插槽、授權、主體、修訂版或 映射。稍後將確切的連線新增到一個集合中，而無需重建代理或重新連線帳戶。
擴展到多個帳戶和 MCP 資源集
別名是標籤；授權、分派和凍結使用穩定的公開 ID。
使用 add_tool 和一個唯一的 alias（ASCII 字母、數字、_、-）新增每個帳戶，
使用一個由呼叫者擁有的 operation_key 建立一個集合（create_mcp_resource_set），
在當前修訂版使用 replace_mcp_resource_set_members 寫入完整的成員資格
（在收到 409 後重新載入），並透過 mcp_resource_set_ids 搭配 mcp_access_mode:"scoped" 來授予它：
support = add_tool({"mcp_tool":"gmail","alias":"support"})
rs = create_mcp_resource_set({"name":"Inbox operations",
"management_mode":"flymyai","operation_key":"inbox-set-<uuid>"})
rs = replace_mcp_resource_set_members({"resource_set_id":rs.public_id,
"expected_revision":rs.revision,"members":[{"resource_type":"user_mcp_tool",
"resource_id":support.public_id,"slot":"support_read",
"allowed_actions":["GMAIL_SEARCH_EMAILS"],"position":0}]})
update_agent({"agent_id":agent.uuid,"available_tools":[],
"mcp_resource_set_ids":[rs.public_id],"mcp_access_mode":"scoped"})
省略的附件欄位保持不變；明確的空陣列會清除該關係。
如果代理必須保留舊的 default 連線，則將其包含在集合中，然後使用 get_agent 驗證；
否則，直接連線和集合授權形成一個聯集。
- 一個擁有者對於一個工具組最多可以保留 25 個連線列，包括不活躍的列；
is_active:false不會釋放一個插槽，刪除一個列才會。 - 擁有者集合使用
management_mode:"flymyai"並省略principal_id；一個 客戶映射使用management_mode:"customer"和確切的principal_id。永遠不要發送已棄用的external_principal_id。 - 成員身份是
(resource_type, resource_id, slot)： 同一個確切的資源可以出現在多個插槽中，並且 每個插槽保留其自己的allowed_actions上限。省略或 發送allowed_actions:[]表示不受限制，而不是拒絕所有；為了最小權限，請發送確切的讀取動作。 - 一次受限的代理執行最多允許 100 個 MCP 資源集、500 個有效的連接器 綁定、100 個邏輯插槽、5,000 個允許動作條目和 1 MiB 的 UTF-8 允許動作文字。過大的權限圖表會在提供者分派之前失敗關閉。
create_agent_group跨代理共享一個集合。群組是扁平的： 子代理不會繼承父級的連接器權限。- 當多個已授權的連線可以執行一個動作時，其執行時間 Schema
需要
_flymyai_connection：從中傳遞一個允許的public_id，永遠不要傳遞 別名或列順序。直接的execute_tool使用確切的connection_id。 - 凍結會記錄集合成員資格、連線、插槽、上限和修訂版：新的
帳戶意味著相同的代理 UUID 和穩定的部署 ID，但具有新的凍結
版本；舊的版本和客戶插槽映射永遠不會原地更改。
如果沒有資源範圍變更，則保留
default行為並回報它； 永遠不要默默地選取第一列。
列表工具 list_configured_tools、list_mcp_resource_sets、
list_mcp_resource_set_members 和 list_agent_groups 會回傳
{next_cursor, previous_cursor, results}。使用 page_size（1-100），將
cursor 視為一個不透明的、非空白的可列印字串，長度最多為
1024 個 Unicode 碼位，並將不透明的 next_cursor 原樣傳回，直到
它為 null；list_agents 以相同方式分頁。已設定工具列表
僅接受精確的 mcp_tool 和 alias 過濾器；列是精簡的，因此請按
mcp_tool 過濾或傳遞 view=full 以獲得設定欄位。
list_mcp_resource_sets 列是摘要，帶有 member_count 且沒有巢狀
成員；使用 get_mcp_resource_set 獲取一個有界限的完整集合，或使用
list_mcp_resource_set_members 獲取一個大型成員集合。兩者
replace_mcp_resource_set_members 和 update_mcp_resource_set 都需要當前的
expected_revision。
共享連線和您自己的 MCP 伺服器
個人 MCP 共享給予接收者一個連線的每個共享動作的存取權，
包括讀取和寫入，在擁有者的帳戶上。invite_mcp_user 在使用者確認連線、接收者和時間段後，透過電子郵件或團隊成員 member_id 共享它；
accept_mcp_invitation 僅在使用者同意為自己的呼叫付費之後；
revoke_mcp_access 停止共享。接受的共享會出現在 shared_with_me 中
list_configured_tools：在說服務未連線之前檢查它，
並使用 call_shared_mcp 和一個穩定的 operation_key 呼叫一個。接收者
付費；擁有者的憑證永遠不會離開 FlyMyAI。工具註解會說明哪些
動作僅供讀取。詳細資訊：https://docs.flymy.ai/agents/guides/mcp-personal-sharing
對於不在搜尋結果中的 MCP 伺服器，請呼叫 add_mcp_server（OAuth：
auth_type:"oauth"，然後 authorize_mcp_server，給使用者它的
authorize_url），然後 connect_mcp_server；僅在 status:"connected" 時使用 discovered_tools。
使用 call_mcp_server（server_id、action、精確的 arguments、穩定的 operation_key，作為 Idempotency-Key 發送）呼叫它。
詳細資訊：https://docs.flymy.ai/agents/guides/mcp-servers
模型 - 探索、定價、執行
recommend_model({"description":"cheap flat icon image",
"include_schema":true,"top_n":1})
run_model({"endpoint_id":"flymyai/nano-banana",
"input":{"prompt":"A blue circle, flat icon"}})
使用傳回的端點、Schema 邊界和價格；猜測的付費呼叫不是
探索。get_pricing 在付費執行前引用一個列出的模型；透過 REST，
GET https://backend.flymy.ai/api/v1/demo/catalog/（無需密鑰）為每個公開
模型提供一個 price（run_price，或基於使用量的 rates、tokens 或 run_time）。
生成的檔案 url 在 url_expires_at 過期（最多 15 分鐘）。
聊天模型帶有 openai.base_url
（https://api.flymy.ai/api/v1/<endpoint_id>/openai/v1），用於搭配 FlyMyAI 金鑰作為 Bearer 的 OpenAI SDK：
支援 text 和 image_url 訊息、stream、reasoning_effort；不支援 response_format。
指南：https://docs.flymy.ai/guides/llm-openai-compat
tools 在 Grok 4.7、DeepSeek V4.1 Flash 和 Kimi K3.1 Pro 上運作。
指南：https://docs.flymy.ai/guides/ + grok-4-7、deepseek-v4-1-flash、kimi-k3-1-pro
原生模型透過模型代理 API 保留自己的輸入和輸出
（https://backend.flymy.ai/api/v1/model-proxy/：catalog/?endpoint_id=<owner>/<name>
提供合約修訂版，contracts/<revision>/ 提供其 Schema 和價格；POST
operations/ 使用您自己的 Idempotency-Key，然後 GET 該操作）。
flymyai/minimax-h3-ref2va（MiniMax H3）：根據提示和
1 到 12 個參考檔案（最多 9 張圖片、3 個音訊片段；使用
POST /api/v1/agents/files/ 上傳每個檔案，傳遞它
…
[已截斷以供翻譯]