Hermes Agent

Oxylabs AI Studio allows your Hermes Agent to pull real-time web search and clean, LLM-ready data to use live context and structured page content as part of its reasoning workflow.

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 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 installed with hermes CLI
• Oxylabs AI Studio API key (AI Studio uses a single API key, no separate username/password)

Setup

1

Install the plugin

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

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

2

Set your API key

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

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

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

3

Choose implementation

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

Web Search

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.

Search returns listings only (title, URL, description), page content is fetched separately through extraction.

Web Extraction

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:

web:
  backend: "oxylabs"

4

Restart Hermes

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

hermes restart

5

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, then restart again.

Once Oxylabs is selected as backend, a missing key only returns an error instead of falling back to another provider.

Overriding endpoint (optional)

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

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

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

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.

More resources

See our GitHub repository for full code references.