Agent workflows
Detailed workflows referenced by the compact server instructions. Use the current tool schemas and the guide at https://flymy.ai/skill.md.
Creating and freezing an agent
Every agent lives in a project, and a new agent is made by creating its project: projects_plan, then projects_create with the task as brief (there is no create_agent tool). It returns the project, its agent - the master the owner talks to in the app - and the first chat. Take that one project from idea to product: define its goal, tools, inputs, and output in the brief; poll get_run on the chat (read_run_result reads a result longer than get_run shows); refine it in the same chat with append_message, or start another chat of the same agent with run_agent; freeze_agent one accepted execution; poll get_compilation; then test it with run_frozen.
To change what a frozen agent does, save_instruction_version (a new version; the current one is kept), test it with run_frozen(compilation_id), then set_live_version - run_frozen(agent_id) and the schedule run the live version, and set_live_version on an older version rolls back. Variables and customers do not require cloned agents. A frozen release keeps running in the FlyMyAI cloud when the user's laptop is closed.
Subagents
Any ordinary run can start subagents. subagent_limits on run_agent or
run_frozen sets the lead's allowance: cap_usd (subagents and their tools; 0
turns them off), max_children, max_parallel (1-8, default 3; more wait) and
agents (your agent ids; without it, also those its instruction names by id).
No cap or count limit unless you set one; the lead's calls bill separately.
Chat/API/SDK/MCP leads author requested helpers with create_subagent and
update_subagent (including user_prompt_source), within the project;
scheduled, frozen and child runs cannot. Editing another agent needs your
request; flymy.yaml agents use plan/apply; external assistants use
update_agent.
In the run the lead has list_subagents (allowed agents, model, inputs),
delegate_agent(agent=..., brief, variables, operation_key=...) (with model
instead of agent it copies the lead and its tools; a subagent runs on the
lead's model unless you or its instructions name another), wait_subagents,
subagent_status(child_id) (facts and full-result reference) and
cancel_subagents (the batch joins automatically; wake_on_end:true wakes the lead
when that child ends), plus describe_subagent_api, freeze_subagent (its last
completed run) and schedule_subagent. delegate (older) starts a bounded copy of the lead.
Children stop only at a cap you set, cannot delegate, and receive no connections
shared by others; get_team_run is for Agent Teams only. Identical delegations in
one owner turn reuse their child; an explicit operation_key marks an intentional
job and changed inputs conflict. Use the child's full result reference; do not recollect
its data. Freezing a lead freezes its subagents first (each without a
current version, from its own run of the subtask), then pins their live versions; its
scheduled runs start the pinned versions with only their variables. A lead and its agents are a
fleet, listed as a project (fleet:<lead id>).
Projects and apps
Everything lives in a project: an agent and the helper agents it starts, their saved versions, schedules and triggers, pages, servers, files, storage and budgets. A new agent or a new piece of work is a new project: projects_plan, then projects_create after the user's OK on the plan and its price, with the task as brief; give the user the project's page in the app, the url of the answer (https://app.flymy.ai/projects/<owner>/<name>).
An agent made before projects stays where it is and keeps working with the same tools. Under it a project is a whole product in one flymy.yaml (flymy.ai/v1alpha1): pages and the only calls they may make, the agents behind them, the models they call, rented CPU and GPU servers, storage, budgets and who pays. A project is its config: every operation on it - create, clone, file edits (overrides), a change of its storages or budgets, stop, start, remove - is a plan and apply of its flymy.yaml and leaves a release; nothing it runs is set up or changed outside it; the files in its Storage are its data, read and written by path. apps_catalog is the contract (flymy.catalog.v1): what this platform runs of the language - each field served, skipped or refused by name, the built-in modules with their versions and inputs, platform tools, models, page and server calls and stacks with their limits and prices; read it before writing a flymy.yaml. apps_plan shows what applying a template creates and costs without spending anything and returns plan_token; apps_apply applies exactly the plan the user confirmed; apps_status follows it.
A project is an applied app, a page on its own or a fleet. For an app or a page: projects_templates lists the gallery; projects_plan then projects_create (after the user's OK on the plan and its price) makes the user's own copy; projects_get shows its pages, agents, servers, storages, money, errors and the tools its agents use; projects_agent is the agent in charge of it. To clone your own app, pass its app:<owner>/<app> id as template to projects_plan and projects_create: the latest successful release becomes a private copy with new resources and its own budget, without stored data, conversations or personal connections.
Another owner's app copies from an explicit gallery template or, when its owner made it public, from its link: projects_share (public: true) gives the owner the link https://app.flymy.ai/projects/<id> to post anywhere; anyone reads it with projects_get (its agents' chats and files too, read-only) and copies it with projects_copy - its agents (a lead with all its subagents), pages and config into their own account, never its data, conversations, money or connections - and the copy's setup chat (the Transfer agent) helps connect what it needs.
A project link someone pastes is such a project: projects_copy takes the link as it is, projects_get its id - https://app.flymy.ai/projects/<owner>/<name> is app:<owner>/<name>, /projects/<lead agent id> is fleet:<lead agent id> (the same under /shared/), and an older link carries the id itself (the part after /projects/, URL-decoded); if it is not theirs, offer projects_copy. A fleet is a lead agent and the agents it starts (fleet:<lead agent id>): projects_get and projects_errors read its agents, money, errors and diagram, projects_share and projects_copy share and copy it; it has no project agent and is not stopped or started - talk to its lead in the lead's chat.
To stop a project, projects_stop (with an operation_key): a release with runtime.state: stopped - its servers stop and the rest of their holds is refunded; its budgets pause; its pages answer project_stopped; its agents, storages and links are kept; nothing is charged; safe to repeat. To start it, projects_start: first without plan_token (the plan and its usd_per_hour; nothing changes), then, after the user's OK on that plan, with its plan_token and an operation_key.
While a project is stopped, apps_plan, apps_apply and apps_remove take no change but its state (project_stopped): start it first. To rename a project, projects_rename; to change its budget, projects_set_budget, only when the user asks; to delete it, projects_delete with confirm: true after the user explicitly confirmed it: a project with no history is removed for good, one with history is archived (stopped, its agents archived, out of the lists; its runs, money records and storages stay). projects_list and projects_get show status and lifecycle: whether it runs, sleeps or is stopped, and whether stop or start is allowed now.
Develop an applied app with apps_files (its template, one page at a time) and apps_plan / apps_apply with app plus overrides (only the files you change; the plan_token covers them). An app's project files - compositions, images, audio, fonts, renders - live in its Storage (kind: Storage, type files), one copy that its servers, its agents and you read and write by path: apps_storage_list (storages, then files by folder prefix), apps_storage_read, apps_storage_write (if_match: the sha256 you read) and apps_storage_delete.
Every runtime of an app gets the platform's handles from the config, never a key: an agent declares storage ({<name>: read | read_write}, or with paths such as compositions/) and gets the app_storage tools storage_list, storage_read, storage_write and storage_delete for exactly those; a rented server (flymy/rented-server@^1.2) declares calls - the app's embedded agents, its Jev, vision and image routes, its Storage (mode read or read_write: put, get, list by prefix and delete by path) and tool routes (a ToolAccess with only the actions it declares, held and charged like execute_tool, within its budget and rate limit) - and reaches exactly those from its code with the server SDK (flymy-server.mjs, flymy_server.py: flymy.call, flymy.put, flymy.get, flymy.list, flymy.delete) through an identity the platform starts it with, scoped to its release; its calls are metered like a page's and count against its sponsor pool (billing.sponsor.per_day_usd) and the project budget when you set them.
Never put an API key or token in a server's env: declare the call instead; apps_plan shows a server's calls under handles, their pool under budgets.server_calls and every agent's and server's storage under storage_access; projects_get shows servers[].handles and storages[].access.
HyperFrames video
Video written as HTML (HeyGen HyperFrames), a primitive and a block, where the platform has it on: search_tools finds the hyperframes tool and projects_templates lists hyperframes-studio; when they do not, tell the user it is not available yet. As a primitive, one call at a time through execute_tool (tool=hyperframes; search_tools then get_tool_schemas first): hyperframes_guide once, hyperframes_lint until no errors, hyperframes_snapshot to check frames, then after the user's OK hyperframes_render (MP4; $0.01 per output second at 1080p30, scaled by pixels and fps; the price bound is held first and a video is charged once) and hyperframes_render_status with its job_id until succeeded; give the public_url or publish_site a page that plays it.
As a block: the hyperframes-studio template in projects_templates is a page with a live HyperFrames player, a director agent (brief to composition) and a renderer agent (MP4); create it with projects_plan / projects_create and develop it with apps_files and apps_plan / apps_apply overrides. As a front app: the hyperframes-studio-server template runs the studio's server on a rented Fly CPU machine (flymy/stack-hyperframes@1: HyperFrames, Chrome, ffmpeg) that renders the MP4 itself and keeps renders and compositions in the app's Storage through its own calls; its page reaches the server through a relay session (it appears in projects_templates once its stack image is built on the platform).
First connection
Keep a first-time user's path concept-light. One implicit personal space plus the first connection of a toolkit uses the default connection. Connect it through the hosted setup link, retain the numeric configured-tool id, grant it to the same agent through available_tools, then run and freeze that agent. Do not require the user to create or name resource sets, groups, slots, grants, principals, revisions, or mappings for this first successful personal workflow.
The default is the safe projection of the same exact connection and authority model used below, so it can be expanded later without rebuilding the agent or reconnecting the account.
Connection instances and resource sets
Introduce this model only when a second same-toolkit account, reusable sharing, a group, or external-customer mapping creates the need. A toolkit, one authenticated account, a named MCP resource set, an agent grant, and a runtime binding are different identities. To connect the same catalog toolkit more than once, call add_tool once per account with a unique alias such as support or sales and retain each returned public_id. Omitting alias addresses only the idempotent legacy alias default.
Traverse bounded list_configured_tools cursor pages and filter by exact mcp_tool or alias. A direct execute_tool call selects a specific instance with its exact connection_id; omission is supported only while one eligible connection is unambiguous. Create one owner resource set with create_mcp_resource_set, management_mode=flymyai, and no principal_id. Replace its full membership with replace_mcp_resource_set_members using the current revision, then attach that set through mcp_resource_set_ids on update_agent.
Use create_agent_group when the same owner set belongs to several agents. list_mcp_resource_sets returns summaries with member_count and no nested members; use get_mcp_resource_set for one bounded full set or list_mcp_resource_set_members for a large membership collection. A principal_id is only for a customer-managed named mapping and requires management_mode=customer; never send external_principal_id. Agent groups are flat, and a subagent does not inherit a parent's connector authority unless it is explicitly included or granted.
Aliases and slots use only letters, digits, underscores, and hyphens, and remain labels only. When a runtime schema requires _flymyai_connection, pass the exact allowed connection public UUID and never guess from alias, email, row order, or toolkit slug.
Shipping an agent
Search_tools if tools are needed, projects_plan and after the user's OK projects_create once with the task as brief, poll get_run on the returned chat until complete (read_run_result for a truncated result), refine the same project in that chat with append_message, let the user pick from get_execution_price(cost_options=true), freeze_agent, poll get_compilation until compiled, run_frozen, then return the project id and its url, agent_id, execution_id, compilation_id, instruction_md, schemas, tested output, and integration code.
A fixed worker has no input_schema or placeholders. A reusable worker defines input_schema plus matching {{ placeholders }} before its accepted run; future runs pass variables, while freeze itself receives only the execution id.
Embedding an agent
This owner MCP surface authors, tests, freezes, and owner-tests the agent. Customer deployment publish, principal bootstrap, connection setup, and customer deployment runs are on the Agents REST API, not MCP tools on this owner surface. A separately launched trusted customer MCP surface may expose run_bound_deployment and get_bound_deployment_run only when its process configuration immutably binds one deployment, one external_user_id, and its mapping; those authority values are never model arguments.
Publish the same frozen version as one deployment. POST /api/v1/agents/deployments/{deployment_id}/connect-session/ with external_user_id and an exact required slot is the mutating bootstrap that resolves the principal and creates a hosted connection session. GET /api/v1/agents/deployments/{deployment_id}/access/ is read-only and never creates a principal; use it to inspect requirements and poll readiness after bootstrap.
Then call POST /api/v1/agents/deployments/{deployment_id}/run/ with external_user_id and a stable Idempotency-Key reserved for that canonical run request. For FlyMyAI-managed saved bindings, omit both resource_set_id and connections. For a customer-managed named mapping, create a principal resource set with management_mode=customer, store its public_id and revision in the customer's backend, and send resource_set_id plus optional resource_set_revision.
For a one-off explicit mapping, send connections. resource_set_id and connections are mutually exclusive. Reuse the key only for the identical request through the documented replay contract. Never blindly retry a deployment write after a timeout, lost response, or other ambiguous dispatch; persist the unknown outcome and reconcile it before any new dispatch. external_user_id selects the product customer's principal only; it does not choose an account by itself and does not change FlyMyAI billing, which remains on the deployment owner.
Do not confuse it with the OAuth user_id of this MCP session. Do not invent client.deployments calls unless the installed SDK exposes them. If embedded preflight rejects a toolkit, report it and keep the logical worker whole instead of silently splitting it. Full verified sequence: https://flymy.ai/skill.md
Retries and unknown outcomes
Run_agent, run_frozen, execute_tool, call_mcp_server, create_mcp_resource_set, create_agent_group, and upload_agent_file require a caller-owned stable operation_key reserved before the first dispatch. Reuse that key only for the identical canonical request. MCP authoring creates and Team admission replay the exact stored 201 response and reject reuse for a changed body. A timeout, lost response, malformed success, or other post-dispatch ambiguity is an unknown outcome: persist and reconcile it, and never automatically dispatch the operation again.
Only a typed, proven pre-effect rejection is retryable. run_agent, run_frozen and execute_tool answer outcome=rejected with the reason when the backend or the provider refused the request before anything happened (invalid arguments, filters or limits, missing setup, agent or compilation, a provider's refusal): nothing started, so fix the arguments and use a new operation_key.