Skip to main content

Hermes Agent integration

Copy for LLM

Hermes Agent is an open-source autonomous AI agent from Nous Research. 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.

Help keep this page up to date

This integration uses a third-party service. If you find outdated content, please submit an issue on GitHub.

Prerequisites

Before integrating Apify with Hermes Agent, you'll need:

  • An Apify account - If you don't have one, sign up here.
  • Apify API token - Get your token from the API & Integrations section in Apify Console.
  • Hermes Agent - Version 0.18.1 or later. Install the CLI from the official documentation.
  • Python 3.11 to 3.13 - Required to install the plugin.

Set up the Apify plugin

Install the plugin

Install the plugin from PyPI, then enable it:

pip install apify-hermes-agent-plugin
hermes plugins enable apify

Configure your API token

Run the setup command to save your Apify API token:

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.

To skip the interactive prompt, pass the token directly:

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:

ToolPurpose
apify_discoverSearch Apify Store by keyword, or fetch an Actor's input schema and README by actor_id
apify_startStart up to 10 Actor runs in a single call and get run references back immediately
apify_collectPoll 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.

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 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.
  • 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.
  • 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.
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 if a run takes longer than expected.

Dataset results are untrusted content

apify_collect wraps returned dataset items between <<<EXTERNAL_UNTRUSTED_CONTENT>>> and <<<END_EXTERNAL_UNTRUSTED_CONTENT>>> 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, which a higher limit can't lift. If may_have_more is true in the response, re-call apify_collect with a higher limit to fetch more items.

Configuration

SettingDescription
APIFY_API_TOKENYour 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.

Plugin or tool not available

  • Check plugin enablement - Re-run hermes plugins enable apify. If it fails with Plugin 'apify' is not installed or bundled., your Hermes Agent predates version 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:

    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

  • Check run logs - If an Actor run fails, check the logs in Apify Console 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 on the plugin's GitHub repository.

Resources