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提供相同的字节。 远程智能体 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 并带上认证的
FLYMYAI_AGENTS_API_ROOT（生产环境
https://backend.flymy.ai/api/v1/agents）；否则报告预检被阻止。候选版本运行必须使用明确的候选
版本发布合约、MCP、技能及智能体 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、可选的来自list_agent_models的model。run_agent使用一个新的operation_key；轮询get_run直到poll_complete=true；如果预览被截断则read_run_result。- 优化同一个智能体（
update_agent或append_message），直到用户 接受一个完成的运行。 freeze_agent使用该执行 ID；轮询get_compilation直到status=compiled。run_frozen使用一个新的operation_key，并轮询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 需要
明确的集合授权。按意图搜索，使用托管设置。
不带 alias 的 add_tool 选择幂等的 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 字母、数字、_、-）添加每个账户，
用 create_mcp_resource_set 和一个调用方拥有的
operation_key 创建一个集合，用
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 停止共享。接受的共享出现在 list_configured_tools 的 shared_with_me 下：在说服务未连接之前检查它，并用 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）用于 OpenAI SDK 并带上 FlyMyAI 密钥作为 Bearer：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 个参考文件生成 5 或 10 秒带声音的视频（最多 9 个图像、3 个音频剪辑；每个通过 POST /api/v1/agents/files/ 上传，传递它