You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Agents (and human authors) commonly land on a topology where:
Primary HTTP handler is bound on /metadata (or /api, or another verb-shaped path).
Root / returns plain-text help: "Actor is ready. Use GET /metadata?url=<url>".
The Actor is reachable, but only by a human reading the help text — programmatic clients hitting / get non-JSON prose and have no machine-readable way to find the real endpoint.
Observed in an eval run (scenario 06, agent's Actor davehan/metadata-api) — deployed Actor was fully functional at /metadata?url=… but invisible to any programmatic client.
Suggested change
Add a "Endpoint discoverability" subsection to the Standby documentation calling out that a well-formed Standby Actor should adopt one of three patterns:
Bind the primary handler on / — simplest; the URL you hand out IS the URL clients hit.
Serve an OpenAPI spec at /openapi.json — clients can auto-discover the shape. Cross-reference the webServerSchema in actor.json.
Return a machine-readable {"endpoints": [...]} JSON at / — minimal escape hatch when / is reserved for something else.
Root-path prose (Actor is ready. Use GET /metadata?...) should be explicitly called out as an anti-pattern.
Related
Sibling change in apify/agent-skills — the same teaching in the public skill.
Sibling change in apify/actor-templates — teaching baked into the ts-standby template AGENTS.md.
Platform-side (apify/actor-standby-controllerOnboarding migration #340): auto-serve webServerSchema at /openapi.json on the Standby URL. That closes the platform-side loop; docs closes the human-authoring loop.
Impact
Medium. Docs are the primary teaching surface — agents that pre-train on Apify docs and human authors both benefit.
Surfaced during an evaluation of Apify surfaces for agent-driven Actor development.
Problem
The Apify Standby documentation (
platform/actors/development/programming-interface/standby) describes how to build a Standby Actor but does not call out endpoint discoverability as a first-class concern.Agents (and human authors) commonly land on a topology where:
/metadata(or/api, or another verb-shaped path)./returns plain-text help:"Actor is ready. Use GET /metadata?url=<url>".The Actor is reachable, but only by a human reading the help text — programmatic clients hitting
/get non-JSON prose and have no machine-readable way to find the real endpoint.Observed in an eval run (scenario 06, agent's Actor
davehan/metadata-api) — deployed Actor was fully functional at/metadata?url=…but invisible to any programmatic client.Suggested change
Add a "Endpoint discoverability" subsection to the Standby documentation calling out that a well-formed Standby Actor should adopt one of three patterns:
/— simplest; the URL you hand out IS the URL clients hit./openapi.json— clients can auto-discover the shape. Cross-reference thewebServerSchemainactor.json.{"endpoints": [...]}JSON at/— minimal escape hatch when/is reserved for something else.Root-path prose (
Actor is ready. Use GET /metadata?...) should be explicitly called out as an anti-pattern.Related
apify/agent-skills— the same teaching in the public skill.apify/actor-templates— teaching baked into thets-standbytemplate AGENTS.md.apify/actor-standby-controllerOnboarding migration #340): auto-servewebServerSchemaat/openapi.jsonon the Standby URL. That closes the platform-side loop; docs closes the human-authoring loop.Impact
Medium. Docs are the primary teaching surface — agents that pre-train on Apify docs and human authors both benefit.
Surfaced during an evaluation of Apify surfaces for agent-driven Actor development.