> For the complete documentation index, see [llms.txt](https://developers.oxylabs.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://developers.oxylabs.io/integrations/ai-studio-integrations/hermes-agent.md).

# Hermes Agent

[**Hermes Agent**](https://github.com/NousResearch/hermes-agent) is a pluggable agent framework that integrates web search and extraction through swappable backends. The `hermes-web-oxylabs` plugin registers [**Oxylabs AI Studio**](https://aistudio.oxylabs.io/) as one of available backends, calling AI Studio's REST API directly (no vendor SDK) to provide agent with:

* Ranked web search results – title, URL, description
* Clean page data as markdown, for research, comparisons, and follow-up reasoning
* Fresh web context for more accurate answers

## Requirements

* [Hermes Agent](https://github.com/NousResearch/hermes-agent) installed with `hermes` CLI
* Oxylabs AI Studio [API key](https://aistudio.oxylabs.io/api-key) (AI Studio uses a single API key, no separate username/password)

## Setup

{% stepper %}
{% step %}

### Install the plugin

Register Oxylabs as a web provider Hermes can use for search and extraction:

```bash
hermes plugins install oxylabs/hermes-web-oxylabs --enable
```

{% endstep %}

{% step %}

### Set your API key

```bash
export OXYLABS_API_KEY="your-api-key-here"
```

Or add it to Hermes `.env` file instead of your shell config:

```bash
# ~/.hermes/.env
OXYLABS_API_KEY=your-api-key-here
```

{% endstep %}

{% step %}

### Choose implementation

Set Oxylabs as the backend for **search**, **extraction**, or **both**.

#### **Web Search**

```bash
hermes config set web.search_backend oxylabs
```

For queries requesting 10 or fewer results, the plugin calls AI Studio's `/search/instant` endpoint and returns results inline. For larger result sets, it submits to `/search/run` and polls until completion.

{% hint style="info" %}
**Search** returns listings only (title, URL, description), page content is fetched separately through [extraction](#web-extraction).
{% endhint %}

#### **Web Extraction**

```bash
hermes config set web.extract_backend oxylabs
```

Each URL is submitted to AI Studio's `/scrape` endpoint and polled until completed (up to 60 seconds per URL). 

A batch of URLs is processed concurrently, failure on one URL doesn't block the batch and comes back with an `error` field instead of content.

#### Search + Extraction (full backend)

If you want Oxylabs to handle both **search** and **extraction**, set the shared `backend` key instead of the two above:

```yaml
web:
  backend: "oxylabs"
```

{% endstep %}

{% step %}

### Restart Hermes

Backend and API key changes are only read at session start. Start a new session or restart the current one:

```bash
hermes restart
```

{% endstep %}

{% step %}

### Verify

Run a task that needs current web context (e.g. a request to read a specific URL). If the response includes search results or page content, the integration is successful.

If `OXYLABS_API_KEY is not configured` error is returned, the key wasn't picked up. Return to [Step 2](#set-your-api-key), then restart again.

{% hint style="info" %}
Once Oxylabs is selected as `backend`, a missing key only returns an error instead of falling back to another provider.
{% endhint %}
{% endstep %}
{% endstepper %}

### Overriding endpoint (optional)

Hermes `web_extract` tool supports API base URL overriding through the following:

```bash
export OXYLABS_API_URL="https://your-custom-endpoint"
```

Used for testing or self-hosted setups. Default: `https://api-aistudio.oxylabs.io`.

{% hint style="info" %}
More advanced features are compatible by Oxylabs AI Studio (`format`, `render_javascript`, `geo_location`) which are currently unsupported through Hermes dispatcher and may be available at a later date.
{% endhint %}

## More resources

See our [GitHub repository](https://github.com/oxylabs/hermes-web-oxylabs) for full code references.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://developers.oxylabs.io/integrations/ai-studio-integrations/hermes-agent.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.