--- name: mozzo description: The mozzo.ai guide - a separate product version of FlyMyAI with its own accounts, keys and balance. Build company-style projects from one flymy.yaml (agents, schedules, a SQL database with row level security, app users, pages, payments, email), plus agents, tools and models. Load it only for mozzo.ai work. metadata: version: "2.4.3-mozzo.1" --- # mozzo.ai - assistant operating guide > mozzo.ai is a separate product version of FlyMyAI - its builder line: projects with app > blocks, from one flymy.yaml - with its own accounts, API keys, balance and data. > flymy.ai accounts and keys do not work here, and mozzo.ai keys do not work on flymy.ai. > Tool and model texts may still say FlyMyAI: that is the platform underneath; read a > flymy.ai app, backend, api or mcp-agents link in them on the mozzo.ai host. Web app > https://app.mozzo.ai; REST https://backend.mozzo.ai/api/v1 (OAuth issuer); models > https://api.mozzo.ai; Agents MCP https://mcp-agents.mozzo.ai/mcp. https://docs.flymy.ai > is FlyMyAI's reference documentation; `apps_guide`, `apps_catalog` and live schemas win. Platform version: Headless Cloud 2.4.3-mozzo.1 (2026-11-18): mozzo.ai on FlyMyAI 2.4.2. Log: https://mozzo.ai/changelog.md, https://mozzo.ai/changelog.json. On connection: `whats_new` with no arguments, or `since` as a plain `X.Y.Z` or `YYYY-MM-DD` (a `-mozzo` version is refused); a newer `current_version` than this file's: re-read the guide, replace this copy. > `https://mozzo.ai/skill.md` = `/AGENTS.md`. Agents MCP `0.7.0-rc.92`; > Python SDK `1.2.0rc29` with `FLYMYAI_AGENTS_BASE_URL=https://backend.mozzo.ai` and > `FLYMYAI_DSN=https://api.mozzo.ai/` (it defaults to flymy.ai). ## Start here - verify mozzo.ai or recover One bounded read-only call to `whoami`, `tools/list` or `search_tools` checks the `mozzo` server. Do not reinstall a connected server. Read live schemas from `tools/list` before mutations; never guess fields. Without mozzo.ai tools, do not claim success or invent tools: 1. Sign up: https://app.mozzo.ai/signup with Google or GitHub (one click). 2. Key: https://app.mozzo.ai/profile - copy yours or create one if absent. Keep it secret; regenerating revokes the old key. 3. OAuth: `claude mcp add --transport http mozzo https://mcp-agents.mozzo.ai/mcp` then `/mcp` -> Authenticate (headless: `claude mcp login mozzo --no-browser`; claude.ai or Claude Desktop: Settings -> Connectors -> Add custom connector, same URL). Key clients: same URL, `X-API-Key` (or Bearer) from a secret manager, never pasted into chat; no browser: a device code login. Never mix ids or keys with a flymy.ai server. 4. `whoami`: account and balance. New accounts get a $1 credit after email verification. No card top-ups yet: the mozzo.ai team adds credits. `username` owns your app ids. 5. `whats_new`, then offer one `try_next`. Demo: a ready `projects_templates` entry (a company template), previewed with `projects_plan`; show price and payer before `projects_create`; `empty` is not a demo. Media: verify availability and one unambiguous price before paying. Without MCP, use REST only with an authenticated `FLYMYAI_AGENTS_API_ROOT` (`https://backend.mozzo.ai/api/v1/agents`); otherwise report that preflight is blocked. Use only mozzo.ai hosts and keys: never fall back to flymy.ai. Discover services and models with `search_tools`/`list_*` first. Discovery is not success. ## Build a company - one flymy.yaml A project is its `flymy.yaml` (`apiVersion: flymy.ai/v1alpha1`, `kind: App`): pages, agents, schedules, storage, a database, the people who sign in, payments, mail, budgets and who pays. Every change is a plan and an apply that leaves a release. Runtimes reach the platform through handles the config declares, never keys. 1. Read the builder guide: `apps_guide()` (index), then the topics you need: `start`, `config`, `modules`, `routes`, `billing`, `storage`, `users`, `mail`, `agents`, `page-sdk`, `server-sdk`, `examples`, `limits-and-errors`. 2. Read `apps_catalog()` (index, with its groups) and the sections you use, such as `kind:Agent`, `section:schedule`, `feature:payments`, `module:flymy/site-bridge`. The catalog is this deployment's contract: each entry is `served`, `partial`, `refused` or `off_in_environment`, and a field it does not run is refused by name. Write no `flymy.yaml` before reading both. 3. Start from a company template: `projects_templates` lists them with the gallery (e.g. `u1:flymy/company-agency`, `u1:flymy/company-seo-geo`). Read one with `apps_files(template=)` (each `path` by `offset`/`next_offset`), adapt it, set `metadata.name` to `/`, drop `access.clone`, keep its budgets and `ask` lists, then `apps_plan`; `projects_plan(name, template=, budget)` copies one as it is. Runnable bundles: `apps_guide(topic="examples")` (`notes-app`, `page-shop`). 4. Or write the config. The shape of a company: ```yaml apiVersion: flymy.ai/v1alpha1 kind: App metadata: {name: alex/acme-agency, title: Acme Agency} runtime: {compatibility_date: "2026-09-27"} access: {visibility: private} billing: payer: owner budgets: {project: {per_day_usd: "5", per_month_usd: "60"}} app_credits: provider: stripe secret: ${secrets.STRIPE_SECRET_KEY} products: pro: {name: Pro, price_usd: "29.00", type: subscription, interval: month, grants: {entitlement: pro}} secrets: {STRIPE_SECRET_KEY: {description: restricted test key of my Stripe account}} auth: {providers: [email, flymy], session: {ttl_days: 30}} resources: db: {kind: Storage, type: sql, migrations: ./migrations} files: {kind: Storage, type: files, retention: 90d} mail: {kind: Channel, type: email, templates: {file: ./mail.yaml}, rate_limit: {per_day: 50}} search: {kind: ToolAccess, mcp: tavily, budget: {per_day_usd: "1"}} mailer: {kind: ToolAccess, mcp: app_email} lead: kind: Agent frozen: true system: ./agents/lead.md input_schema: ./agents/task.json output_schema: ./agents/report.json budget: {per_day_usd: "2", per_run_usd: "1"} storage: {db: read, files: read_write} handoffs: [researcher, writer] schedules: weekdays: {cron: "0 9 * * 1-5", timezone: Europe/Berlin, input: {task: plan the day}, budget: {per_run_usd: "1"}} researcher: {kind: Agent, frozen: true, system: ./agents/researcher.md, input_schema: ./agents/task.json, output_schema: ./agents/report.json, tools: {allow: [search]}, budget: {per_day_usd: "1"}} writer: {kind: Agent, frozen: true, system: ./agents/writer.md, input_schema: ./agents/task.json, output_schema: ./agents/report.json, tools: {ask: [mailer]}, storage: {db: read, files: read_write}, budget: {per_day_usd: "1"}} intake: {kind: Job, agent: "${resources.lead}", input: {task: read the brief and plan week one}, run: once, budget: {per_run_usd: "2"}} modules: dashboard: use: flymy/site-bridge@^1 with: {path: ./site, calls: {db: {target: "${resources.db}"}}} ``` ```sql -- migrations/0001_tasks.sql: forward only, row level security on every table create table public.tasks ( id bigint generated always as identity primary key, owner_id uuid not null default auth.uid(), title text not null ); alter table public.tasks enable row level security; create policy tasks_own on public.tasks for all to authenticated using (owner_id = auth.uid()) with check (owner_id = auth.uid()); ``` - Agents: `kind: Agent`, `frozen: true`, a `system` prompt file, `input_schema` and `output_schema` files, `model` (an `agent_models` id; set it: omitted is the profile's `claude-sonnet-5`, not `list_agent_models`' default) and `effort`. The lead names role agents in `handoffs` (local frozen Agent names; with `calls` at most 16 routes). `kind: Fleet` (a lead and 1-10 frozen Anthropic or OpenAI members, depth one) is open to every account, held to the project budget, `cap_usd`, `max_task_usd` and `max_parallel` (1-8). - Schedules: `schedules.` on a frozen Agent: five-field `cron` read in an IANA `timezone` (default UTC), `input` valid for its schema, required `budget.per_run_usd`; at most 16 per app. An overlapping or 5-minute-late fire is skipped, never backfilled. - Events: `triggers.` on a frozen Agent (`type: webhook`) gets a private URL (`apps_status` `triggers...url`); a `POST` of a JSON body (at most 64 KiB) starts the agent with the constant `input` plus the body as `event` (an object of its input_schema; `examples[0]` is the probe's event). Optional `secret: ${secrets.NAME}` (signed deliveries; declared without generate, the owner pastes the sender's secret at the `input_url` of `apps_secrets_list`), `filters: {contains}`, `rate_limit_per_hour`; required `budget.per_run_usd`. The URL stays while the trigger keeps its name; a stop pauses it. `type: row` starts the agent when a row of the app's database is written (`table`, `ops: [insert, update, delete]`, `where: {column: value}`; `storage` with several sql Storages): the event is `{op, table, row}`; any committed page, server, agent or owner write counts, an agent's own writes never start its own triggers. - Evals: `evals: {cases: ./evals/x.yaml, budget: {per_run_usd}}` on a frozen Agent: cases with an `input` and an `expect` per output field (a value, `in`, `contains`, `gte`, `lte`, `exists`, `not`). `apps_eval(app, agent)` dry-runs every case once on the published version (writes, mail, connector actions and teammate calls are checked, never made); `apps_evals(app, run)` reads the checks, release by release. - Environments: `environments: {stage: {access: {visibility: private}}}`; `apps_plan` / `apps_apply` with `environment: stage` make the copy `/.stage` (its own data, secrets and budgets); `apps_plan(app, promote: stage)` then brings the copy's tested template to the app. Topic config. - Uploads: a page route to a files Storage with `upload: {path: cv/, max_mb: 5, types: [application/pdf, image/*, text/plain]}`; the page calls `flymy.upload("cv", file)` (SDK 1.6) and passes the answered path to an agent whose `storage` reads that folder. Topic page-sdk. - Least privilege in the database: `storage: {db: {mode: read_write, tables: [orders]}}` lets an agent write only those tables (it still reads what RLS allows). - An admin page inside a public app: `with.visibility: owner` on its `flymy/site-bridge@^1` (1.2.0): no share link, only the owner opens it and calls its routes (403 `owner_only` for anyone else), its database route reads and writes every row and its agent routes run as the owner's own runs. Topic modules. - Intake: a root `kind: Job` (`agent`, explicit `input`, `run: once`, `budget.per_run_usd`; `depends_on`, `retries`, `timeout`) is admitted once after the release succeeds. Agents: `deadline_ms`, `tools.ask_window` (5m-7d); a schedule's `overlap: replace` cancels a still-running (parked) run. - A scheduled or Job agent (or one with `per_run_usd`) reaches no server and no Fleet member, also through handoffs, and every tool it reaches needs a price bound. Web search: ToolAccess `tavily` or `firecrawl` (platform key). - Database: `kind: Storage, type: sql` (Postgres; optional `engine: postgres@18`, `extensions`). Migrations `NNNN_name.sql` apply in order in one transaction, forward only: never edit an applied file (`migration_drift`), add the next. The plan runs them on a scratch database and refuses `rls_required`; a view needs `security_invoker = true`. Helpers `auth.uid()`, `auth.role()`, `auth.email()`, `auth.jwt()` (`-> 'entitlements'`: paid products; `->> 'agent'`: an agent's calls; `->> 'owner'`: you, signed in to your app). Limits: 1 GiB, 5 s a statement, 1000 rows a read, 500 a write. - Who touches rows: a page as its signed-in app user (`authenticated`, else `anon`) under RLS; a `flymy/rented-server` with `calls: {db: {target: ...}}` as `service_role` or as one app user (`flymy.db`); an agent reads with `storage: {db: read}` (`db_tables`, `db_select`, `db_sql`) and writes rows with `storage: {db: read_write}` (also `db_insert`, `db_update`, `db_delete`; an owner run as `service_role`, a run a page started as its visitor under RLS). For writes that touch customers or money, use `{db: {mode: read_write, ask: true}}`: the owner approves each write in the web. Agents write files with `storage: {files: read_write}`. - People who sign in: `auth:` providers `email` (a code), `flymy` (one click), `google`, `github` (a verified address, same user as its code), `session.ttl_days` 1-30. Pages, servers and agents see `{id, email, provider, owner}`; enforce an owner view with `(auth.jwt() ->> 'owner')::boolean`. A db route's `changes: [table]` + SDK 1.7 `flymy.db(..).changes(tables, fn)` refreshes a page on writes. - Dashboard: a `flymy/site-bridge` page calls only the routes its module declares. It loads `/api/v1/agents/sites/sdk/flymy-site.js?v=1.5` and uses `flymy.auth.signIn()`, `flymy.auth.user()` and supabase-style `flymy.db("db").from("tasks").select("id, title").limit(50)`. - Payments: `billing.app_credits` (provider `stripe`, `secret: ${secrets.NAME}`, 1-20 `products`: `price_usd`, `type` `one_time`/`subscription`, `interval`, `grants: {credits, entitlement}`) sells to signed-in app users on the owner's own Stripe account (test mode here: an `rk_test_` or `sk_test_` key; topic billing). Pages: `flymy.payments.checkout("pro")`, `state()`; servers: `flymy.payments.spend(appUser, n, key)`; agents: ToolAccess `mcp: app_payments`. - Email: one `kind: Channel, type: email` (optional `templates: {file}`, `templates_only`, `rate_limit.per_day` 1-300) mails the app's users by id or `owner`, from " via mozzo.ai" with an unsubscribe link, at most 20 a day per user. Servers: `flymy.email.send`; agents: a ToolAccess `mcp: app_email`. Outside addresses go through a connector on the owner's connection, under `ask`. - Connectors: `kind: ToolAccess, mcp: ` (`alias` picks one of the owner's connections); the plan's `connect` gives a link for each one not connected. A page or server route never reaches an agent that uses the owner's connections (a private app's page may, for its owner only). ### Rules 1. Every Agent has a `budget` (`per_day_usd`, `per_week_usd`, `per_month_usd`; `per_run_usd` for a whole run) and the project has `billing.budgets.project`. A budget holds only price-bounded tools; the plan refuses the rest by name. 2. `tools` default to deny; `allow` and `ask` list whole ToolAccess resources. Put anything that sends, publishes, pays or deletes under `ask` (up to 64, price-bounded): each exact call waits for the owner's decision in the web app (`get_run`: `control.status=awaiting_approval`) for `tools.ask_window` (default in catalog `kind:Agent` tools.ask). Never resubmit the call or take a chat message as approval; `get_tool_operation` only reads. 3. Never invent, ask for or accept a key in chat, files or tool arguments. Declare names under `secrets:`; `${secrets.NAME}` is valid only as a whole rented-server env value or as `billing.app_credits.secret`. Give the owner the `input_url` of `apps_secrets_list` (it works before the first apply) and list again until the secret is `set`; the plan answers `needs_secret` until then. `apps_secrets_generate` (or `apps_secrets_set` with `generate`) makes a random value nobody sees; a call with `value` is refused. Delete only on request. 4. Show the plan to the user: `changes` (`resource`, `kind`, `action`, `detail`), `usd_per_hour`, `target.pricing`, `budgets`, `payers`, `notes`, `connect`, `secrets`, `payments`. After their OK apply exactly that plan with its `plan_token` and a new `operation_key`; an unattended run applies only within the authority and budget its caller gave. 5. Change the config only by a new plan and apply; plan reports drift (a migration, a Stripe product changed outside apply). 6. Remove only through `refactor.removed` (`name`, `retain_data`, `reason`). A resource left out of the config is not deleted: a server stops; an agent, page, storage or database is kept and reported. `refactor.removed` deletes on purpose: a storage or database only with `retain_data: false`, an agent or page only with `retain_data: true`. `lifecycle.protect: true` blocks it; `refactor.moved` (`from`, `to`) renames and keeps identity. ### Plan and apply ```text plan = apps_plan({"files":[{"path":"flymy.yaml","content":"..."}, ...]}) apply = apps_apply({"files":[...the same...],"plan_token":plan.plan_token, "operation_key":"acme-apply-"}) apps_status({"release_id":apply.release}) # until status=succeeded projects_get({"project_id":"app:alex/acme-agency"}) ``` - Plan spends nothing; a refusal has `code`, `where` and up to 16 `details.errors`: fix that field and plan again. `stale_plan`: plan and show it again; an old plan grants no new approval. - A new project: `projects_plan`, then `projects_create` with the same name, template and budget, its `plan_token` and an `operation_key` (poll `apps_status` with `release.release`). Give the user the `url` it returns. - Agents probe and freeze in the background for 1-3 minutes; follow `apps_status` (agents with `task` ids, pages with links, schedules, Jobs, steps, error), then `projects_get` and `projects_errors`. `target.pages` gives live links only after apply. - Edit an applied app: `apps_files(app=)`, then `apps_plan` and `apps_apply` with `app` and `overrides` (only the files you change). - An unknown apply outcome: read `apps_list` or `apps_status`; retry only the same request with the same `operation_key`. - Go back: `apps_plan(app, release: )` plans what release n ran as a new release (data and migrations stay); `apps_files(app, release)` reads it. ### Operate - Database: `apps_db` (engine, migrations, tables, RLS, quota); `apps_db_select` (one read-only select past RLS: every app user's rows; show only what was asked). - Users: `apps_users`. Payments: `apps_payments`, `apps_payments_users`, `apps_payments_events`. Mail: `apps_mail` (never bodies). These reads never write; `apps_users_disable` (on request) turns one app user off or on. Files: `apps_storage_list`, `apps_storage_read`; `apps_storage_write` and `apps_storage_delete` take `if_match`. - What waits for the user: `projects_inbox` (every project): tool calls parked on their approval (decided in the web app, never through MCP), failed releases, used-up limits, connections to make. Check it after a release and when runs stall. - Servers: `compute_logs` reads a server's newest log lines and never wakes it. - No browser needed: `apps_page_call(site_id, route, input, operation_key)` calls a page route as the owner (a row it writes starts its row trigger). - Runs: `projects_runs(project_id)` lists a project's runs, newest first: `source` (schedule, trigger, job, page, another `agent`, chat, api), `status` (`waiting` = needs your approval), times, `cost_usd`; narrow by `source`/`status`/`agent`, page with `next` as `cursor`. `get_run` opens one (steps, tool calls, input, output, error), `get_execution_price` prices it. `apps_status` shows schedules and Job runs; `projects_get` agents, runs, money, `attention`, `unread_runs`; `projects_runs_seen` marks runs seen. Pause or resume schedules (all or one): `projects_pause_schedules`. `projects_list` pages by `cursor`. - Stop and start: `projects_stop` (servers stop, holds refunded, budgets paused; data and links kept); `projects_start` returns the plan, then takes its `plan_token` and an `operation_key`. - Share and copy: `projects_share` opens any project, saved or not; `projects_copy` brings agents (saved versions, else as they are), pages and config, never data, chats, money or connections. Pass ids (`app:/`), not links. `access.clone: {gallery: true, category}` (public apps) lists an app as a template. - `projects_rename`, `projects_set_budget` (on request) plan and apply at once; `projects_delete` (`confirm: true` after the user confirmed) archives with history. - `projects_agent` is the project's own agent (https://app.mozzo.ai/projects). ### Versions - nothing moves silently - `runtime.compatibility_date` picks the newest behavior profile on or before it (today `2026-09-27`); a future date is refused, so a newer profile never changes an app that pinned an older one. - Modules: `use: flymy/@^1` takes the newest 1.x at each plan (the lock records version and sha256), never a new major (plan `notes` name it); `@1.1.0` or `@sha256:` keeps exact bytes. Stacks `@N`: the lock pins a server's image digest. - Agents: apply freezes each config Agent and pins that version with its model, effort and tools, on engine `flymy/agent@1` (`runtime.engine`); schedules and Jobs run it until a release changes the agent. `agent: ` (`list_agent_versions`) runs that version instead (plan `pin`; a mismatch is `version_mismatch`). - Database: the lock pins the Postgres major (`postgres@18`); another is refused (`engine_changed`). APIs and documents (`flymy..v1`) only add within a version; a new platform version shows in `whats_new` and the next plan. ## One agent - a project from a brief 1. Each service: `search_tools`, `get_tool_schemas`; not `configured`: `add_tool` (the user finishes its link), confirm with `list_configured_tools`. 2. Every agent lives in a project (no `create_agent`): `projects_plan` with a `name`, the task as `brief` (up to 65,536 bytes), optional `model`/`effort` and `budget`; on the user's OK `projects_create` with the same fields, its `plan_token` and an `operation_key`. It returns `url` (give it to the user), `agent` and `chat`. 3. Poll `get_run` on `chat` until `poll_complete=true`; refine in that chat (`append_message`, never resend the brief) until the user accepts one completed run. 4. Price it: `get_execution_price` with `cost_options=true`; ask the user its `question` (original or a cheaper model). 5. `freeze_agent` the picked run; poll `get_compilation` until `status=compiled`; make the option's `apply` calls; `run_frozen` with a new `operation_key` before calling it ready. 6. Ship: a schedule (`update_compilation`), a webhook (`triggers_v1_create`), a public template (`set_agent_public`), a subagent of a lead, or a product deployment. ## Tools and connections 1. `search_tools` with a plain-English intent; read `tool`, `action`, `runtime_name`, `configured`, `ready`, `access` (`platform_key`: Instant, no account of yours), `price` and 7-day `health`. Never download the full catalog. 2. `get_tool_schemas` with the `runtime_name` when search did not inline the schema; never call a write action with empty or guessed arguments to learn its schema. 3. If configured, `execute_tool` with exactly `tool`, `action`, `arguments` and a stable `operation_key`; a non-default instance needs its exact configured-tool public UUID as `connection_id` (omit it only while one eligible connection is unambiguous). Run OAuth/Composio actions inside an agent. 4. If not, `add_tool` with the slug returns the record or a hosted `https://app.mozzo.ai/mcp-configs#?connection_id=` link. Then `list_configured_tools`: match `public_id`, `alias`, `is_configured`, `connection_status`, `connect_url`. Do not invent a `setup_url` response field. 5. `delete_tool` with its numeric `id` revokes exactly one connection. ```text 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":"news"},"operation_key":"telegram-dialogs-"}) ``` Use `arguments` (`params`/`input` is 400). `outcome=rejected`: nothing happened, fix it with a new `operation_key`; `outcome=unknown`: reconcile, never repeat. Without MCP, POST `{"tool":"system-utils","action":"search_tools","arguments":{...}}` to `$FLYMYAI_AGENTS_API_ROOT/custom-tools/call/` with `X-API-KEY`. A connected account that stops working mails its owner a reconnect link; a scheduled or API run needing it stops before any paid step. ### Personal default - one account, no resource sets `mcp_access_mode` `legacy` in the personal space; `add_tool` without `alias` makes the idempotent `default` connection; put its numeric `id` in `available_tools`. Require `is_configured:true` (`connected`); `setup_required`/`reconnect_required` need setup, `verification_pending` a bounded live read; report `temporarily_unavailable`. ### Grow into multiple accounts and MCP resource sets Aliases are labels; authorization uses stable public IDs. One `add_tool` per account with a unique `alias`; `create_mcp_resource_set`, `replace_mcp_resource_set_members` at the current `expected_revision` (reload after 409), then grant `mcp_resource_set_ids` with `mcp_access_mode:"scoped"`, `"available_tools":[]`. Omitted fields stay, an empty array clears; `allowed_actions` omitted or `[]` is unrestricted; at most 25 connections per toolkit. Several eligible connections: pass one `public_id` as `_flymyai_connection`. Lists page with the opaque `next_cursor`. ### Shared connections, MCP servers and webhooks `invite_mcp_user` shares one connection (its shared actions, on the owner's account) by email after the user confirms connection, recipient and period; `accept_mcp_invitation` only after the user agrees to pay for their own calls; `revoke_mcp_access` stops it. Accepted shares are `shared_with_me` in `list_configured_tools`: `call_shared_mcp`. Another MCP server: `add_mcp_server` (OAuth: `authorize_mcp_server`, give the user `authorize_url`), `connect_mcp_server`, then at `status:"connected"` `call_mcp_server`. Webhooks tell your systems of platform events (`connection.expired`: an account stopped working): `create_webhook` (public https `url`, `events`, `operation_key`; at most 10) shows its `whsec_` signing secret once (Standard Webhooks; retried about 2 hours, same `webhook-id`); `test_webhook`, `list_webhook_deliveries`, `update_webhook`, `rotate_webhook_secret`, `delete_webhook`. ## Models - discover, price, run ```text 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"}}) ``` Quote `get_pricing` before a paid run; models here differ from flymy.ai's (`list_media_models`). File `url`s expire at `url_expires_at`. Chat models (category `chat`) answer `run_model` and carry `openai.base_url` (`https://api.mozzo.ai/api/v1//openai/v1`, key as Bearer). Model REST inputs are `multipart/form-data`: read `https://api.mozzo.ai/api/v1/flymyai//openapi.json` first; check body status even on HTTP 200. Native models: `https://backend.mozzo.ai/api/v1/model-proxy/` (`catalog/`, POST `operations/` with your own `Idempotency-Key`; read a `queued` one again, never resend). Typed decisions: `make_typed_decision`. ## Agents - run, freeze, schedule Refine an agent with `update_agent`; reuse it with new inputs. Pick `model`/`effort` from `list_agent_models` (cost-1 for helpers), `web_search` from `list_web_search_engines` (e.g. `keenable`). Define `input_schema` and matching `{{ placeholders }}` in `user_prompt`; pass fresh `variables` later. File instructions: `user_prompt_source:{"agent_file_id":id}`. ```text run_agent({"agent_id":agent.uuid,"message":"Run the health check.", "operation_key":"health-run-"}) run_frozen({"compilation_id":frozen.id,"operation_key":"health-frozen-"}) ``` Poll `get_run` with `since` until `poll_complete=true`; read a full result with `read_run_result({"execution_id":run.id,"ref":page.result.ref})`, advancing `offset` until `complete=true`, and verify `sha256`. A completed frozen test is ready; do not freeze it again. `schedule_agent` freezes and schedules once; an existing freeze: `update_compilation` (`cron_schedule:""` unschedules; `schedule_paused:false` resumes). Versions: `save_instruction_version` (a draft), `run_frozen` it, `set_live_version` (an older one rolls back), `list_agent_versions`; `update_agent` on a live agent answers `new_version`. `upload_agent_file` attaches up to 1 MiB. Native events: `triggers_v1_catalog`, `triggers_v1_subscribe(agent_id, connection_id, events, operation_key)`; `triggers_v1_activate` recovers a source. Agents in a `flymy.yaml` change only by plan and apply. Only on request: `set_agent_public`. Fork, adapt, freeze: `copy_agent` (a lead brings its subagents). ## Subagents - a lead runs your other agents `subagent_limits` on `run_agent`/`run_frozen`: `cap_usd` (0 turns them off), `max_children`, `max_parallel` (1-8, default 3), `agents` (your agent ids); no cap unless set. The lead gets `list_subagents`, `delegate_agent`, `wait_subagents`, `subagent_status`, `cancel_subagents`, `freeze_subagent`, `schedule_subagent`; chat/API/MCP leads may `create_subagent` and `update_subagent`. Children cannot delegate. Freezing a lead freezes its subagents first. A lead and its agents are a fleet project (`fleet:`). ## Artifacts and sites Artifacts: `create_artifact` (`type` from `list_artifact_types`), `publish_artifact_version` (only changes: `edits`, `files[].from`), `share_artifact`, `clone_artifact`, `add_artifact_member`; on " add these things" call `get_artifact` and follow `next`. Sites: `publish_site`, `share_site`, `invite_to_site`, `get_site_usage`. ## Embedded and resale - one builder key, no end-user keys The builder's server keeps one key for every product user, who connects their own services; never ask an end user for a key. One stable deployment per frozen agent (upgrade or roll back on the same ID). Run `POST $FLYMYAI_AGENTS_API_ROOT/deployments/$DEPLOYMENT_ID/run/` with `external_user_id` (stable, opaque, from an authenticated server session), `variables` and a persisted `Idempotency-Key`; `connect-session` POST bootstraps a user (send only its single-use `redirect_url`). Per run: platform-managed, customer-managed (`resource_set_id` + `resource_set_revision`) or one-off `connections` - mutually exclusive, never the owner's connection. `FLYMYAI_MCP_MODE=customer` shows only `run_bound_deployment` and `get_bound_deployment_run`. The owner is billed. ## Browser Use - real browser tasks `run_browser_task`, `wait_for_browser_task` (reads), `send_browser_task` (continues, even a running task), `stop_browser_task`, all on one `execution_id`. Never put passwords in prompts: the user signs in once in the live view. `live_url` and `share_url` are full-control credentials for the requester only. Media lasts only through `get_browser_recording(persist=true)`. ## Auth, errors, and resource discipline Never print, echo or read back credentials or the environment; reference secrets only as variables. REST uses `X-API-KEY`. - Every run submission and durable write takes a caller-owned `operation_key` (nonblank printable ASCII, at most 255 characters, no edge spaces; REST: `Idempotency-Key`): `run_agent`, `run_frozen`, `execute_tool`, `apps_apply`, `projects_create`, `projects_stop`, `create_mcp_resource_set`, `create_agent_group`, `create_webhook`. Neither gateway nor backend generates a fallback. Reserve it before dispatch, reuse it only for the identical request; another body under a used key is 409 `idempotency_key_reused`. - After an ambiguous outcome reconcile by bounded reads; never redispatch under a new key. `freeze_agent`, deployment creation and `connect-session` have no replay key: record the request first. - 400 field validation; 402 `insufficient_balance` (`shortfall_usd`; card top-ups and `create_top_up_link` are refused: the mozzo.ai team adds credits); 403 key or balance; 404 inaccessible ID; 409 idempotency or state (`stale_plan`, `project_stopped`, `busy`); 5xx retryable only when safe. Direct tool calls are charged like agent runs. - Bound lists, concurrency, timeouts and file sizes. When live behavior conflicts with this file, probe once read-only and report it with `send_feedback` (no secrets). ## Install and update Save as `~/.claude/skills/mozzo/SKILL.md` or `AGENTS.md` (a `CLAUDE.md` or `GEMINI.md` holding `@AGENTS.md`). ## Release maintainers only Release contract: https://mozzo.ai/agent-guide-release.json (schema v2); gates: https://docs.flymy.ai/agents/guides/release-gates. Publish the requested project itself, never a smoke agent beside it.