---
title: Hermes Agent integration
url: https://docs.apify.com/integrations/hermes-agent.md
parents:
  - [Apify documentation](https://docs.apify.com/llms.txt)
  - [Integrations](https://docs.apify.com/integrations.md)
  - [AI](https://docs.apify.com/integrations/ai.md)
previous: [Haystack](https://docs.apify.com/integrations/haystack.md)
next: [LangChain](https://docs.apify.com/integrations/langchain.md)
---

> ## Documentation index
> Fetch the complete documentation index at: https://docs.apify.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Hermes Agent integration

[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).

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](https://github.com/apify/apify-docs/issues).

## 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* - Version 0.18.1 or later. Install the CLI from the [official documentation](https://hermes-agent.nousresearch.com/docs).
* *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:


```bash
pip install apify-hermes-agent-plugin

hermes plugins enable 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 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 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.
* *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](https://console.apify.com/) 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

| 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* - 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:


  ```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

* *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