Apify Orchestrator Actor Development

Apify orchestrator Actor development

An orchestrator Actor is a parent Apify Actor whose job is to coordinate a sequence (or parallel fan-out) of other Actors. It takes user input, calls sub-Actor A, feeds A's output into sub-Actor B, optionally runs an LLM transformation between them, and emits the combined result to its own dataset.

This skill covers TypeScript-only orchestrators built on the apify-orchestrator library. It does not cover Python, JavaScript, or Standby-mode Actors.

Important: Before writing code, fill in the generatedBy property in .actor/actor.json (e.g., "Claude Code with Claude Opus 4.7"). This helps Apify improve tooling for specific AI models.

Prerequisites and setup

Verify the apify CLI is installed:

apify --help

If not installed, use a package manager (never curl | bash):

npm install -g apify-cli
# or on Mac: brew install apify-cli

Confirm login:

apify info   # should return your username

If not logged in, run apify login (opens a browser) or export APIFY_TOKEN from https://console.apify.com/settings/integrations. Never pass tokens on the command line — arguments show up in process listings and shell history.

Interactive creation flow

When the user asks for a new orchestrator Actor, follow these steps in order:

1. Elicit sub-Actor sequence
2. Fetch each sub-Actor's schema via Apify MCP
3. Decide data flow between steps
4. Note the total cost cap (a Run option, not an input field)
5. Ask about optional LLM step
6. Scaffold the project
7. Test locally, then deploy

Step 1 — Elicit the sub-Actor sequence

Ask the user which Apify Actors to chain together, in order. Accept either:

• A list up-front (e.g., "apify/website-content-crawler then apify/rag-web-browser"), or
• One at a time (ask for the first, discuss it, then ask what comes next).

If the user names a task instead of an Actor ID ("scrape LinkedIn profiles"), use the Apify MCP search-actors tool to propose candidates and let the user pick.

Step 2 — Fetch each sub-Actor's schema via Apify MCP

For every sub-Actor in the chain, call the Apify MCP fetch-actor-details tool. The parameter is actor, not actorId. Present the input schema back to the user with the fields listed in inputSchema.required highlighted. See references/mcp-schema-discovery.md for the truncation gotcha (500-char descriptions; enum lists arrive whole), the frequently absent outputSchema, and the fallback path via the REST API / raw INPUT_SCHEMA.json on GitHub.

Never guess field names. If the MCP truncation is limiting, fetch the raw schema from the Actor's GitHub repo.

Step 3 — Decide data flow between steps

For each pair of adjacent sub-Actors, ask:

• Which fields from step N's output feed into step N+1's input?
• Which top-level orchestrator inputs should be exposed to the user (via the orchestrator's own .actor/input_schema.json)?
• Which sub-Actor inputs should be hardcoded?

Step 4 — Note the total cost cap

The total cost cap is a Run option (maxTotalChargeUsd) — the caller sets it when they start the orchestrator via the Apify Console, API, or SDK. It's not an input schema field. See the Apify API docs for how callers pass it.

At Run time the orchestrator:

1. Reads its own cap via client.run(actorRunId).get().options.maxTotalChargeUsd.
2. Divides the total evenly across the sub-Actor steps at compile time — declare a STEPS tuple and compute perStepCap = maxTotalChargeUsd / STEPS.length.
3. Passes each step's share as maxTotalChargeUsd when calling the sub-Actor (for pay-per-event Actors) or as maxItems (for pay-per-result Actors).
4. Tracks cumulative cost across sub-Actor Runs and refuses to launch the next step once the running total reaches the cap. Note that run.usageTotalUsd reads 0 on the object .call() returns and then accrues over several seconds, so the tally has to re-read each child Run rather than trust that value. The Run-level maxTotalChargeUsd is what enforces the ceiling; the tally is reporting plus a backstop for a step that ran uncapped. See references/cost-tracking.md.

Do not add a stepBudgets input schema field. The even split is a deliberate compile-time constant — it keeps the input schema clean, makes cost behavior predictable for the caller, and removes a footgun (three shares that don't sum to the total). Users control cost solely via the Run's maxTotalChargeUsd option; the orchestrator handles the split.

Tell the user to set maxTotalChargeUsd when they trigger the orchestrator — otherwise there's no ceiling and the orchestrator runs uncapped. See references/cost-tracking.md for the full pattern, including the LLM-step approximation (Standby Actors don't accept maxTotalChargeUsd, so estimate cost from token usage).