How to Integrate Hermes Agent with Oxylabs AI Studio

Requirements

Make sure you have the following before starting:

• Hermes Agent installed with hermes CLI

• Oxylabs AI Studio API key (AI Studio uses a single API key, no separate username/password required)

Step 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

Step 2. Set your API key

Set the API key in your current shell session:

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

Or add it directly to your Hermes environment configuration file (~/.hermes/.env):

OXYLABS_API_KEY=your-api-key-here

Step 3. Choose what Oxylabs handles

You can set Oxylabs as the backend for search, extraction, or both.

Search only

hermes config set web.search_backend oxylabs

• For queries requesting 10 or fewer results, the plugin uses AI Studio's /search/instant endpoint and returns results inline.

• For larger result sets, it submits to /search/run to poll until completion.

• web.search tool returns listings only (title, URL, description); full page content is fetched separately through the web.extract backend.

Extraction only

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

• Batches of URLs are processed concurrently. A failure on one URL does not block the rest of the batch and returns an error field instead of content.

Both, via a shared backend

To use Oxylabs for both search and extraction, set the shared backend key via CLI:

hermes config set web.backend oxylabs

Or update your ~/.hermes/config.yaml file:

web:
  backend: "oxylabs"

Step 4. Restart Hermes

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

hermes restart

Step 5. Verify it's working

Run a task that requires live web access or page extraction:

hermes run "Summarize the latest product updates from https://oxylabs.io"

• Success: The agent outputs structured search results or Markdown page content.

• Error: 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)

The Hermes web_extract tool supports API base URL overriding (default: https://api-aistudio.oxylabs.io). You can override this endpoint for testing or self-hosted setup:

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

Learn more

• Oxylabs AI Studio documentation

• Hermes Agent on GitHub

• hermes-web-oxylabs plugin

Final thoughts

Integrating Oxylabs AI Studio with Hermes Agent bridges the gap between static AI agent reasoning and real-time web intelligence. Offloading web search and page extraction to Oxylabs helps your agents gain more reliable access to structured, LLM-ready context without the challenges of managing custom scraping infrastructure or vendor SDKs.

Want to explore further? Check out our guides on the best AI agent frameworks, MCP vs A2A protocols, and our LlamaIndex and CrewAI integrations for building web-powered LLM applications in Python.

If you have questions about web scraping and integrations, email us on support@oxylabs.io or use the live chat on our homepage.

Please be aware that this is a third-party tool not owned or controlled by Oxylabs. Each third-party provider is responsible for its own software and services. Consequently, Oxylabs will have no liability or responsibility to you regarding those services. Please carefully review the third party's policies and practices and/or conduct due diligence before accessing or using third-party services.