# tool_apify

A RocketRide tool node that exposes Apify Actors (web scrapers and automation tasks) to an AI agent.

## What it does

Gives an agent the ability to run Apify Actors and read their results. The agent can
launch any Actor by ID or name, wait for it to finish, and receive the items it produced,
or read items from an existing Apify dataset. Useful for agents that need to extract
structured web data on demand.

Uses the official **apify-client** Python SDK. The client is created once at pipeline
start from the configured API token; an empty token fails the node at startup.

Every Actor run is bounded by three configurable safety limits: item count (default
**100**), run timeout (default **120 seconds**), and spend cap (default **$1 USD**).
This prevents an agent-chosen Actor from hanging the pipeline or overspending.
Agent-supplied `limit` values are clamped to the configured maximum.

---

## Configuration


| Field | Type | Description |
|---|---|---|
| `apikey` | string | Default empty. Apify API token |
| `max_items` | integer | Default 100. Upper cap on items returned per call (agent requests are clamped to this). |
| `run_timeout_secs` | integer | Default 120. Max seconds an Actor run may take before it is stopped. |
| `max_cost_usd` | number | Default 1. Spend limit per run for pay-per-event Actors. |


Invalid or missing values for `max_items`, `run_timeout_secs`, and `max_cost_usd` fall
back to their defaults; integer limits are floored at `1`.

---

## Available tools

Tools are registered under the `apify` prefix.

### run_actor

Run an Apify Actor to completion and return the items it produced.


| Tool | Description |
|---|---|---|
| `run_actor` | Run an Apify Actor to completion and return the items it produced. |
| `get_dataset_items` | Read items from an existing Apify dataset. |


Returns `{ success, dataset_id, count, items }` -- the run's default dataset ID and its
items. If the run produces no dataset, returns `success: true` with an empty `dataset_id`
and zero items.

### get_dataset_items

Read items from an existing Apify dataset.

| Parameter    | Required | Description                                              |
|--------------|----------|----------------------------------------------------------|
| `dataset_id` | yes      | Apify dataset ID to read                                 |
| `limit`      | no       | Max items to return (default 100, capped by `max_items`) |

Returns `{ success, count, items }`.

---

## Safety limits

`run_actor` passes the configured bounds directly to the Apify run:

- **Item cap** -- the effective `limit` (agent request clamped to `max_items`) is sent as
  the run's `max_items` and also applied when reading the resulting dataset.
- **Timeout** -- `run_timeout_secs` bounds both the Actor's run time and how long the node
  waits for the run to finish.
- **Cost cap** -- `max_cost_usd` is sent as the run's `max_total_charge_usd`, limiting
  spend on pay-per-event Actors.

---

## Authentication

Set `apikey` to an Apify API token (stored as a secure field). The token is used to
construct the `ApifyClient` when the pipeline starts and is required -- configuration
validation warns, and pipeline startup fails, if it is missing.

See the [Apify documentation](https://docs.apify.com) for obtaining a token and for
per-Actor input schemas.

---

<!-- ROCKETRIDE:GENERATED:PARAMS START -->
<!-- Generated by nodes:docs-generate. Do not edit by hand. -->

## Schema

| Field | Type | Description | Default |
|---|---|---|---|
| `tool_apify.apikey` | `string` | **API Token**<br/>Apify API token | `""` |
| `tool_apify.max_cost_usd` | `number` | **Max Cost (USD)**<br/>Spend limit per run for pay-per-event Actors. | `1` |
| `tool_apify.max_items` | `integer` | **Max Items**<br/>Upper cap on items returned per call (agent requests are clamped to this). | `100` |
| `tool_apify.run_timeout_secs` | `integer` | **Run Timeout (seconds)**<br/>Max seconds an Actor run may take before it is stopped. | `120` |

## Dependencies

- `apify-client` `>=3,<4`

## Source

[<svg viewBox="0 0 16 16" width="15" height="15" fill="currentColor" aria-hidden="true" style="vertical-align:-0.15em;margin-right:0.35em"><path d="M8 0C3.58 0 0 3.58 0 8c0 3.54 2.29 6.53 5.47 7.59.4.07.55-.17.55-.38 0-.19-.01-.82-.01-1.49-2.01.37-2.53-.49-2.69-.94-.09-.23-.48-.94-.82-1.13-.28-.15-.68-.52-.01-.53.63-.01 1.08.58 1.23.82.72 1.21 1.87.87 2.33.66.07-.52.28-.87.51-1.07-1.78-.2-3.64-.89-3.64-3.95 0-.87.31-1.59.82-2.15-.08-.2-.36-1.02.08-2.12 0 0 .67-.21 2.2.82.64-.18 1.32-.27 2-.27.68 0 1.36.09 2 .27 1.53-1.04 2.2-.82 2.2-.82.44 1.1.16 1.92.08 2.12.51.56.82 1.27.82 2.15 0 3.07-1.87 3.75-3.65 3.95.29.25.54.73.54 1.48 0 1.07-.01 1.93-.01 2.2 0 .21.15.46.55.38A8.013 8.013 0 0016 8c0-4.42-3.58-8-8-8z"/></svg> View source](https://github.com/rocketride-org/rocketride-server/tree/develop/nodes/src/nodes/tool_apify)
<!-- ROCKETRIDE:GENERATED:PARAMS END -->