/apify-orchestrator-actor-development

name: apify-orchestrator-actor-development
description: Build TypeScript Apify orchestrator Actors — coordinate a sequence of sub-Actors (optionally with an LLM step) using the apify-orchestrator library. Use when creating a new orchestrator Actor, chaining Apify Actors together, adding an OpenRouter LLM step between Actors, or scaffolding parent-Actor workflows that call other Actors.
author: Fabian Maume
author_url: https://github.com/fmaume
metadata:
  category: actor-development
  keywords: "orchestrator, sub-actor, actor-chaining, apify-orchestrator, typescript, cost-cap, maxTotalChargeUsd, openrouter, llm-step, scaffolding, input-schema, output-schema, mcp"

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`](https://github.com/apify-projects/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](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](https://docs.apify.com/api/v2/act-runs-post) 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](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](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).

Step 5 — Ask about an optional LLM step

Ask the user whether to insert an LLM transformation somewhere in the chain (common: summarize between steps, classify at the end, or format the final output). If yes, point them at [references/openrouter.