Merge branch 'main' of github.com:NousResearch/hermes-agent into bb/gui
This commit is contained in:
Brooklyn Nicholson
@@ -105,6 +105,7 @@ Hermes reads MCP config from `~/.hermes/config.yaml` under `mcp_servers`.
|
||||
| `timeout` | number | Tool call timeout |
|
||||
| `connect_timeout` | number | Initial connection timeout |
|
||||
| `enabled` | bool | If `false`, Hermes skips the server entirely |
|
||||
| `supports_parallel_tool_calls` | bool | If `true`, tools from this server may run concurrently |
|
||||
| `tools` | mapping | Per-server tool filtering and utility policy |
|
||||
|
||||
### Minimal stdio example
|
||||
@@ -409,6 +410,23 @@ Because Hermes now only registers those wrappers when both are true:
|
||||
|
||||
This is intentional and keeps the tool list honest.
|
||||
|
||||
## Parallel Tool Calls
|
||||
|
||||
By default, MCP tools run sequentially — one at a time. If your MCP server exposes tools that are safe to run concurrently (e.g. read-only queries, independent API calls), you can opt-in to parallel execution:
|
||||
|
||||
```yaml
|
||||
mcp_servers:
|
||||
docs:
|
||||
command: "docs-server"
|
||||
supports_parallel_tool_calls: true
|
||||
```
|
||||
|
||||
When `supports_parallel_tool_calls` is `true`, Hermes may execute multiple tools from that server at the same time within a single tool-call batch, just like it does for built-in read-only tools (web_search, read_file, etc.).
|
||||
|
||||
:::caution
|
||||
Only enable parallel calls for MCP servers whose tools are safe to run at the same time. If tools read and write shared state, files, databases, or external resources, review the read/write race conditions before enabling this setting.
|
||||
:::
|
||||
|
||||
## MCP Sampling Support
|
||||
|
||||
MCP servers can request LLM inference from Hermes via the `sampling/createMessage` protocol. This allows an MCP server to ask Hermes to generate text on its behalf — useful for servers that need LLM capabilities but don't have their own model access.
|
||||
|
||||
@@ -21,6 +21,7 @@ High-level categories:
|
||||
| Category | Examples | Description |
|
||||
|----------|----------|-------------|
|
||||
| **Web** | `web_search`, `web_extract` | Search the web and extract page content. |
|
||||
| **X Search** | `x_search` | Search X (Twitter) posts and threads via xAI's built-in `x_search` Responses tool — gated on xAI credentials (SuperGrok OAuth or `XAI_API_KEY`); off by default, opt in via `hermes tools` → 🐦 X (Twitter) Search. |
|
||||
| **Terminal & Files** | `terminal`, `process`, `read_file`, `patch` | Execute commands and manipulate files. |
|
||||
| **Browser** | `browser_navigate`, `browser_snapshot`, `browser_vision` | Interactive browser automation with text and vision support. |
|
||||
| **Media** | `vision_analyze`, `image_generate`, `text_to_speech` | Multimodal analysis and generation. |
|
||||
|
||||
@@ -0,0 +1,117 @@
|
||||
---
|
||||
title: X (Twitter) Search
|
||||
description: Search X (Twitter) posts and threads from within the agent using xAI's built-in x_search Responses tool — works with either a SuperGrok OAuth login or an XAI_API_KEY.
|
||||
sidebar_label: X (Twitter) Search
|
||||
sidebar_position: 7
|
||||
---
|
||||
|
||||
# X (Twitter) Search
|
||||
|
||||
The `x_search` tool lets the agent search X (Twitter) posts, profiles, and threads directly. It's backed by xAI's built-in `x_search` tool on the Responses API at `https://api.x.ai/v1/responses` — Grok itself runs the search server-side and returns synthesized results with citations to the originating posts.
|
||||
|
||||
**Use this instead of `web_search`** when you specifically want current discussion, reactions, or claims **on X**. For general web pages, keep using `web_search` / `web_extract`.
|
||||
|
||||
## Authentication
|
||||
|
||||
`x_search` registers when **either** xAI credential path is available:
|
||||
|
||||
| Credential | Source | Setup |
|
||||
|------------|--------|-------|
|
||||
| **SuperGrok OAuth** (preferred) | Browser login at `accounts.x.ai`, refreshed automatically | `hermes auth add xai-oauth` — see [xAI Grok OAuth (SuperGrok Subscription)](../../guides/xai-grok-oauth.md) |
|
||||
| **`XAI_API_KEY`** | Paid xAI API key | Set in `~/.hermes/.env` |
|
||||
|
||||
Both hit the same endpoint with the same payload — the only difference is the bearer token. **When both are configured, SuperGrok OAuth wins** so x_search runs against your subscription quota instead of paid API spend.
|
||||
|
||||
The tool's `check_fn` runs the xAI credential resolver every time the model's tool list is rebuilt. A `True` return means the bearer is fetchable AND non-empty AND (if it had expired) successfully refreshed. Revoked tokens with a failed refresh hide the tool from the schema; the model simply can't see it.
|
||||
|
||||
## Enabling the tool
|
||||
|
||||
Off by default. Enable in `hermes tools`:
|
||||
|
||||
```bash
|
||||
hermes tools
|
||||
# → 🐦 X (Twitter) Search (press space to toggle on)
|
||||
```
|
||||
|
||||
The picker offers two credential choices:
|
||||
|
||||
1. **xAI Grok OAuth (SuperGrok Subscription)** — opens the browser to `accounts.x.ai` if you're not already logged in
|
||||
2. **xAI API key** — prompts for `XAI_API_KEY`
|
||||
|
||||
Either choice satisfies the gating. You can pick whichever credentials you already have; the tool works identically with both. If both end up configured, OAuth is preferred at call time.
|
||||
|
||||
## Configuration
|
||||
|
||||
```yaml
|
||||
# ~/.hermes/config.yaml
|
||||
x_search:
|
||||
# xAI model used for the Responses call.
|
||||
# grok-4.20-reasoning is the recommended default; any Grok model
|
||||
# with x_search tool access works.
|
||||
model: grok-4.20-reasoning
|
||||
|
||||
# Request timeout in seconds. x_search can take 60–120s for
|
||||
# complex queries — the default is generous. Minimum: 30.
|
||||
timeout_seconds: 180
|
||||
|
||||
# Number of automatic retries on 5xx / ReadTimeout / ConnectionError.
|
||||
# Each retry backs off (1.5x attempt seconds, capped at 5s).
|
||||
retries: 2
|
||||
```
|
||||
|
||||
## Tool parameters
|
||||
|
||||
The agent calls `x_search` with these arguments:
|
||||
|
||||
| Parameter | Type | Description |
|
||||
|-----------|------|-------------|
|
||||
| `query` | string (required) | What to look up on X. |
|
||||
| `allowed_x_handles` | string array | Optional list of handles to include **exclusively** (max 10). Leading `@` is stripped. |
|
||||
| `excluded_x_handles` | string array | Optional list of handles to exclude (max 10). Mutually exclusive with `allowed_x_handles`. |
|
||||
| `from_date` | string | Optional `YYYY-MM-DD` start date. |
|
||||
| `to_date` | string | Optional `YYYY-MM-DD` end date. |
|
||||
| `enable_image_understanding` | boolean | Ask xAI to analyze images attached to matching posts. |
|
||||
| `enable_video_understanding` | boolean | Ask xAI to analyze videos attached to matching posts. |
|
||||
|
||||
The tool returns JSON with:
|
||||
|
||||
- `answer` — synthesized text response from Grok
|
||||
- `citations` — citations returned by the Responses API top-level field
|
||||
- `inline_citations` — `url_citation` annotations extracted from the message body (each with `url`, `title`, `start_index`, `end_index`)
|
||||
- `credential_source` — `"xai-oauth"` if OAuth resolved, `"xai"` if API key resolved
|
||||
- `model`, `query`, `provider`, `tool`, `success`
|
||||
|
||||
## Example
|
||||
|
||||
Talking to the agent:
|
||||
|
||||
> What are people on X saying about the new Grok image features? Focus on responses from @xai.
|
||||
|
||||
The agent will:
|
||||
|
||||
1. Call `x_search` with `query="reactions to new Grok image features"`, `allowed_x_handles=["xai"]`
|
||||
2. Get back a synthesized answer plus a list of citations linking to specific posts
|
||||
3. Reply with the answer and references
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
### "No xAI credentials available"
|
||||
|
||||
The tool surfaces this when both auth paths fail. Either set `XAI_API_KEY` in `~/.hermes/.env` or run `hermes auth add xai-oauth` and complete the browser login. Then restart your session so the agent re-reads the tool registry.
|
||||
|
||||
### "`x_search` is not enabled for this model"
|
||||
|
||||
The configured `x_search.model` doesn't have access to the server-side `x_search` tool. Switch to `grok-4.20-reasoning` (the default) or another Grok model that supports it. Check the [xAI documentation](https://docs.x.ai/) for the current list.
|
||||
|
||||
### Tool doesn't appear in the schema
|
||||
|
||||
Two possible causes:
|
||||
|
||||
1. **Toolset not enabled.** Run `hermes tools` and confirm `🐦 X (Twitter) Search` is checked.
|
||||
2. **No xAI credentials.** The check_fn returns False, so the schema stays hidden. Run `hermes auth status` to confirm xai-oauth login state, and check that `XAI_API_KEY` is set (if you're using the API-key path).
|
||||
|
||||
## See Also
|
||||
|
||||
- [xAI Grok OAuth (SuperGrok Subscription)](../../guides/xai-grok-oauth.md) — the OAuth setup guide
|
||||
- [Web Search & Extract](web-search.md) — for general (non-X) web search
|
||||
- [Tools Reference](../../reference/tools-reference.md) — full tool catalog
|
||||
Reference in New Issue
Block a user