DEV Community: Ivan Solovyev

Two Actors, one agent, and the three ways my chain broke

Ivan Solovyev — Wed, 02 Sep 2026 17:09:31 +0000

A client asked a question that sounds simple: which sellers on the marketplaces are risky to buy from? Answering it takes two steps. Find the sellers behind the product listings, then check each seller's legal entity against public risk registries.

I had an Actor for each half already. One walks marketplace search results and returns sellers with their tax ID, legal name and store URL. The other takes tax IDs and returns a risk score built from bankruptcy filings, tax arrears, the procurement blacklist and the financial monitoring list. Both had been in the Store for months, both had paying users.

The first Actor, doing its half of the job. Each of these runs produces the input for the second one.

Handing the chain to an agent broke it three times, and none of the breaks looked like a failure. The runs stayed green. The dataset filled up. The answer was wrong in a way that only showed up when I checked a company by hand.

The agent reached both Actors through the Apify MCP server, which exposes them as tools over the Model Context Protocol. Nothing below depends on which client you use: the failures come from how the two Actors hand data to each other, and a human doing the same handoff by hand would have hit two of the three.

Why this is two Actors and not one

The scraper needs a browser, residential proxies and a container image heavy enough to carry them. The risk check needs plain HTTP requests to four public sources and nothing else. Merged into one Actor, every risk lookup would drag a browser image behind it.

They also run on different clocks. Seller lists get refreshed when a client enters a new category. Risk data gets rechecked weekly for the same sellers, because bankruptcy filings appear on their own schedule. Splitting them means the expensive half runs once and the cheap half runs as often as the client wants.

That split is the right call for the platform and the wrong shape for a naive agent, which will treat the two as one tool and wire them together the first way that looks plausible.

Break one: the handoff by reference

The obvious wiring is to pass the first run's dataset id to the second Actor. My builder Actors accept sourceDatasetId for exactly that. It works on a laptop, where your personal token reads everything you own.

On the platform, an Actor running with standard permissions cannot read the default dataset of a different run. The API answers Insufficient permissions. I confirmed this on a cloud run on 25 July after losing most of a day to it locally, where the Python SDK happily used my personal token and hid the whole problem.

The fix is to pass values, and the part specific to chaining is this: your input schema decides which wiring the agent tries first. If sourceDatasetId sits at the top of the schema with a confident description, that is the path the agent picks. I moved items to the top, described it as the primary input, and demoted the dataset id to a fallback with an explicit note about permissions.

{
  "items": {
    "title": "Companies to check",
    "type": "array",
    "description": "Records with an inn field, passed by value. Use this when chaining from another Actor: a run cannot read another run's dataset with standard permissions.",
    "editor": "json"
  },
  "sourceDatasetId": {
    "title": "Source dataset (same-account only)",
    "type": "string",
    "description": "Read companies from a dataset your token owns. Fails with Insufficient permissions across runs."
  }
}

Schema order is documentation for a reader who stops reading after the first field that works.

Break two: the first Actor's output is the second one's input, and mine did not fit

The second Actor has no idea where its tax IDs come from. That indifference is what makes it reusable, and what makes the handoff fragile.

The seller scraper returns a tax ID for most sellers, not all. On Wildberries the ID lives in a separate dossier request that I make only when fetchDossier is on, and some storefronts have no legal entity attached at all. My run log said it plainly:

with_inn = sum(1 for s in sellers if s.get("inn"))
Actor.log.info(f"sellers: {len(sellers)} (with tax ID: {with_inn}, by platform: {scraped_counts})")

The agent never sees the log. It saw a list of sellers, mapped it to the risk checker's input, and passed the whole thing. Records without a tax ID went in as empty strings. The risk Actor did what it should: no company found, no risk data, one record out per record in.

The result read as "these eleven sellers came back clean." They had never been checked.

Two changes fixed it. First, the seller Actor now marks each record with what a downstream step can do with it:

seller["checkable"] = bool(seller.get("inn"))
seller["checkableReason"] = None if seller.get("inn") else "no legal entity published by the marketplace"

Second, the risk Actor refuses to invent an answer for input it cannot use:

inn = (raw.get("inn") or "").strip()
if not inn:
    await Actor.push_data({
        "input": raw.get("name") or raw.get("sellerId"),
        "lookupStatus": "skipped_no_inn",
        "riskScore": None,          # not zero: absence of a check, not absence of risk
    })
    continue

riskScore: None is the important part. A zero score means four sources answered and found nothing. None with a status means nobody looked. An agent summarising fifty sellers will average those numbers, and a zero in that average is a claim I never made.

Break three: a schema rejection ate the results of a paid run

This one is my favourite, because everything about it was working as designed.

My risk Actor labels each risk factor with its source. The dataset schema declared the allowed values as an enum, which is good practice: it keeps the output honest and gives the Store a clean field list. The enum listed fedresurs and nalog, the two sources I had at the time.

Then I added the procurement blacklist as a third source, labelled rnp. Company records that carried a blacklist factor now failed validation on write. push_data raised Schema validation failed, my handler logged a warning, and the run continued and finished green.

Read that again in the context of a chain. The scraper ran and charged. The risk Actor ran and charged. The most interesting companies in the batch, the ones actually on a blacklist, were the exact records that never reached the dataset. The agent received a shorter list with no indication that anything was missing, and every company on it looked fine.

The fix took one line in the schema:

{
    "riskFactors": {
        "type": "array",
        "items": {
            "type": "object",
            "properties": {
                "source": {
                    "type": "string",
                    "enum": ["fedresurs", "nalog", "rnp", "rosfinmonitoring"]
                }
            }
        }
    }
}

I shipped it as build 0.1.16, then verified against three tax IDs on the platform rather than locally: run b1J1ULvJJuVL7beZd came back with all three non-empty, including 7536176707 with 23 blacklist records and a risk score of 90. When I later added the financial monitoring list I extended the enum in the same commit as the parser, before any run could produce the new value.

Two habits came out of this:

Treat a write failure as a run failure. A warning in the log is invisible to the caller, and in a chain the caller is a machine that already paid for the data.
Extend output enums in the same commit that produces the new value. There is no version of this where the parser lands first and the schema catches up later.

try:
    await Actor.push_data(out_items)
except Exception as exc:
    # the full text matters: the platform names the field that failed validation,
    # and without it a chain silently loses its most interesting records
    Actor.log.warning(f"push_data failed ({type(exc).__name__}): {str(exc)[:220]}")
    raise

What the agent can actually hold

A category sweep returns a few hundred sellers. The full risk record for one company runs to dozens of fields: bankruptcy cases, arrears by year, directors, encumbrances, appeals. Multiply that out and no agent can keep the result in context, so it starts summarising, and the summary is where accuracy goes to die.

I added a compact mode that returns one row per company with the decision fields only:

Field	Meaning
`inn`	tax ID that was checked
`riskScore`	0-100, or `null` when no check happened
`riskLevel`	low, medium, high
`topFactors`	up to three factor codes that drove the score
`lookupStatus`	ok, not_found, source_unreachable, skipped_no_inn

Full dossiers stay in the dataset for a human to open. The agent gets five fields per company, which fits, and it can request the full record for the handful that matter. My prefill company, tax ID 7707083893, comes back as riskScore: 35, riskLevel: medium, which is one line instead of six screens.

Paying twice for the same answer

Chained runs invite repetition. An agent that gets a partial result retries the step, and a retry of step two is a second charge for companies that were already checked in the first attempt. My billing is one event per company, so a fifty-seller batch retried once costs a hundred events for fifty answers.

The cheap defence is to make repetition visible before it happens. The risk Actor now drops duplicate tax IDs inside a single input, reports how many it dropped, and refuses to charge for a company it already answered in the same run:

seen, deduped = set(), []
for raw in items:
    key = (raw.get("inn") or "").strip()
    if key and key in seen:
        continue
    seen.add(key)
    deduped.append(raw)

if len(deduped) < len(items):
    Actor.log.info(f"duplicate inputs dropped: {len(items) - len(deduped)}")

Across runs the responsibility shifts to the caller, and the caller is an agent with no memory of yesterday. What helps there is making the record self-dating: every row carries checkedAt, so an agent that keeps its own store can decide whether a seven-day-old risk score needs refreshing before it spends money on one.

What I would do differently from the start

I built both Actors for a person clicking Start in the console, then adapted them for a chain. Building for the chain first would have changed four decisions:

Every record states whether the next step can use it, and why not when it cannot.
Absence of a check and absence of a finding are different values, never both 0 or both [].
A failed write ends the run instead of shortening the dataset.
There is a compact output shape, because the second consumer of your data has a context limit and the first one had a monitor.

The chain works now. An agent runs the seller sweep, passes the checkable records by value, gets five fields back per company, and asks for full dossiers only where the score crosses a threshold. What made it work was not new scraping code. It was making both Actors honest about what they did not do.

The last mile of a scraper is a human copying a spreadsheet

Ivan Solovyev — Wed, 02 Sep 2026 17:07:05 +0000

I scrape product cards from online stores for a content bank with an Actor of my own. The Actor finishes, the dataset fills up, and then a person exports it, checks it, and pastes it into the tool where the work actually happens. That last step has no technology in it. It is somebody's Tuesday.

When Apify shipped MCP connectors, I wanted to delete that step. A connector lets an Actor call a third-party service over the Model Context Protocol using credentials the user authorized once, on the platform. The Actor never holds the token. It talks to an Apify proxy with its own run token, and the platform injects the real credentials server-side.

I built a small Actor to try it: take product cards, write them into whatever service the user connected. The full code is at github.com/isolovyev77/apify-card-sink. It works now. Getting there took six failed runs, and every one of them failed differently.

Versions matter in this article more than usual, because one of the failures is purely a version mismatch. Mine: apify==3.4.1, mcp>=1.2.0, httpx==0.28.1, on the apify/actor-python:3.12 base image. The platform reported the run as SDK 3.4.1, client 2.5.1, Crawlee 1.9.0.

What the Actor does

One job: take cards by value, connect to the service the user picked, find a tool that can write, write the rows, and report what happened.

The design decision worth explaining is that the Actor does not know its destination. It does not have a Notion branch and a Supabase branch. It asks the connected service which tools it exposes, picks one that can write, reads the argument schema that service published, and shapes the call to match. Connect it to a Notion workspace and it creates pages. Connect it to a database and it inserts rows.

Declaring the connector

A connector is an input field with resourceType: "mcpConnector", which the Actor-side guide documents in full. The mcpServers list does two jobs at once: it filters which of the user's connectors show up in the picker, and it caps what the Actor may call at runtime. The proxy holds you to the declaration, so a tool you did not declare is not just discouraged, it is unreachable.

{
    "outputConnector": {
        "title": "Destination",
        "type": "string",
        "description": "Where to write the cards. Pick a connector you have authorized: a Notion workspace, a Supabase project, a Slack channel. Your credentials stay on the Apify side and never reach this Actor.",
        "resourceType": "mcpConnector",
        "editor": "resourcePicker",
        "mcpServers": [
            { "url": "*", "tools": { "required": ["insert*"] } },
            { "url": "*", "tools": { "required": ["create_*"] } },
            { "url": "*", "tools": { "required": ["post_*"] } }
        ]
    }
}

In Apify Console the field renders as a picker, and the connector the user chose is what the
run receives:

The mcpConnector field as the user sees it. No token, no endpoint, just a choice.

That declaration is where my first real mistake lives, and I will come back to it.

Six runs, six different failures

Nine runs in one night. The two red ones are where the MCP client crashed before reaching Notion.

Run one lasted three seconds and produced nothing. Exit code 0, empty dataset, no error anywhere. I had written async def main() and never called it. The module imported cleanly, defined a function, and exited. On a platform that reports success by exit code, forgetting asyncio.run(main()) looks exactly like an Actor with nothing to do.

Run two also produced an empty dataset, this time correctly: no connector was selected, so the Actor logged a warning and returned. The behaviour was right and the reporting was wrong. I had just written an article arguing that a caller sees the dataset and never the log, and here I was, putting the one fact the caller needed into the log. Now every refusal is a row:

async def refuse(status, detail):
    Actor.log.warning(detail)
    await Actor.push_data({"delivered": 0, "status": status, "detail": detail})

if not connector_id:
    return await refuse("no_connector", "no connector selected: nowhere to write")

Run three crashed inside the MCP client, before a single byte reached Notion:

ValueError: not enough values to unpack (expected 3, got 2)
  File "/usr/src/app/src/main.py", line 102, in main
    http_client=http_client) as (read, write, _):

The Python example in the Apify documentation unpacks three streams from streamable_http_client. The version of the MCP SDK that installed in my image yields two. Both are correct for their own version; a fixed unpack is what breaks. Index the result instead:

async with streamable_http_client(f"{proxy_url}/{connector_id}",
                                  http_client=http_client) as streams:
    read, write = streams[0], streams[1]
    async with ClientSession(read, write) as session:
        await session.initialize()

Run four connected, and the tool matcher came up empty. My write hints were written for the names I imagined: create_page, insert, append. Notion exposes notion-create-pages. Different word, different separator. The naive repair is to match on create, which then also matches notion-create-attachment and notion-create-file-upload, and product cards do not belong in either. You can see the full set the connector exposes in Console:

Twenty-seven tools, every name hyphenated. This screen is also where you limit what an Actor may call.

The list is explicit now:

WRITE_HINTS = ("create-pages", "create_pages", "create-page", "create_page",
               "insert", "add_row", "append", "execute_sql",
               "send_message", "post_message")

That is also why the mcpServers declaration above is wrong in a way you will not notice until a connector fails to appear in the picker. Patterns like create_* never match notion-create-pages. While I was learning what services actually name their tools, I widened the declaration to [{"url": "*"}] and let the code do the filtering. Narrow it back once you know the names you need.

Run five wrote nothing because I could not see the argument shape. My dry run reported the tool it would use and a null where the schema should be. getattr(tool, "inputSchema", None) returned an object that did not survive the JSON dump. The SDK hands back pydantic models, and the field is input_schema in a dump, not inputSchema:

def describe(tool):
    """Argument shape of a tool, in a form that survives a JSON dump."""
    for attr in ("model_dump", "dict"):
        fn = getattr(tool, attr, None)
        if callable(fn):
            try:
                return fn(mode="json") if attr == "model_dump" else fn()
            except TypeError:
                return fn()
    return {"name": getattr(tool, "name", None), "note": "shape unavailable"}

With that fixed, the dry run returned all 27 tools the Notion connector exposes and the full schema of the one it picked. That output is the single most useful thing this Actor produces, which is why dryRun is a first-class input rather than a debug flag.

There is no universal write call

Reading that schema killed my original design. I had assumed a write is a write: hand the tool a table name and a list of rows. Notion wants pages, each with a title property and a Markdown body. A database wants rows. A chat wants a channel and a text blob.

So the Actor stopped guessing from the tool name and started reading the published schema:

def build_arguments(tool, payload):
    """Shape the call for the tool we picked."""
    props = schema_of(tool)
    if "pages" in props:
        pages = [{"properties": {"title": c.get("title") or "Untitled product card"},
                  "content": as_markdown(c)} for c in payload["rows"]]
        return {"pages": pages}, "notion-style pages"
    for key in ("rows", "records", "values"):
        if key in props:
            return {key: payload["rows"], "table": payload["table"]}, "table rows"
    if "text" in props or "message" in props:
        body = "\n\n".join("%s - %s" % (c.get("title"), c.get("url"))
                           for c in payload["rows"])
        return {"text": body, "channel": payload["table"]}, "chat message"
    return payload, "unrecognised argument shape, sending our own"

The last branch matters as much as the first three. When the shape is unfamiliar, the Actor says so in the dataset instead of sending a hopeful payload into somebody's workspace.

One detail from Notion's schema saved me a whole feature: the parent is optional. Without it, created pages land as private workspace-level pages. I had been about to build a parent-search step, and the service documentation had already answered it.

Run six wrote for real. One card in, one page out:

{
  "delivered": 1,
  "status": "ok",
  "tool": "notion-create-pages",
  "argumentShape": "notion-style pages",
  "response": "{\"pages\":[{\"id\":\"3b3b52ac-9795-818b-b31c-fcc9852969ce\",\"properties\":{\"title\":\"Lenovo IdeaPad Slim 3 15ABR8\"}}]}"
}

The whole exchange in five log lines: connect, list tools, pick one, call it, get a page id back.

The dataset carries what happened, including which argument shape was used.

The page appeared in the workspace with the product title as its heading and the card body in Markdown underneath.

The end of the last mile: a card that arrived without anyone exporting anything. Total time from the Actor starting to the page existing: under ten seconds, and my Actor never saw a Notion token.

The connector I could not use

I started with Supabase, because I already run one. Apify accepted the server URL, then told me the server does not support dynamic client registration and recommended registering my own OAuth application. Notion, by contrast, has managed OAuth: pick it from the dropdown, authorize, done.

This is worth checking before you design around a service. Apify provides managed OAuth for Notion and Supabase; for GitHub, Slack, Google and others you bring your own OAuth client. Supabase also accepts a personal access token through the API key method, which is the shortcut if you need that one specifically.

What the security model actually buys you

Three layers decide what a connector-enabled Actor can do, and they compose: the scopes granted at authorization, the tool allowlist the user sets on the connector in Console, and the Actor's own mcpServers declaration. The proxy filters tools/list down to what the Actor declared and rejects calls outside it.

For a published Actor this is the difference between "give me your API key" and "pick a connector". My Actor never sees a Notion token. A user who wants to be stricter can allow only page creation on their connector, and the Actor cannot get around it. Access dies with the run.

Deploying it, and a wall I hit on the way

I deploy Actors by pushing source files through the Apify API. That stopped working here: bodies over roughly 20 KB left my machine intact and never came back with a response. Rather than fight it, I switched the Actor to build from Git.

sourceType: GIT_REPO
gitRepoUrl: https://github.com/isolovyev77/apify-card-sink#main

The tiny request body sidestepped the problem entirely, and the article got a public repository as a side effect. If you are debugging an Actor through repeated deploys, this is the better default anyway: the build log tells you which commit it built.

What I would tell someone starting this today

Ship dryRun before you ship the write path. List the tools, dump the schema, write nothing. Everything else in this article was discovered by that one code path.
Declare {"url": "*"} while you learn the names, then narrow. A pattern that does not match leaves the user staring at an empty picker with nothing to click.
Read the tool's published schema instead of matching on its name. Names vary by service and separator; schemas do not lie.
Put every refusal in the dataset. The caller sees rows, not logs, and this is doubly true when the caller is an agent.
Check the authentication method for your service before you design around it. Managed OAuth and "register your own OAuth app" are half an hour apart.

The last mile is closed now. Cards land where the work happens, and nobody exports a spreadsheet on Tuesday.

My Actors worked fine until an AI agent called them

Ivan Solovyev — Wed, 02 Sep 2026 13:12:18 +0000

On 27 July I published a scraper that pulls product cards and specifications from online stores. It was my fourteenth Actor. The others cover company due diligence by tax ID, government tender feeds, cadastral records, marketplace seller leads. All of them had months of green runs behind them.

Then I connected the Apify MCP server to Claude. It exposes Actors as tools an AI client can call over the Model Context Protocol. I gave it a task in plain language: find this product across those stores and return the specs.

The agent picked my Actor, filled the input, started the run. Status: succeeded. Zero results, no error.

The Origin column says MCP: that run was started by an agent, not by me clicking Start.

The scraper worked. The agent had read my input schema the way any careful reader would. The trouble is that I wrote that schema for a reader who already had the target website open in another tab, and that reader was me, six months earlier.

This is what I changed across fourteen Actors to make them callable by something that cannot ask me a question. Two of those changes were about input fields. The ones that cost me money were about billing, and about the gap between "nothing exists" and "I could not look."

The code below is Python, using the Apify SDK for Python version 3.4.1, and every snippet is lifted from an Actor that runs in production today.

Why an agent breaks things a human never would

A human who gets an empty dataset has options. They open the store page, reread the README, try another value, send me an email. The whole recovery loop takes five minutes and never reaches me.

An agent has one shot inside a longer plan. It reads your schema, picks values, fires the run, reads the output, and branches. If your Actor answers six different situations with the same empty array, the agent treats all six as one fact and keeps executing with confidence. The wrong branch is now running, and nothing looks broken anywhere.

So the question stopped being "is my schema documented" and became: can a caller who has never seen the target site tell my outcomes apart?

My input fields described the website, not the task

The clearest case came from my software registry Actor. It queries a national software registry, which groups products into classes: 06.09 is a class, 06 is the group above it. Those codes are printed on the site and appear in every document a user would quote.

The registry's listing endpoint ignores them. It filters by an internal option id, an opaque integer that lives only inside their markup. You learn it by loading the listing page and mapping labels to ids. My first version exposed that integer, because that is what the request needed.

No caller can produce that value. An agent asked about class 06.09 passes 06.09, gets a clean run and an empty dataset. An agent that guesses an integer gets a full dataset for the wrong class, which costs more, because nobody checks a result that looks right.

I moved the translation inside the Actor:

{
  "softwareClasses": {
    "title": "Software classes",
    "type": "array",
    "editor": "stringList",
    "description": "Class codes as printed on the registry site: 06.09 for one class, 06 for the whole group. The Actor resolves them to the registry's internal filter ids.",
    "prefill": ["06.09"]
  }
}

The input as a caller sees it. Every sentence here is the only instruction an agent will ever get.

The rule I now apply to every input field: if a value can only be obtained by inspecting the target site, keep it out of the schema. Resolve it in code. When you cannot, make it an enum with readable titles, so the caller picks from a closed list instead of inventing. The input schema specification supports both, and the choice between them is the whole difference between a caller that guesses and one that picks.

That rule caught a second field the same week. My product Actor takes a platforms list, which used to be free-form strings matching my internal module names. Agents passed Ozon, ozon.ru, OZON. My code wanted ozon. It is an enum now, and unknown values get reported in the output instead of dropped.

Empty and failed looked identical, and that cost a client money

The registry sits behind a certificate chain from a national CA that no default trust store carries. Requests die with CERTIFICATE_VERIFY_FAILED. When I first hit that, I caught the exception, logged a warning, and returned an empty result for the company.

Empty result. The same thing the Actor returns when a company is genuinely absent from the registry.

For one company at a time, a human reads the warning line and moves on. My client ran two hundred tax IDs through an agent. About half the "not in the registry" answers were "the source did not answer," and both arrived as []. Those answers flowed into a decision about which suppliers to work with.

Every record now carries the reason it looks the way it does:

record = {
    "inn": inn,
    "foundInRegistry": None,          # True, False, or None when we could not check
    "lookupStatus": "source_unreachable",   # ok | not_found | source_unreachable
    "lookupDetail": "registry TLS chain rejected",
}

Three states instead of two. foundInRegistry: false claims something about the world. null with a status claims something about my attempt. The agent can act on the first and retry the second.

Here is the mapping I now keep for the product scraper, which has four ways to end up with fewer rows than expected:

What happened	What the record says	What the agent should do
Store returned a challenge page	`status: blocked`, `specCount: 0`	retry later or route to another store
Search matched nothing	`status: not_found`	drop the query, do not retry
Page loaded, no specifications	`status: partial`, `title` present	usable for links, not for a card
Store search by name unsupported	`status: unsupported_mode`	switch to direct URLs

Before this table existed, all four rows were an empty array and a warning in the log the caller never sees.

Dataset ids do not cross run boundaries

My product pipeline is two Actors by design. The scraper needs a browser, proxies and a heavy image. The card builder needs one HTTP request for a category reference and no browser at all. Splitting them means the expensive half runs once and the cheap half re-runs every time a client changes the card format.

I wired them the obvious way: the builder takes a sourceDatasetId and reads the scraper's output. On my machine it worked on the first try.

On the platform it fails. An Actor with standard permissions cannot read the default dataset of a different run, and the API answers Insufficient permissions. I confirmed it on a cloud run on 25 July, after losing a day locally, because local development uses your personal token and hides the whole problem.

Agents chain tools by default. Claude called the scraper, took the dataset id out of the run result, passed it to the builder, and got a permissions error it had no way to fix. The builder now takes values, and the dataset path is the fallback:

items = inp.get("items") or []
from_dataset = inp.get("sourceDatasetId")

if from_dataset and not items:
    # Works when the caller owns the dataset and supplies a token that can read it.
    # A cross-run read with the Actor's own permissions returns
    # "Insufficient permissions", so agent workflows should pass items.
    page = await Actor.apify_client.dataset(from_dataset).list_items()
    items = page.items

if not items:
    Actor.log.warning("No input records: pass items, or a dataset this run can read.")
    return

If you build a family of Actors meant to compose, make values the interface and references the optimisation. The agent holds that data in its context anyway.

Billing is part of the interface

My scraper charges per event: one price for a card assembled from free methods, another when a paid fallback channel was required, plus a surcharge for building the publish-ready structure. The run decides which events fire based on what the store made it do.

Two things went wrong, and both belong to callers who never read a pricing page.

Three events, three prices. Which ones fire is decided by the run, so an agent cannot predict the bill from the schema alone.

The surcharge shipped as a default. The flag that builds the ready-to-publish card started as true, because that output demos well. An agent calling the Actor for specifications paid for a formatting step it never used and never mentioned. I flipped buildCards to false and put the price consequence in the field description. Anything that costs extra should be opt-in, priced in the text the caller actually reads.

The check that catches this takes a minute. Run the Actor in the cloud, pull chargedEventCounts off the run object, compare it against the events you expected. Not the local run. The billed one.

I charged in the wrong order, and I had a reason that sounded good. I wanted every dataset row to state what it had been billed as, so a client could reconcile an invoice line by line, and I did not want to charge for a card that failed to save. So the run pushed the row, then charged, then set billedAs.

Datasets are append-only. After push_data returns, that row is frozen. Assigning billedAs afterwards changed an object in my process and nothing else. Clients received billedAs: null while the invoice showed charges, which killed the one feature the field existed for.

# Charge BEFORE the write. The reverse order avoided billing for a card that never
# landed, but a dataset row cannot be edited after the fact: billedAs assigned
# afterwards changes only the in-memory object, and the client receives an empty
# field while the invoice shows a charge.
for card_obj, item in to_charge:
    item["billedAs"] = await charge_for_card(card_obj, item["paidMethods"], emit_cards)

await Actor.push_data(out_items)

The general form has nothing to do with billing: compute anything the caller needs to see before the immutable write.

While I was in that function I stopped charging for empty results. A page that yielded a title and no specifications is not a product card:

async def charge_for_card(card, paid_stages, build_cards):
    if not card.get("specCount"):
        return None                      # no specs, no card, no charge
    event = EVENT_PREMIUM if paid_stages else EVENT_BASIC
    try:
        await Actor.charge(event)
        if build_cards and (card.get("card") or {}).get("attributeCount"):
            await Actor.charge(EVENT_READY)
    except Exception as exc:
        # billedAs must reflect the FACT of a charge, otherwise reconciliation
        # fails in both directions
        Actor.log.warning(f"charge '{event}' failed: {type(exc).__name__}: {str(exc)[:90]}")
        return None
    return event

The platform's automated test is your first agent

Apify runs your Actor with its prefill input on a schedule and flags it as under maintenance when the run produces nothing. The flag pulls you out of Store search until it clears.

I got flagged twice, and the scraper was healthy both times.

The first prefill hit four marketplaces at once. That is a realistic user request, it takes longer than the test allows, and the test gave up. My Actor sat marked as broken while paying users ran it all day. The prefill is now the cheapest useful request I have: one store, one query, under five minutes. The impressive four-store demo moved to a saved task, where nobody holds a stopwatch.

The second time, my marketplace monitor lost one store's API host and the prefill happened to use that store. The verdict was fair. What I took from it is that your prefill decides which single failure can delist you, so it should sit on your most reliable path rather than your most interesting one. I raised the per-page retry budget, redeployed as build 0.1.46, and the run came back with 200 cards in 96 seconds.

Treat that test as a preview of every agent that will call you: no context, no patience, one attempt, and a verdict based on whether output appeared.

The checklist I run before an Actor meets an agent

Can a caller produce every input value without opening the target site? If not, resolve it in code or use an enum.
Does the output separate "no such thing" from "I could not check"? Tri-state fields plus an explicit status.
If this Actor is chained with another, does data pass by value? Cross-run dataset reads fail on standard permissions.
Is anything that costs money on by default? Turn it off, and state the price where the caller reads.
Is every field the caller needs computed before push_data?
Is the prefill my most reliable path, and does it finish fast?
Does chargedEventCounts on a real cloud run match what I believe I charge?

None of this made my scrapers better at scraping. It made them usable by a caller who cannot ask me anything, which turned out to be the same as making them usable by anyone other than me.

The Actor most of these lessons came from. Pay-per-event pricing is what turned the billing bugs from cosmetic into expensive.

The two Actors most of this came from are the product card and specs scraper, which handles the scraping and the pay-per-event side, and the counterparty due diligence Actor, where an empty array first passed for a fact.