From f805c97be09691ccd0e041d22e66c8c922210e38 Mon Sep 17 00:00:00 2001 From: JanHranicky Date: Tue, 11 Aug 2026 09:48:48 +0200 Subject: [PATCH 1/4] feat: initial docs --- sources/platform/integrations/ai/hermes.md | 143 ++++++++++++++++++ sources/platform/integrations/ai/index.mdx | 8 + .../integrations/hermes-agent-white.svg | 1 + .../platform/integrations/hermes-agent.svg | 1 + 4 files changed, 153 insertions(+) create mode 100644 sources/platform/integrations/ai/hermes.md create mode 100644 static/img/platform/integrations/hermes-agent-white.svg create mode 100644 static/img/platform/integrations/hermes-agent.svg diff --git a/sources/platform/integrations/ai/hermes.md b/sources/platform/integrations/ai/hermes.md new file mode 100644 index 0000000000..53626bc68c --- /dev/null +++ b/sources/platform/integrations/ai/hermes.md @@ -0,0 +1,143 @@ +--- +title: Hermes Agent integration +sidebar_label: Hermes Agent +description: Learn how to integrate Apify with Hermes Agent to give your AI agent access to web scraping, data extraction, and automation using pre-built Actors. +slug: /integrations/hermes-agent +toc_min_heading_level: 2 +--- + +import ThirdPartyDisclaimer from '@site/sources/_partials/_third-party-integration.mdx'; + +[Hermes Agent](https://hermes-agent.nousresearch.com) is an open-source autonomous AI agent CLI from Nous Research. The Apify plugin for Hermes Agent gives your agent access to thousands of pre-built Actors for web scraping, data extraction, and automation through three tools: `apify_discover`, `apify_start`, and `apify_collect`. + +For more details about Hermes Agent, refer to the [official documentation](https://hermes-agent.nousresearch.com/docs). + + + +## Prerequisites + +Before integrating Apify with Hermes Agent, you'll need: + +- _An Apify account_ - If you don't have one, [sign up here](https://console.apify.com/sign-up). +- _Apify API token_ - Get your token from the **API & Integrations** section in [Apify Console](https://console.apify.com/settings/integrations). +- _Hermes Agent_ - Install the CLI from the [official documentation](https://hermes-agent.nousresearch.com/docs). +- _Python 3.11+_ - Required to install the plugin. + +## Set up the Apify plugin + +### Install the plugin + +Install the plugin from PyPI: + +```bash +pip install apify-hermes-agent-plugin +``` + +:::note Enable the plugin manually + +`hermes plugins enable apify` doesn't recognize pip-installed plugins yet - this is a known Hermes Agent CLI issue, since it only scans bundled and user plugin directories, not Python entry points. Until that's fixed upstream, enable the plugin directly in `~/.hermes/config.yaml`: + +```yaml +plugins: + enabled: + - apify +``` + +::: + +### Configure your API token + +Run the setup command to save your Apify API token: + +```bash +hermes apify-setup +``` + +This prompts for your `APIFY_API_TOKEN`, saves it to `~/.hermes/.env`, and enables the `apify` toolset for the CLI. You can find your token in the **API & Integrations** section of [Apify Console](https://console.apify.com/settings/integrations). + +To skip the interactive prompt, pass the token directly: + +```bash +hermes apify-setup --token apify_api_... +``` + +If the toolset isn't enabled automatically, run `hermes tools` and enable `apify` manually. + +## Apify tool overview + +The plugin registers three tools under the `apify` toolset: + +| Tool | Purpose | +| ---- | ------- | +| `apify_discover` | Search the Apify Store by keyword, or fetch an Actor's input schema and README by `actor_id` | +| `apify_start` | Start up to 10 Actor runs in a single call and get run references back immediately | +| `apify_collect` | Poll run statuses using the references from `apify_start` and retrieve completed dataset results | + +### Fire-and-forget batch pattern + +The tools follow an asynchronous workflow built around batching. Your agent starts up to 10 Actor runs in one `apify_start` call and gets run references immediately, then polls `apify_collect` with those references until every run finishes. Re-call `apify_collect` with the same references until the response's `all_done` field is `true`. + +```text +apify_discover (search) -> apify_discover (schema) -> apify_start (batch) -> apify_collect (poll) +``` + +### Actor ID format + +Actor IDs accept either the unique ID or the `username~actor-name` format (for example, `apify~google-search-scraper`). `apify_discover` returns Actor IDs in this format when it fetches an Actor's schema or searches the Store. + +## What you can do + +Once the plugin is set up, your Hermes agent can: + +- _Search for scrapers_ - Ask the agent to find an Actor for any platform (for example, "find me an Instagram scraper") and it discovers the right one from [Apify Store](https://apify.com/store). +- _Inspect input requirements_ - Fetch an Actor's input schema and README with `apify_discover` before starting a run, so the agent knows exactly what input to provide. +- _Scrape any website_ - The agent can extract data from Google Search, Instagram, TikTok, YouTube, Google Maps, e-commerce sites, and more. +- _Batch multiple targets_ - Start up to 10 Actor runs in a single `apify_start` call and collect all results together with `apify_collect`. + +:::note Actor runs may take some time + +Actor execution time varies depending on the task complexity. `apify_collect` reports runs as `pending` until they reach a terminal status. Check Actor run status in [Apify Console](https://console.apify.com/) if a run takes longer than expected. + +::: + +:::note Dataset results are untrusted content + +`apify_collect` wraps returned dataset items between `<<>>` markers, since scraped data comes from external websites and Actors, not from you or Hermes Agent. Results are also capped at 50,000 characters per run - if `may_have_more` is `true` in the response, re-call `apify_collect` with a higher `limit`. + +::: + +## Configuration + +| Setting | Description | +| ------- | ----------- | +| `APIFY_API_TOKEN` | Your Apify API token, saved to `~/.hermes/.env` by `hermes apify-setup`. Required for every `apify` tool call. | + +## Troubleshooting + +### Authentication errors + +- _Check your API token_ - Verify `APIFY_API_TOKEN` is set in `~/.hermes/.env`. Re-run `hermes apify-setup` to update it. +- _Get a new token_ - Find or generate one in the **API & Integrations** section of [Apify Console](https://console.apify.com/settings/integrations). + +### Plugin or tool not available + +- _Check plugin enablement_ - Ensure `apify` is listed under `plugins.enabled` in `~/.hermes/config.yaml`. Pip-installed plugins aren't auto-detected by `hermes plugins enable apify` yet. +- _Check toolset enablement_ - Run `hermes tools` and confirm `apify` is enabled for the CLI. `hermes apify-setup` enables it automatically in most cases. + +### Actor run failures + +- _Check run logs_ - If an Actor run fails, check the logs in [Apify Console](https://console.apify.com/) for details. +- _Verify input schema_ - Use `apify_discover` with `actor_id` to check what input parameters the Actor expects before calling `apify_start`. +- _Check batch size_ - `apify_start` accepts a maximum of 10 runs per call. + +### Report an issue + +If you encounter a bug or have a feature request, [open an issue](https://github.com/apify/apify-hermes-agent-plugin/issues) on the plugin's GitHub repository. + +## Resources + +- [Hermes Agent documentation](https://hermes-agent.nousresearch.com/docs) - Official Hermes Agent docs +- [Apify Actors documentation](https://docs.apify.com/actors) - Learn about Apify Actors +- [Apify Store](https://apify.com/store) - Browse pre-built Actors +- [Apify API reference](https://docs.apify.com/api/v2) - Full API documentation +- [Apify Hermes Agent plugin on GitHub](https://github.com/apify/apify-hermes-agent-plugin) - Source code and issue tracker diff --git a/sources/platform/integrations/ai/index.mdx b/sources/platform/integrations/ai/index.mdx index a48316cd05..ce0e770c8b 100644 --- a/sources/platform/integrations/ai/index.mdx +++ b/sources/platform/integrations/ai/index.mdx @@ -81,6 +81,14 @@ Plug Apify Actors into the AI stack - chat clients like Claude and ChatGPT via t imageUrl="/img/platform/integrations/openclaw.svg" smallImage /> + NousResearch \ No newline at end of file diff --git a/static/img/platform/integrations/hermes-agent.svg b/static/img/platform/integrations/hermes-agent.svg new file mode 100644 index 0000000000..3eb7e6b7a1 --- /dev/null +++ b/static/img/platform/integrations/hermes-agent.svg @@ -0,0 +1 @@ +NousResearch \ No newline at end of file From 2b3fc158c0e9e656e34c615dbd85f151d203121d Mon Sep 17 00:00:00 2001 From: JanHranicky Date: Tue, 11 Aug 2026 10:10:16 +0200 Subject: [PATCH 2/4] fix: phrasing, wording --- sources/platform/integrations/ai/hermes.md | 28 +++++++++++----------- sources/platform/integrations/ai/index.mdx | 2 +- 2 files changed, 15 insertions(+), 15 deletions(-) diff --git a/sources/platform/integrations/ai/hermes.md b/sources/platform/integrations/ai/hermes.md index 53626bc68c..b68eced651 100644 --- a/sources/platform/integrations/ai/hermes.md +++ b/sources/platform/integrations/ai/hermes.md @@ -1,14 +1,14 @@ --- title: Hermes Agent integration sidebar_label: Hermes Agent -description: Learn how to integrate Apify with Hermes Agent to give your AI agent access to web scraping, data extraction, and automation using pre-built Actors. +description: Learn how to integrate Apify with Hermes Agent to give your AI agent access to thousands of pre-built AI tools, called Actors, for scraping and automation. slug: /integrations/hermes-agent toc_min_heading_level: 2 --- -import ThirdPartyDisclaimer from '@site/sources/_partials/_third-party-integration.mdx'; +import ThirdPartyDisclaimer from '@site/sources/\_partials/\_third-party-integration.mdx'; -[Hermes Agent](https://hermes-agent.nousresearch.com) is an open-source autonomous AI agent CLI from Nous Research. The Apify plugin for Hermes Agent gives your agent access to thousands of pre-built Actors for web scraping, data extraction, and automation through three tools: `apify_discover`, `apify_start`, and `apify_collect`. +[Hermes Agent](https://hermes-agent.nousresearch.com) is an open-source autonomous AI agent from [Nous Research](https://nousresearch.com/). The Apify plugin for Hermes Agent gives your agent access to thousands of pre-built AI tools, called Actors. The plugin comes with three tools: `apify_discover`, `apify_start`, and `apify_collect`, which your agent can use autonomously. For more details about Hermes Agent, refer to the [official documentation](https://hermes-agent.nousresearch.com/docs). @@ -39,8 +39,8 @@ pip install apify-hermes-agent-plugin ```yaml plugins: - enabled: - - apify + enabled: + - apify ``` ::: @@ -67,11 +67,11 @@ If the toolset isn't enabled automatically, run `hermes tools` and enable `apify The plugin registers three tools under the `apify` toolset: -| Tool | Purpose | -| ---- | ------- | -| `apify_discover` | Search the Apify Store by keyword, or fetch an Actor's input schema and README by `actor_id` | -| `apify_start` | Start up to 10 Actor runs in a single call and get run references back immediately | -| `apify_collect` | Poll run statuses using the references from `apify_start` and retrieve completed dataset results | +| Tool | Purpose | +| ---------------- | ------------------------------------------------------------------------------------------------ | +| `apify_discover` | Search Apify Store by keyword, or fetch an Actor's input schema and README by `actor_id` | +| `apify_start` | Start up to 10 Actor runs in a single call and get run references back immediately | +| `apify_collect` | Poll run statuses using the references from `apify_start` and retrieve completed dataset results | ### Fire-and-forget batch pattern @@ -89,9 +89,9 @@ Actor IDs accept either the unique ID or the `username~actor-name` format (for e Once the plugin is set up, your Hermes agent can: -- _Search for scrapers_ - Ask the agent to find an Actor for any platform (for example, "find me an Instagram scraper") and it discovers the right one from [Apify Store](https://apify.com/store). +- _Search for Actors_ - Ask the agent to find an Actor to add to its AI tools. Actors can be scrapers, lead generation tools, or any other kind of tool - for example, try asking it to `find me an Actor to scrape Instagram` and it discovers the right one from [Apify Store](https://apify.com/store). - _Inspect input requirements_ - Fetch an Actor's input schema and README with `apify_discover` before starting a run, so the agent knows exactly what input to provide. -- _Scrape any website_ - The agent can extract data from Google Search, Instagram, TikTok, YouTube, Google Maps, e-commerce sites, and more. +- _Extract data from any website_ - Scrapers are just one category of Actor. The agent can extract data from Google Search, Instagram, TikTok, YouTube, Google Maps, e-commerce sites, and more. - _Batch multiple targets_ - Start up to 10 Actor runs in a single `apify_start` call and collect all results together with `apify_collect`. :::note Actor runs may take some time @@ -108,8 +108,8 @@ Actor execution time varies depending on the task complexity. `apify_collect` re ## Configuration -| Setting | Description | -| ------- | ----------- | +| Setting | Description | +| ----------------- | -------------------------------------------------------------------------------------------------------------- | | `APIFY_API_TOKEN` | Your Apify API token, saved to `~/.hermes/.env` by `hermes apify-setup`. Required for every `apify` tool call. | ## Troubleshooting diff --git a/sources/platform/integrations/ai/index.mdx b/sources/platform/integrations/ai/index.mdx index ce0e770c8b..24887b6687 100644 --- a/sources/platform/integrations/ai/index.mdx +++ b/sources/platform/integrations/ai/index.mdx @@ -83,7 +83,7 @@ Plug Apify Actors into the AI stack - chat clients like Claude and ChatGPT via t /> Date: Tue, 11 Aug 2026 10:53:46 +0200 Subject: [PATCH 3/4] fix: removed obsolete bug mention --- sources/platform/integrations/ai/hermes.md | 17 +++-------------- 1 file changed, 3 insertions(+), 14 deletions(-) diff --git a/sources/platform/integrations/ai/hermes.md b/sources/platform/integrations/ai/hermes.md index b68eced651..383a5ef074 100644 --- a/sources/platform/integrations/ai/hermes.md +++ b/sources/platform/integrations/ai/hermes.md @@ -27,24 +27,13 @@ Before integrating Apify with Hermes Agent, you'll need: ### Install the plugin -Install the plugin from PyPI: +Install the plugin from PyPI, then enable it: ```bash pip install apify-hermes-agent-plugin +hermes plugins enable apify ``` -:::note Enable the plugin manually - -`hermes plugins enable apify` doesn't recognize pip-installed plugins yet - this is a known Hermes Agent CLI issue, since it only scans bundled and user plugin directories, not Python entry points. Until that's fixed upstream, enable the plugin directly in `~/.hermes/config.yaml`: - -```yaml -plugins: - enabled: - - apify -``` - -::: - ### Configure your API token Run the setup command to save your Apify API token: @@ -121,7 +110,7 @@ Actor execution time varies depending on the task complexity. `apify_collect` re ### Plugin or tool not available -- _Check plugin enablement_ - Ensure `apify` is listed under `plugins.enabled` in `~/.hermes/config.yaml`. Pip-installed plugins aren't auto-detected by `hermes plugins enable apify` yet. +- _Check plugin enablement_ - Run `hermes plugins enable apify` to confirm the plugin is enabled. - _Check toolset enablement_ - Run `hermes tools` and confirm `apify` is enabled for the CLI. `hermes apify-setup` enables it automatically in most cases. ### Actor run failures From ca84536f00d8429bf64f93d9aad38716bd75af98 Mon Sep 17 00:00:00 2001 From: JanHranicky Date: Wed, 12 Aug 2026 14:21:16 +0200 Subject: [PATCH 4/4] fix: added hermes-agent <18.0 troubleshooting section --- sources/platform/integrations/ai/hermes.md | 11 +++++++++-- 1 file changed, 9 insertions(+), 2 deletions(-) diff --git a/sources/platform/integrations/ai/hermes.md b/sources/platform/integrations/ai/hermes.md index 383a5ef074..7b8db2ca08 100644 --- a/sources/platform/integrations/ai/hermes.md +++ b/sources/platform/integrations/ai/hermes.md @@ -76,7 +76,7 @@ Actor IDs accept either the unique ID or the `username~actor-name` format (for e ## What you can do -Once the plugin is set up, your Hermes agent can: +Once the plugin is set up, your Hermes Agent can: - _Search for Actors_ - Ask the agent to find an Actor to add to its AI tools. Actors can be scrapers, lead generation tools, or any other kind of tool - for example, try asking it to `find me an Actor to scrape Instagram` and it discovers the right one from [Apify Store](https://apify.com/store). - _Inspect input requirements_ - Fetch an Actor's input schema and README with `apify_discover` before starting a run, so the agent knows exactly what input to provide. @@ -110,7 +110,14 @@ Actor execution time varies depending on the task complexity. `apify_collect` re ### Plugin or tool not available -- _Check plugin enablement_ - Run `hermes plugins enable apify` to confirm the plugin is enabled. +- _Check plugin enablement_ - Run `hermes plugins enable apify` to confirm the plugin is enabled. If that fails with `Plugin 'apify' is not installed or bundled.`, your Hermes Agent predates `0.18.1`, when entry-point plugin discovery was fixed upstream - update with `pip install --upgrade hermes-agent`. If you can't upgrade, add `apify` under `plugins.enabled` in `~/.hermes/config.yaml` manually instead: + + ```yaml + plugins: + enabled: + - apify + ``` + - _Check toolset enablement_ - Run `hermes tools` and confirm `apify` is enabled for the CLI. `hermes apify-setup` enables it automatically in most cases. ### Actor run failures