- Python 100%
| Filename | Latest commit message | Latest commit date |
|---|---|---|
Sync runtime -> repo (the accepted code wins): explicit-resume branch gated on returncode == 0 (fail-closed can_continue), _build_command refactor, _find_hermes_bin, refined session_id/continue schema docs. |
||
| .gitignore | ||
| __init__.py | ||
| plugin.yaml | ||
| README.md | ||
| schemas.py | ||
| tools.py | ||
delegate-profile
Delegate tasks to named Hermes Agent profiles with full isolation.
A Hermes Agent plugin that enables spawning isolated sub-agents — each with its own LLM model, toolsets, memory, skills, and session history — for concurrent or sequential task execution.
Overview
delegate-profile is the primary mechanism for offloading work to specialized agents within the Hermes Agent ecosystem. It bridges the main agent with profile-scoped workers, turning a single conversational thread into a multi-agent orchestration layer.
Key capabilities
- Profile isolation — Each delegated task runs as a separate Hermes process with its own:
- LLM model (e.g. fast model for research, smart model for code review)
- Toolsets (web, terminal, file, cronjob, etc.)
- Memory, skills, and session history
- Structured output — Returns JSON with
status,output, and diagnostic fields - Timeout control — Configurable per-task timeout (default 300s, max 3600s)
- Max iterations — Controls the depth of tool-calling chains (default 50)
- Graceful truncation — Output capped at 20000 characters with truncation notice
Installation
Prerequisites
- Hermes Agent CLI installed (typically at
~/.hermes/hermes-agent/.venv/bin/hermes) - At least one additional profile created (
hermes profile create <name>)
Setup
-
Copy the plugin directory to your Hermes plugins folder:
cp -r delegate-profile ~/.hermes/plugins/ -
Restart Hermes Agent or reload plugins:
hermes plugin reload -
Verify registration:
hermes tool list | grep delegate_profile
Usage
Basic delegation
delegate_profile(
profile="researcher",
goal="Find recent papers on RAG optimization and summarize key findings",
context="Focus on 2024-2025 publications. Output format: markdown with citations."
)
Multi-turn dialogue with session continuation
# Шаг 1: Начальный запрос (создает новую сессию)
r1 = delegate_profile(
profile="researcher",
goal="Find recent papers on RAG optimization"
)
# → {..., "session_id": "20260521_161520_c5d29a", "can_continue": true}
# Шаг 2: Follow-up вопрос (продолжаем ту же сессию)
r2 = delegate_profile(
profile="researcher",
goal="Give implementation details for the most promising approach",
session_id="20260521_161520_c5d29a" # Продолжаем предыдущую сессию
)
# Шаг 3: Ещё уточнение
r3 = delegate_profile(
profile="researcher",
goal="Compare this with the alternative approach mentioned earlier",
session_id="20260521_161520_c5d29a" # Та же сессия
)
Auto-continue last session
# Автоматически продолжает последнюю сессию (не нужно указывать session_id)
delegate_profile(
profile="researcher",
goal="Expand on the second paper's methodology",
continue=True # Продолжить последнюю сессию
)
With explicit iteration and timeout limits
delegate_profile(
profile="code-reviewer",
goal="Review the changes in the main.py file for security issues",
context="/workspace/main.py contains the target code",
max_iterations=100,
timeout=500
)
Tool Schema
| Parameter | Type | Required | Default | Description |
|---|---|---|---|---|
profile |
string | Yes | — | Name of the Hermes profile to delegate to |
goal |
string | Yes | — | Self-contained task description |
context |
string | No | — | Additional background: file paths, constraints, output format |
session_id |
string | No | — | ID of previous session to continue (for multi-turn dialogue) |
continue |
boolean | No | False | Continue last session instead of creating new one |
max_iterations |
integer | No | 50 | Maximum tool-calling turns for the profile agent |
timeout |
integer | No | 300 | Timeout in seconds (max: 3600) |
Return Format
Success response
The function returns a JSON object with the following fields:
| Field | Type | Description |
|---|---|---|
profile |
string | Name of the profile that executed the task |
status |
string | Execution status: "completed", "failed", or "timeout" |
returncode |
int | Exit code from the profile agent (0 = success) |
output |
string | Full output from the profile agent (truncated to 20000 chars if needed) |
stderr |
string|null | Error message if any (truncated to 500 chars) |
truncated |
bool | Whether the output was truncated due to length |
session_id |
string | NEW: ID of the created session for multi-turn continuation |
can_continue |
bool | NEW: Whether the session is active and can be continued |
Using the response for multi-turn
# First call - creates a new session
r1 = delegate_profile(
profile="researcher",
goal="Find papers on RAG optimization"
)
# → {"session_id": "sess_abc123", "can_continue": true, ...}
# Follow-up - continues the session
r2 = delegate_profile(
profile="researcher",
goal="Now give me implementation details",
session_id=r1["session_id"] # Continue from previous session
)
On timeout:
{
"profile": "researcher",
"status": "timeout",
"error": "Profile agent timed out after 300s",
"hint": "Increase timeout or simplify the task"
}
Architecture
How it works
┌─────────────────┐ subprocess.run() ┌──────────────────────┐
│ Main Agent │ ───────────────────────────> │ Profile Agent │
│ (parent) │ hermes -p <name> chat -q │ (isolated process) │
└─────────────────┘ └──────────────────────┘
│ │
│ JSON result │ Runs with profile's
│ │ model, tools, memory
└──────────────────────────────────────────────────┘
returns
- Validation — Checks that
profileandgoalare non-empty - Profile discovery — Looks for
HERMES_HOME/profiles/<name> - Binary resolution — Finds the Hermes CLI binary via:
HERMES_BINenvironment variable- Hardcoded fallback paths (
/opt/hermes/.venv/bin/hermes,/opt/hermes/hermes) - System
PATHlookup
- Command construction — Builds
hermes -p <profile> chat -q <prompt>with shell-safe escaping - Execution — Runs via
subprocess.run()with configurable timeout - Result parsing — Returns structured JSON with output, stderr, and truncation status
Process isolation
Each delegated profile runs as a completely separate process — it does not share:
- Conversation context (parent's chat history)
- Memory store
- Active tool sessions
- Session state
The profile only receives the explicitly provided goal and context.
Profile Configuration
Creating a new profile
# Create a researcher profile with a fast model
hermes profile create researcher --model openrouter/qwen-2.5-coder-32b-instruct --toolsets web,file
# Create a code-review profile with smart model + terminal tools
hermes profile create code-reviewer --model openrouter/claude-sonnet-4 --toolsets terminal,file
Available toolsets
| Toolset | Capabilities |
|---|---|
web |
Web search, browser automation |
terminal |
Shell commands, process management |
file |
File read/write/modify |
browser |
Full browser tooling |
cronjob |
Scheduled task management |
github |
GitHub operations (gh CLI) |
image_gen |
Image generation |
video_gen |
Video generation |
vision |
Image analysis |
delegation |
Sub-agent spawning |
When to use vs. when not to use
✅ Use delegate-profile for:
- Web research tasks → delegate to a profile with
web+filetoolsets and a fast model - Heavy data processing → delegate to a profile with
terminal+filetoolsets - Batch operations → spawn multiple profiles in parallel for independent tasks
- Context isolation → when you need a clean slate without parent conversation history
❌ Don't use for:
- Simple single-step queries — direct responses are faster
- Tasks requiring user interaction — profiles cannot ask clarification questions
- Stateful workflows — each run is ephemeral; no state persists between calls
Error Handling
| Error | Cause | Fix |
|---|---|---|
No profile specified |
Empty profile argument |
Provide a valid profile name |
No goal specified |
Empty goal argument |
Provide a task description |
Profile not found |
Profile directory missing | Run hermes profile list to see available profiles |
Hermes binary not found |
CLI binary missing from all fallback paths | Set HERMES_BIN env var or install Hermes CLI |
timeout exceeded |
Task took longer than configured | Increase timeout parameter or simplify the task |
File Structure
delegate-profile/
├── __init__.py # Plugin registration and entry point
├── plugin.yaml # Plugin metadata (name, version, tool registration)
├── schemas.py # Tool schema definition for parameter validation
└── tools.py # Core delegation logic: binary resolution, subprocess execution
__init__.py
Registers the delegate_profile tool under the delegate-profile toolset via ctx.register_tool().
tools.py
Contains three main functions:
_find_hermes_bin()— Binary discovery chain (env → hardcode → PATH)_build_prompt()— Constructs the final prompt with goal + context + system instructionsdelegate_profile()— Main handler: validation → execution → structured JSON output
schemas.py
Defines the OpenAI-compatible tool schema for delegate_profile, including:
- Parameter descriptions
- Required field enforcement
- Default values
Security Considerations
- Shell-safe escaping — The prompt is passed via
shlex.quote()to prevent command injection - Process isolation — Each delegate runs in a separate process with no shared memory
- No user interaction — Profiles cannot prompt the user for clarification
- Output truncation — 20000 char limit prevents excessive resource consumption
- Timeout ceiling — Hard-capped at 3600 seconds to prevent runaway processes
Dependencies
- Python 3.11+ — Standard library only (
json,subprocess,logging,os,shlex,pathlib) - Hermes Agent CLI — Installed at
~/.hermes/hermes-agent/.venv/bin/hermesor discoverable via PATH - No external packages — Zero pip dependencies
Troubleshooting
"Profile not found"
# List available profiles
hermes profile list
# Create a missing profile
hermes profile create <name> --model <model> --toolsets <toolsets>
"Hermes binary not found"
# Check if hermes is installed
which hermes
# Set custom path
export HERMES_BIN=/path/to/hermes
# Or ensure it's in PATH
export PATH=$PATH:/path/to/hermes
"Profile agent timed out"
# Increase timeout (max 3600)
delegate_profile(
profile="researcher",
goal="...",
timeout=3500
)
License
Same as Hermes Agent.
Contributing
This is an internal Hermes Agent plugin. For bug reports or feature requests, open an issue against the Hermes Agent repository.