# Embedded and resale builder reference

> The complete REST sequence behind one builder key - publish a frozen agent, page versions, connect each product user's accounts, choose the customer mapping, run, and meter.

This page holds the complete builder sequence from the public agent guide at
[flymy.ai/skill.md](https://flymy.ai/skill.md), which keeps only its essence.
The step-by-step walkthrough is
[Create, Freeze & Embed](https://docs.flymy.ai/agents/guides/serverless-agents.md), the customer
identity model is [Per-customer MCP Access](https://docs.flymy.ai/agents/guides/embedded-mcp.md), and
named customer mappings are covered in
[Multiple MCP Accounts & Resource Sets](https://docs.flymy.ai/agents/guides/mcp-resource-sets.md#product-customer-mapping-modes).

Deployment runs require a nonblank printable ASCII `Idempotency-Key` of 1-255
characters with no leading or trailing spaces. Neither gateway nor backend
generates a fallback: reserve the key with the canonical request before the
first dispatch and reuse it only for the identical request. Leading or trailing
spaces, non-ASCII characters, and control characters fail locally.

## Choose the mode

| Mode | FlyMyAI identity and key | Service connections | Billing |
| --- | --- | --- | --- |
| Personal | The account connected to this assistant | That account's services | That FlyMyAI account |
| Embedded or resale | One builder key on the builder backend | Each product user's own services | FlyMyAI charges the builder; the builder charges its users |

Never ask every embedded end user to create a FlyMyAI account or paste a FlyMyAI key.

## After freeze, choose one integration branch

- **Owner/private** - call
  `POST /api/v1/agents/compilations/{compilation_id}/run-instruction/` with a
  persisted `Idempotency-Key`; use the same key only to replay the identical
  request.
- **Product customers with their own connected service accounts** - publish the
  same frozen version as one stable deployment, create hosted connection links
  per required slot, and call
  `POST /api/v1/agents/deployments/{deployment_id}/run/` with
  `external_user_id`.

`external_user_id` selects that product customer's isolated principal and
supported connector bindings. It does not switch the FlyMyAI billing identity:
FlyMyAI charges the deployment owner, and the builder applies its own customer
billing, quota, credits, or markup.

Be precise about the boundary: the normal owner Agents MCP surface can create
an agent with its project, then run, refine, freeze, and owner-test it.
Deployment publish and customer connect-session remain Agents REST operations.
A separately provisioned customer-bound MCP surface can run one
already-published deployment for one customer, but only after trusted server
configuration binds the deployment, `external_user_id`, and optional mapping.
Those authority values are never model-call arguments. Do not confuse customer
identity with the OAuth `user_id` of an owner MCP session, and do not invent
`client.deployments` calls unless the installed SDK version actually exposes
them.

If embedded preflight rejects a toolkit, keep the logical worker whole and
report the unsupported requirement. Do not silently turn it into two agents or
bypass preflight.

If a request already says the agent will be embedded in a product or names
product customer IDs, take the customer-deployment branch directly. Do not ask
whether to split the workflow or create one agent per customer.

For the owner/private branch, the exact REST schedule update for an existing
compilation is:

```bash
curl -fsS --max-time 30 -X PATCH -H "X-API-KEY: $FLYMYAI_API_KEY" \
  -H 'Content-Type: application/json' \
  --data '{"cron_schedule":"0 9 * * 1-5","timezone":"UTC","schedule_variables":{}}' \
  "$FLYMYAI_AGENTS_API_ROOT/compilations/$COMPILATION_ID/"
# Clear it through the same route with {"cron_schedule":""}.
```

## One builder key, no end-user keys

The builder wires FlyMyAI once:

```text
product client -> authenticated builder backend -> stable FlyMyAI deployment
  -> principal unique to (deployment, external_user_id) -> that principal's mapping
```

`external_user_id` is the builder's stable, opaque, non-secret ID, at most 255
characters, and must not start with the reserved `flymyai-owner-` prefix.
FlyMyAI creates the principal lazily. End users do not sign up for FlyMyAI and
never see the builder key. When a connector needs authorization, the builder
redirects that user through a short-lived hosted connection URL. Runtime lookup
rechecks every saved, named, or explicit connection against the same principal.

Rules:

- Keep `FLYMYAI_API_KEY` only in a server secret manager. Never expose it to clients, URLs, logs, or chat.
- Before an MCP-authored agent crosses to deployment REST, call MCP `whoami`
  and `GET /api/v1/agents/me/` with the builder key. Require the same
  `user_id`; otherwise stop, because the REST key cannot publish another
  owner's agent.
- Derive `external_user_id` from the authenticated server session. Do not accept an arbitrary client-supplied ID or use an email or secret.
- Reserve and persist a stable `Idempotency-Key` with the canonical deployment-run request before dispatch. Reuse it only for the identical request through the documented replay contract. Never automatically repeat a write after a timeout, lost response, or other ambiguous dispatch - persist the unknown outcome and reconcile it first. A replay after the first response returns the same execution while the idempotency record exists; successful records are eligible for cleanup after 2 days. Reuse after cleanup can create a new execution. Changed-body reuse returns 409; a concurrent replay can return 409 while the first is still committing.
- FlyMyAI bills the deployment owner. Automatic onward charging, billing passthrough, and per-user cost rollup do not exist today.
- Persist `(external_user_id, deployment_id, mapping_mode, resource_set_id,
  resource_set_revision, execution_id, idempotency_key)`, omitting mapping
  fields only when that mode does not use them. Fetch the settled execution
  price and apply your own quota, credits, markup, or invoice.
- Call Models API separately from the builder backend and map its request ID into the same ledger.

## Choose the customer mapping mode

`external_user_id` selects the external principal only. It does not select an
account or mapping.

- FlyMyAI-managed binding - omit both `resource_set_id` and `connections`;
  saved `ConnectionBinding` rows apply.
- Customer-managed named mapping - store a principal resource-set `public_id`
  and `revision` in the builder backend, then send both `resource_set_id` and
  `resource_set_revision` on every run. The backend still accepts an omitted
  revision for compatibility, but the safe public workflow never omits it.
- One-off explicit mapping - send `connections` keyed by frozen slot.

`resource_set_id` and `connections` are mutually exclusive. A named mapping
can contain only exact `integration_connection` public UUIDs owned by the
resolved principal. FlyMyAI revalidates authority, slots, status, and revision
at the snapshot boundary. The opaque mapping ID never exposes credentials or
changes the deployment owner's billing identity.

The exact one-off shape maps each frozen slot to either one connection UUID or
an array of connection UUIDs:

```json
{
  "external_user_id":"customer_42",
  "variables":{},
  "connections":{
    "support_mailbox":"11111111-1111-4111-8111-111111111111",
    "compliance_mailbox":["22222222-2222-4222-8222-222222222222"]
  }
}
```

Every UUID must be an active `integration_connection` owned by the resolved
principal. Unknown slots, duplicate UUIDs, the wrong toolkit, cross-principal
IDs, and cardinality violations fail before provider dispatch. Omitted slots
currently continue through saved bindings, so include every required frozen
slot when the canonical request must own the complete mapping. Owner
`user_mcp_tool` IDs are never valid here, and a customer principal never falls
back to the owner's authoring connection.

## Optional customer-bound MCP runtime

Use the owner MCP surface to author, test, and freeze. Use Agents REST to
publish and bootstrap connections. After that, a product backend may expose a
published deployment through a separately provisioned customer MCP process.
Current safe customer mode has one immutable deployment/customer binding per
gateway process:

```bash
FLYMYAI_API_KEY='<server-owner-key>' \
MCP_HTTP_TOKEN='<customer-edge-token>' \
FLYMYAI_MCP_MODE=customer \
FLYMYAI_MCP_DEPLOYMENT_ID="$DEPLOYMENT_ID" \
FLYMYAI_MCP_EXTERNAL_USER_ID="$AUTHENTICATED_PRODUCT_USER_ID" \
FLYMYAI_MCP_RESOURCE_SET_ID="$CUSTOMER_RESOURCE_SET_ID" \
FLYMYAI_MCP_RESOURCE_SET_REVISION="$CUSTOMER_RESOURCE_SET_REVISION" \
npm start
```

The product backend derives `external_user_id` from its authenticated session
and places it in trusted process provisioning. It is never a model-call
argument, client header, query parameter, or value copied from chat. Use the
resource-set pair for a customer-managed named mapping, omit both resource-set
variables for saved FlyMyAI bindings, or set
`FLYMYAI_MCP_CONNECTIONS_JSON` for one exact process-managed mapping.

Connect the customer-facing MCP client with
`Authorization: Bearer <customer-edge-token>`, not the owner API key. The
surface exposes only:

```text
started = run_bound_deployment({
  "variables":{},
  "operation_key":"customer-logical-run-<uuid>"
})
page = get_bound_deployment_run({"run_handle":started.run_handle})
```

Pass `next_since` while `has_more=true` and stop only when
`poll_complete=true`. The opaque handle is bound to the configured deployment,
customer, and owner credential. To serve another product user, route to a
separately trusted binding. Two bindings may use the same deployment, but they
must produce different `ExternalPrincipal` and execution records while keeping
the same agent, version, deployment, and billed owner.

## Publish a frozen agent

`AGENT_ID` and `COMPILATION_ID` must identify the one requested agent and its
one accepted instruction freeze, or the one disposable fixture agent only when
a release maintainer deliberately ran the
[connectionless platform fixture](https://docs.flymy.ai/agents/guides/release-gates.md#release-maintainer-only-connectionless-fixture). Never
freeze the same accepted execution again merely to enter this publish sequence.
`FLYMYAI_API_KEY` must already be exported by the builder's secret manager. Do
not edit the agent between the accepted freeze and version selection. If a
freeze response was lost, do not POST it again: reconcile with the bounded
compilation list filtered by the known execution ID and stop if the outcome is
not unique.

```bash
set -euo pipefail
: "${FLYMYAI_API_KEY:?Export the builder key in this server process}"
: "${AGENT_ID:?Set to the agent from projects_create}"
: "${COMPILATION_ID:?Set from the one accepted instruction freeze}"
: "${OPERATION_LABEL:?Reuse the unique audit label from agent creation}"
: "${FLYMYAI_AGENTS_API_ROOT:?Set the exact Agents API root ending in /api/v1/agents}"
A="${FLYMYAI_AGENTS_API_ROOT%/}"
auth=(-H "X-API-KEY: $FLYMYAI_API_KEY")

for attempt in $(seq 1 1350); do
  compilation=$(curl -fsS --max-time 30 "${auth[@]}" \
    "$A/compilations/$COMPILATION_ID/")
  status=$(jq -r '.status' <<<"$compilation")
  error=$(jq -r '.error // empty' <<<"$compilation")
  if test -n "$error"; then jq '{status,error}' <<<"$compilation"; exit 1; fi
  case "$status" in
    compiled|completed) break ;;
    failed) jq '{status,error}' <<<"$compilation"; exit 1 ;;
  esac
  sleep 2
done
case "$status" in compiled|completed) ;; *) exit 1 ;; esac

VERSION_ID=
for attempt in $(seq 1 1350); do
  next_url="$A/versions/?agent_task=$AGENT_ID"
  version_ids='[]'
  for page in $(seq 1 100); do
    case "$next_url" in "$A/versions/"*) ;; *) exit 1 ;; esac
    versions=$(curl -fsS --max-time 30 "${auth[@]}" "$next_url")
    page_ids=$(jq -c --argjson c "$COMPILATION_ID" \
      '[.results[]|select(.source_compilation==$c)|.public_id]' <<<"$versions")
    version_ids=$(jq -cn --argjson prior "$version_ids" \
      --argjson current "$page_ids" '$prior+$current')
    next_url=$(jq -r '.next // empty' <<<"$versions")
    if test -z "$next_url"; then break; fi
    if test "$page" = 100; then exit 1; fi
  done
  case "$(jq -r 'length' <<<"$version_ids")" in
    0) sleep 2 ;;
    1) VERSION_ID=$(jq -r '.[0]' <<<"$version_ids"); break ;;
    *) echo "Multiple versions materialized for compilation $COMPILATION_ID" >&2; exit 1 ;;
  esac
done
test -n "$VERSION_ID"

# The versions route is cursor-paginated. The loop follows at most 100
# same-origin pages and never sends the builder key to an untrusted next URL.

deployment=$(curl -fsS --max-time 30 -X POST "${auth[@]}" \
  -H 'Content-Type: application/json' \
  --data "$(jq -nc --arg a "$AGENT_ID" --arg v "$VERSION_ID" --arg label "$OPERATION_LABEL" \
    '{agent_task:$a,candidate_version:$v,name:("Production ["+$label+"]"),status:"draft",publish_mode:"embedded"}')" \
  "$A/deployments/")
DEPLOYMENT_ID=$(jq -er '.public_id' <<<"$deployment")

access=$(curl -fsS --max-time 30 "${auth[@]}" \
  "$A/deployments/$DEPLOYMENT_ID/access/")
jq '[.requirements[]|{slot,connection_required,hosted_setup_supported}]' <<<"$access"
jq -e 'all(.requirements[];(.connection_required|not) or .hosted_setup_supported)' \
  <<<"$access" >/dev/null
curl -fsS --max-time 30 -X POST "${auth[@]}" \
  -H 'Content-Type: application/json' --data '{"publish_mode":"embedded"}' \
  "$A/deployments/$DEPLOYMENT_ID/preflight/" | jq -e '.ready==true' >/dev/null
curl -fsS --max-time 30 -X POST "${auth[@]}" \
  -H 'Content-Type: application/json' --data '{"publish_mode":"embedded"}' \
  "$A/deployments/$DEPLOYMENT_ID/publish/" | jq '{public_id,status,active_version}'
```

The stable deployment ID remains your endpoint when a newer immutable version is published. A version pins instruction, schemas, internal LLM, effort, tool manifest, and requirements.

Upgrade and rollback that same deployment - never create a deployment per
release. PATCH its `candidate_version`, run preflight, then publish. To roll
back, stage the prior immutable version on the same ID and repeat the same two
checks:

```bash
curl -fsS --max-time 30 -X PATCH "${auth[@]}" \
  -H 'Content-Type: application/json' \
  --data "$(jq -nc --arg v "$NEXT_VERSION_ID" '{candidate_version:$v}')" \
  "$A/deployments/$DEPLOYMENT_ID/"
curl -fsS --max-time 30 -X POST "${auth[@]}" \
  -H 'Content-Type: application/json' --data '{"publish_mode":"embedded"}' \
  "$A/deployments/$DEPLOYMENT_ID/preflight/" | jq -e '.ready==true' >/dev/null
curl -fsS --max-time 30 -X POST "${auth[@]}" \
  -H 'Content-Type: application/json' --data '{"publish_mode":"embedded"}' \
  "$A/deployments/$DEPLOYMENT_ID/publish/" >/dev/null
```

Preflight currently accepts only supported catalog adapters. It rejects arbitrary custom MCP servers, mutable skills, unsupported adapters, and raw media-model tools inside an embedded agent. Do not bypass a failed preflight. Call raw Models API separately from your backend.

## Connect one user's service account

For each `connection_required` slot, use the exact slot returned by `access`:

The deployment `access` GET is read-only. It can return requirements and
existing customer state, but it never creates an `ExternalPrincipal`. For a
new external user, the `connect-session` POST below is the first mutating
bootstrap: it resolves or creates the principal and then creates the hosted
authorization session.

```bash
: "${EXTERNAL_USER_ID:?Derive from the authenticated product user}"
: "${SLOT:?Use a connection_required slot from access}"
session=$(curl -fsS --max-time 30 -X POST "${auth[@]}" \
  -H 'Content-Type: application/json' \
  --data "$(jq -nc --arg u "$EXTERNAL_USER_ID" --arg s "$SLOT" \
    '{external_user_id:$u,slot:$s}')" \
  "$A/deployments/$DEPLOYMENT_ID/connect-session/")
jq '{redirect_url,expires_at}' <<<"$session"
```

Redirect that authenticated user to `redirect_url`. It expires after 15 minutes and is single-use. The user authorizes the third-party service, not FlyMyAI. There is no reseller success webhook today. Poll `access` with backoff until each required slot has the required cardinality of active, unexpired connections, not merely a binding row:

Treat `connect-session` as a single-dispatch write. Persist its canonical
deployment, customer, slot, and audit label before calling. It has no caller
idempotency key. After a timeout or lost response, do not immediately create a
second session; reconcile through `access` and the known 15-minute window, and
surface an unknown outcome if uniqueness cannot be proven.

```bash
curl -fsS --max-time 30 -G "${auth[@]}" \
  --data-urlencode "external_user_id=$EXTERNAL_USER_ID" \
  "$A/deployments/$DEPLOYMENT_ID/access/" \
  | jq '{requirements,connections:[.connections[]|{public_id,principal,toolkit_slug,alias,status,expires_at}],bindings}'
```

The run call is authoritative. If readiness changed, preserve and handle its HTTP 400 `connections` error instead of assuming a stale binding is usable.
Keep the full `access` response on the authenticated builder backend. Send only
the hosted `redirect_url` to the customer, not owner policy, connection, or
binding metadata.

### Optional customer-managed named mapping

After the exact hosted connections are active, resolve the principal and create
one principal-scoped resource set. Use exact active connection `public_id`
values from that customer's `access` response:

```bash
: "${CUSTOMER_CONNECTION_ID:?Exact active connection public_id from access}"
: "${CUSTOMER_RESOURCE_SET_CREATE_KEY:?Persist one key for this exact customer mapping create}"
principals=$(curl -fsS --max-time 30 -G "${auth[@]}" \
  --data-urlencode "deployment=$DEPLOYMENT_ID" \
  --data-urlencode "external_user_id=$EXTERNAL_USER_ID" \
  "$A/external-principals/")
PRINCIPAL_ID=$(jq -er '
  (.results // .) as $rows |
  if ($rows|length)==1 then $rows[0].public_id
  else error("expected exactly one external principal") end
' <<<"$principals")

mapping=$(curl -fsS --max-time 30 -X POST "${auth[@]}" \
  -H "Idempotency-Key: $CUSTOMER_RESOURCE_SET_CREATE_KEY" \
  -H 'Content-Type: application/json' \
  --data "$(jq -nc --arg p "$PRINCIPAL_ID" '{
    name:"Primary customer mapping",
    management_mode:"customer",
    principal_id:$p
  }')" \
  "$A/mcp-resource-sets/")
CUSTOMER_RESOURCE_SET_ID=$(jq -er '.public_id' <<<"$mapping")
CUSTOMER_RESOURCE_SET_REVISION=$(jq -er '.revision' <<<"$mapping")

mapping=$(curl -fsS --max-time 30 -X POST "${auth[@]}" \
  -H 'Content-Type: application/json' \
  --data "$(jq -nc \
    --arg connection "$CUSTOMER_CONNECTION_ID" \
    --arg slot "$SLOT" \
    --argjson revision "$CUSTOMER_RESOURCE_SET_REVISION" '{
      expected_revision:$revision,
      members:[{
        resource_type:"integration_connection",
        resource_id:$connection,
        slot:$slot,
        allowed_actions:[],
        position:0
      }]
    }')" \
  "$A/mcp-resource-sets/$CUSTOMER_RESOURCE_SET_ID/replace-members/")
CUSTOMER_RESOURCE_SET_REVISION=$(jq -er '.revision' <<<"$mapping")
```

For several slots or accounts, send the complete desired member array in one
replacement. A set can reference only connections owned by that exact
principal. Persist the returned mapping ID and revision in the builder backend.

## Run and meter one user

This released HTTP contract keeps the key server-side and uses the slim progress
route. Store the canonical variables object alongside the idempotency key;
`AGENT_VARIABLES_JSON={}` is valid only when the frozen input schema has no
required fields:

```python
import json, os, time, uuid
import httpx

base = os.environ["FLYMYAI_AGENTS_API_ROOT"].rstrip("/")
if not base.endswith("/api/v1/agents"):
    raise ValueError("FLYMYAI_AGENTS_API_ROOT must end in /api/v1/agents")
deployment = os.environ["FLYMYAI_DEPLOYMENT_ID"]
user_id = os.environ["PRODUCT_USER_ID"]
idem = os.environ["PERSISTED_DEPLOYMENT_RUN_KEY"]
variables = json.loads(os.environ.get("AGENT_VARIABLES_JSON", "{}"))
if not isinstance(variables, dict):
    raise ValueError("AGENT_VARIABLES_JSON must contain a JSON object")
request_body = {"external_user_id": user_id, "variables": variables}
mapping_id = os.environ.get("CUSTOMER_MCP_RESOURCE_SET_ID")
mapping_revision = os.environ.get("CUSTOMER_MCP_RESOURCE_SET_REVISION")
connections_json = os.environ.get("CUSTOMER_CONNECTIONS_JSON")
if mapping_id and connections_json:
    raise ValueError("Choose resource_set_id or connections, not both")
if mapping_revision and not mapping_id:
    raise ValueError("A resource-set revision requires its mapping id")
if mapping_id:
    if not mapping_revision:
        raise ValueError("The public named-mapping workflow requires its revision")
    request_body["resource_set_id"] = mapping_id
    request_body["resource_set_revision"] = int(mapping_revision)
    if request_body["resource_set_revision"] < 1:
        raise ValueError("The mapping revision must be positive")
elif connections_json:
    connections = json.loads(connections_json)
    if not isinstance(connections, dict):
        raise ValueError("CUSTOMER_CONNECTIONS_JSON must contain a JSON object")
    if len(connections) > 100:
        raise ValueError("CUSTOMER_CONNECTIONS_JSON exceeds 100 slots")
    for slot, selected in connections.items():
        if not isinstance(slot, str) or not slot:
            raise ValueError("Every connection mapping key must be a frozen slot")
        ids = [selected] if isinstance(selected, str) else selected
        if not isinstance(ids, list) or not ids or len(ids) > 25:
            raise ValueError(f"Slot {slot} must select 1-25 connection UUIDs")
        if any(not isinstance(value, str) for value in ids):
            raise ValueError(f"Slot {slot} connection IDs must be strings")
        for value in ids:
            uuid.UUID(value)
    request_body["connections"] = connections


with httpx.Client(headers={"X-API-KEY": os.environ["FLYMYAI_API_KEY"]},
                  timeout=httpx.Timeout(30.0, connect=10.0)) as client:
    response = client.post(f"{base}/deployments/{deployment}/run/",
        headers={"Idempotency-Key": idem},
        json=request_body)
    response.raise_for_status()
    execution = response.json()["id"]
    retry = client.post(f"{base}/deployments/{deployment}/run/",
        headers={"Idempotency-Key": idem},
        json=request_body)
    retry.raise_for_status()
    if retry.json()["id"] != execution:
        raise RuntimeError("Idempotency replay created another execution")
    since = None
    for _ in range(150):
        poll = client.get(f"{base}/executions/{execution}/status/",
            params={"since": since} if since else None)
        poll.raise_for_status()
        state = poll.json()
        since = state.get("last_step_id") or since
        if state["is_settled"]:
            if state["status"] != "completed":
                raise RuntimeError(state.get("error") or state["status"])
            result = state["result"]
            break
        time.sleep(2)
    else:
        raise TimeoutError(execution)
    price = client.get(f"{base}/executions/{execution}/prices/")
    price.raise_for_status()
    print({"execution_id": execution, "result": result,
           "total_price": price.json()["total_price"]})
```

The price response has `id`, `tool_calls`, `llm_usage`, decimal-string `total_price` and `billing_settled`; each row has its `price` and `settled`. Bill your customer from a run whose `billing_settled` is true. It has no external user field, so join it through your ledger. Do not use unpaginated `/executions/prices/` for request-time rollups.

## SDK namespaces

This candidate guide is aligned to `flymyai` 1.2.0rc12
(`pip install 'flymyai>=1.2.0rc12'`). That candidate exposes `client.versions`,
`client.deployments`, `client.mcp_resource_sets`, and `client.agent_groups` in
both sync and async clients. Capability-detect the
installed SDK before using those namespaces. An older installed package may
require the equivalent REST routes; never invent a namespace that is absent.
