diff --git a/sources/academy/tutorials/apify_actors/adding_rapidapi_project.md b/sources/academy/tutorials/apify_actors/adding_rapidapi_project.md index 41bda37656..4a2f70b839 100644 --- a/sources/academy/tutorials/apify_actors/adding_rapidapi_project.md +++ b/sources/academy/tutorials/apify_actors/adding_rapidapi_project.md @@ -114,7 +114,7 @@ Actors can run in two modes: as batch processing jobs that execute a single task ::: -Once you’ve saved the settings, go to the **Standby** tab, and click the **Test endpoint** button. It will start the Actor, and you can test it. Once the Actor is running, you're done with the migration! +Once you’ve saved the settings, go to the **Endpoints** tab, and click the **Test endpoint** button. It will start the Actor, and you can test it. Once the Actor is running, you're done with the migration! ## Next steps diff --git a/sources/platform/actors/development/actor_definition/actor_json.md b/sources/platform/actors/development/actor_definition/actor_json.md index 17ce38afeb..5656258b68 100644 --- a/sources/platform/actors/development/actor_definition/actor_json.md +++ b/sources/platform/actors/development/actor_definition/actor_json.md @@ -93,5 +93,5 @@ Actor `name`, `version`, `buildTag`, and `environmentVariables` are currently on | `minMemoryMbytes` | Optional | Specifies the minimum amount of memory in megabytes required by the Actor to run. Requires an _integer_ value. If both `minMemoryMbytes` and `maxMemoryMbytes` are set, then `minMemoryMbytes` must be equal or lower than `maxMemoryMbytes`. Refer to the [Usage and resources](https://docs.apify.com/actors/running/usage-and-resources#memory) for more details about memory allocation. | | `maxMemoryMbytes` | Optional | Specifies the maximum amount of memory in megabytes required by the Actor to run. It can be used to control the costs of run. Requires an _integer_ value. Refer to the [Usage and resources](https://docs.apify.com/actors/running/usage-and-resources#memory) for more details about memory allocation. | | `usesStandbyMode` | Optional | Boolean specifying whether the Actor will have [Standby mode](../programming_interface/actor_standby.md) enabled. | -| `webServerSchema` | Optional | The `webServerSchema` property defines an OpenAPI v3 schema for the web server running in the Actor. Set the property to an embedded OpenAPI schema object or a path to a JSON schema file. Define the schema when your Actor starts its own HTTP server and you want to describe its interface. | +| `webServerSchema` | Optional | The `webServerSchema` property defines an OpenAPI v3 schema for the web server running in the Actor. Set the property to an embedded OpenAPI schema object or a path to a JSON schema file. Define the schema when your Actor starts its own HTTP server and you want to describe its interface. See [Actor web server schema](./web_server_schema/index.md). | | `webServerMcpPath` | Optional | The HTTP endpoint path where the Actor exposes its MCP (Model Context Protocol) server functionality. When set, the Actor is recognized as an MCP server. For example, setting `"/mcp"` designates the `/mcp` endpoint as the MCP interface. This path becomes part of the Actor's stable URL when [Standby mode](../programming_interface/actor_standby.md) is enabled. | diff --git a/sources/platform/actors/development/actor_definition/index.md b/sources/platform/actors/development/actor_definition/index.md index 01b0d1b46b..00cfca8fb9 100644 --- a/sources/platform/actors/development/actor_definition/index.md +++ b/sources/platform/actors/development/actor_definition/index.md @@ -15,6 +15,7 @@ Actors have the following elements: - **[Dockerfile](./docker.md)** which specifies where is the Actor's source code, how to build it, and run it. - **Documentation** in the form of a **README.md** file. - **[Input](./input_schema/index.md)** and **[output](./output_schema/index.md)** schemas that describe what input the Actor requires and what output it produces. +- **[Web server schema](./web_server_schema/index.md)** that describes the HTTP endpoints of the Actor's web server, if it runs one. - Access to an out-of-box **[storage](../../../storage/index.md)** system for Actor data, results, and files. The documentation and the input and output schemas make it possible for people to easily understand what the Actor does, enter the required inputs both in the user interface or API, and integrate the Actor's results with their other workflows. Actors can easily call and interact with each other, enabling building more complex systems on top of simple ones. diff --git a/sources/platform/actors/development/actor_definition/web_server_schema/index.md b/sources/platform/actors/development/actor_definition/web_server_schema/index.md index 1e52330e26..d5f1a0f839 100644 --- a/sources/platform/actors/development/actor_definition/web_server_schema/index.md +++ b/sources/platform/actors/development/actor_definition/web_server_schema/index.md @@ -2,13 +2,13 @@ title: Actor web server schema sidebar_label: Web server schema sidebar_position: 7 -description: Attach an OpenAPI specification to your Actor to enable the interactive Standby tab in Apify Console and Apify Store, where you can browse and test endpoints. +description: Attach an OpenAPI specification to your Actor to enable the interactive Endpoints tab in Apify Console and Apify Store, where you can browse and test endpoints. slug: /actors/development/actor-definition/web-server-schema --- -The `webServerSchema` field in `.actor/actor.json` attaches an [OpenAPI 3.x](https://spec.openapis.org/oas/v3.0.3) specification to your Actor. You can define the schema for any Actor that exposes an HTTP server. When you enable [standby mode](/actors/development/programming-interface/standby), Apify Console and Apify Store render an interactive **Standby** tab on the Actor's detail page. From there you can browse endpoints, inspect request and response schemas, and send requests directly from the browser. +The `webServerSchema` field in `.actor/actor.json` attaches an [OpenAPI 3.x](https://spec.openapis.org/oas/v3.0.3) specification to your Actor. You can define the schema for any Actor that exposes an HTTP server. When you enable [standby mode](/actors/development/programming-interface/standby), Apify Console and Apify Store render an interactive **Endpoints** tab on the Actor's detail page. From there you can browse endpoints, inspect request and response schemas, and send requests directly from the browser. -![Apify Console showing the Standby tab with the Endpoints section rendered from the Actor's OpenAPI spec](../images/console-standby-openapi-swagger.png) +![Apify Console showing the Endpoints tab rendered from the Actor's OpenAPI spec](../images/console-standby-openapi-swagger.png) ## Define the web server schema @@ -92,7 +92,7 @@ Follow the standard [OpenAPI 3.x format](https://spec.openapis.org/oas/latest.ht The build process validates `webServerSchema`, similar to other Actor schemas like [input schema](/actors/development/actor-definition/input-schema) and [dataset schema](/storage/dataset-schema). If the spec is malformed, the build fails with a validation error. -Once deployed, the **Standby** tab appears automatically on the Actor's detail page when you enable [standby mode](/actors/development/programming-interface/standby). It renders your spec with [Swagger UI](https://swagger.io/tools/swagger-ui/) and handles authentication automatically - Actor users can send requests without configuring API tokens. +Once deployed, the **Endpoints** tab appears automatically on the Actor's detail page when you enable [standby mode](/actors/development/programming-interface/standby). It renders your spec with [Swagger UI](https://swagger.io/tools/swagger-ui/) and handles authentication automatically - Actor users can send requests without configuring API tokens. :::note Servers field is overwritten @@ -104,5 +104,5 @@ Your `servers` array is replaced with the Actor's standby URL at display time. C | Field | Description | | --- | --- | -| `usesStandbyMode` | Must be `true` for the **Standby** tab to appear. See [standby mode](/actors/development/programming-interface/standby). | -| `webServerSchema` | The OpenAPI spec that powers the **Standby** tab. Defined in [`.actor/actor.json`](/actors/development/actor-definition/actor-json) as an inline object or a path to a JSON file. | +| `usesStandbyMode` | Must be `true` for the **Endpoints** tab to appear. See [standby mode](/actors/development/programming-interface/standby). | +| `webServerSchema` | The OpenAPI spec that powers the **Endpoints** tab. Defined in [`.actor/actor.json`](/actors/development/actor-definition/actor-json) as an inline object or a path to a JSON file. | diff --git a/sources/platform/actors/development/programming_interface/actor_standby.md b/sources/platform/actors/development/programming_interface/actor_standby.md index efa099fc16..595d8b675f 100644 --- a/sources/platform/actors/development/programming_interface/actor_standby.md +++ b/sources/platform/actors/development/programming_interface/actor_standby.md @@ -66,8 +66,7 @@ async def main() -> None: -Please make sure to describe your Actors, their endpoints, and the schema for their -inputs and outputs in your README. +Describe your Actor's endpoints, their parameters, and responses with a [web server schema](../actor_definition/web_server_schema/index.md) defined in the [`.actor/actor.json`](../actor_definition/actor_json.md) file. Apify Console then renders an interactive **Endpoints** tab on the Actor's detail page, where users can browse the endpoints and send requests directly from the browser. Describe the endpoints in your Actor's README as well. ### Readiness probe @@ -170,14 +169,38 @@ async def main() -> None: +## Run lifecycle in Standby mode + +The platform starts and stops Standby runs automatically based on the incoming request load. It stops a run that receives no requests within the configured idle timeout and starts a new run when requests arrive again. Don't keep data only in the run's memory: persist anything you need to a [dataset or key-value store](../../../storage/index.md). See [how Standby scaling works](../../running/actor_standby.md#is-there-any-scaling-to-accommodate-the-incoming-requests) and [how to customize the Standby configuration](../../running/actor_standby.md#how-do-i-customize-standby-configuration). + +Apart from the [readiness probe](#readiness-probe), the platform doesn't check your server's health while the run is alive. A run ends when its process exits, when it migrates to another machine, or when it stays idle for longer than the idle timeout. A server that stays up but stops responding keeps receiving requests, so on an unrecoverable error, exit the process instead of swallowing the error. + ## Timeouts When you send a request to an Actor in Standby mode, the total timeout for receiving the first response is _5 minutes_. Before the platform forwards the request to a specific Actor run, it performs a _run selection_ process to determine the specific Actor run that will handle it. This process has internal timeout of _2 minutes_. -## Getting the URL of the Standby Actor +## Get the URL of the Standby Actor The URL is exposed as an environment variable `ACTOR_STANDBY_URL`. You can also use `Actor.config`, where the `standbyUrl` option is available. +The URL typically combines the Actor owner's username and the Actor name, for example: + +```text +https://jane-doe--my-actor.apify.actor +``` + +The Actor also responds on a URL built from its ID, which keeps working if the Actor or its owner is renamed: + +```text +https://92c4oi4fpzy7rprlf.apify.actor +``` + +Unlike the [container web server](./container_web_server.md) URL, which changes with every run, the Standby URL stays the same for all runs of the Actor. You can share it publicly or hardcode it in applications that call the Actor: copy it from the **Endpoints** tab on the Actor's detail page rather than building it from the username and Actor name, because some Actors use a different hostname format. + +If the Actor exposes an MCP server, its endpoint is the Standby URL followed by the path defined in the [`webServerMcpPath`](../actor_definition/actor_json.md) property. + +Requests to the Standby URL require an Apify API token. See [how to authenticate your requests](../../running/actor_standby.md#how-do-i-authenticate-my-requests). + ## Monetization of Actors in Standby mode You can monetize Standby Actors just like any other Actor. diff --git a/sources/platform/actors/development/programming_interface/container_web_server.md b/sources/platform/actors/development/programming_interface/container_web_server.md index f9f12ec560..e33fc7244a 100644 --- a/sources/platform/actors/development/programming_interface/container_web_server.md +++ b/sources/platform/actors/development/programming_interface/container_web_server.md @@ -37,6 +37,8 @@ The web server inside the container must listen on the port specified by the `AC Check out [Custom environment variables](./environment_variables.md) for more details. +You can describe the web server's API with a [web server schema](../actor_definition/web_server_schema/index.md) in the Actor definition. + ## Example: Start a simple web server diff --git a/sources/platform/actors/development/programming_interface/environment_variables.md b/sources/platform/actors/development/programming_interface/environment_variables.md index 00713b39a8..05f3c1ad33 100644 --- a/sources/platform/actors/development/programming_interface/environment_variables.md +++ b/sources/platform/actors/development/programming_interface/environment_variables.md @@ -52,9 +52,9 @@ Variables prefixed with `ACTOR_` are defined by the [Actor specification](https: | `ACTOR_BUILD_NUMBER` | Build number of the Actor build used in the run. | | `ACTOR_BUILD_TAGS` | A comma-separated list of tags of the Actor build used in the run. Note that this environment variable is assigned at the time of start of the Actor and doesn't change over time, even if the assigned build tags change. | | `ACTOR_TASK_ID` | ID of the Actor task. Empty if Actor is run outside of any task, e.g. directly using the API. | -| `ACTOR_WEB_SERVER_URL` | Unique public URL for accessing the Actor run web server from the outside world. | +| `ACTOR_WEB_SERVER_URL` | Unique public URL for accessing the Actor run web server from the outside world. Each run gets its own URL, which stops working when the run finishes. | | `ACTOR_WEB_SERVER_PORT` | TCP port for the Actor to start an HTTP server on. This server can be used to receive external messages or expose monitoring and control interfaces. The server also receives messages from the [Actor Standby](/actors/development/programming-interface/standby) mode. | -| `ACTOR_STANDBY_URL` | URL for accessing web servers of Actor runs in the [Actor Standby](/actors/development/programming-interface/standby) mode. | +| `ACTOR_STANDBY_URL` | Public URL of the Actor in [Actor Standby](/actors/development/programming-interface/standby) mode. Unlike `ACTOR_WEB_SERVER_URL`, it stays the same for all runs of the Actor, so it's safe to hardcode in calling applications. | | `ACTOR_EVENTS_WEBSOCKET_URL` | Websocket URL where Actor may listen for [events](/actors/development/programming-interface/system-events) from Actor platform. | | `ACTOR_MCP_CONNECTOR_BASE_URL` | Base URL of the Apify MCP Proxy. Connect to an [MCP connector](/integrations/mcp-connectors) at `${ACTOR_MCP_CONNECTOR_BASE_URL}/` using `APIFY_TOKEN` as the bearer token. | diff --git a/sources/platform/actors/running/actor_standby.md b/sources/platform/actors/running/actor_standby.md index bd87983cb4..ae2f916202 100644 --- a/sources/platform/actors/running/actor_standby.md +++ b/sources/platform/actors/running/actor_standby.md @@ -12,14 +12,15 @@ in the background, waiting for the incoming HTTP requests. In a sense, the Actor ## How do I know if Standby mode is enabled -You will know that the Actor is enabled for Standby mode if you see the **Standby** tab on the Actor's detail page. +You will know that the Actor is enabled for Standby mode if you see the **Endpoints** tab on the Actor's detail page. In the tab, you will find the hostname of the server, the description of the Actor's endpoints, the parameters they accept, and what they return in the Actor README. +If the Actor defines a [web server schema](../development/actor_definition/web_server_schema/index.md), the tab also shows an interactive list of its endpoints, where you can send requests directly from the browser. To use the Actor in Standby mode, you don't need to click a start button or not need to do anything else. Simply use the provided hostname and endpoint in your application, hit the API endpoint and get results. -![Standby tab](./images/actor_standby/standby-tab.png) +![Endpoints tab](./images/actor_standby/standby-tab.png) ## How do I pass input to Actors in Standby mode @@ -63,6 +64,12 @@ it well. Please head to the Actor README to learn more about the capabilities of When you use the Actor in Standby mode, the system automatically scales the Actor to accommodate the incoming requests. Under the hood, the system starts new Actor runs, which you will see in the Actor runs tab, with the origin set to Standby. +## Does the platform check that Standby runs are healthy + +The platform checks a run's readiness once, before the run starts serving requests, and performs no health checks after that. A run ends when its process exits, when it migrates to another machine, or when it stays idle for longer than the idle timeout. + +If an Actor's server stays up but stops responding, the platform doesn't detect the failure, and requests keep going to that run. To learn how to handle this in your own Actors, see [Develop Actors in Standby mode](../development/programming_interface/actor_standby.md#run-lifecycle-in-standby-mode). + ## What is the timeout for incoming requests For requests sent to an Actor in Standby mode, the maximum time allowed until receiving the first response is _5 minutes_. This represents the overall timeout for the operation. @@ -81,9 +88,9 @@ The Standby configuration currently consists of the following properties: - **Idle timeout (seconds)** - If a Standby Actor run doesn’t receive any HTTP requests within this time, the system will terminate the run. When a new request arrives, the system might need to start a new Standby Actor run to handle it, which can take a few seconds. A higher idle timeout improves responsiveness but increases costs, as the Actor remains active for a longer period. - **Build** - The Actor build that the runs of the Standby Actor will use. Can be either a build tag (e.g. `latest.`), or a build number (e.g. `0.1.2`). -You can see these in the Standby tab of the Actor detail page. However, note that these properties are not configurable at the Actor level. If you wish to +You can see these in the **Endpoints** tab of the Actor detail page. However, note that these properties are not configurable at the Actor level. If you wish to use the Actor-level hostname, this will always use the default configuration. To override this configuration, just create a new Task from the Actor. -You can then head to the Standby tab of the created Task and modify the configuration as needed. Note that the task has a specific hostname, so make +You can then head to the **Endpoints** tab of the created Task and modify the configuration as needed. Note that the task has a specific hostname, so make sure to use that in your application if you wish to use the custom configuration. ## Are the Standby runs billed differently