No description
Find a file
Repository files (latest commit first)
Filename Latest commit message Latest commit date
Slopych 44b68c67d1 delegate-profile: sync final accepted runtime state
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.
2026-11-11 17:38:14 +03:00
.gitignore delegate-profile: plugin source, base for nix-managed deployment 2026-11-11 12:26:40 +03:00
__init__.py delegate-profile: plugin source, base for nix-managed deployment 2026-11-11 12:26:40 +03:00
plugin.yaml delegate-profile: plugin source, base for nix-managed deployment 2026-11-11 12:26:40 +03:00
README.md delegate-profile: plugin source, base for nix-managed deployment 2026-11-11 12:26:40 +03:00
schemas.py delegate-profile: sync final accepted runtime state 2026-11-11 17:38:14 +03:00
tools.py delegate-profile: sync final accepted runtime state 2026-11-11 17:38:14 +03:00

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

  1. Copy the plugin directory to your Hermes plugins folder:

    cp -r delegate-profile ~/.hermes/plugins/
    
  2. Restart Hermes Agent or reload plugins:

    hermes plugin reload
    
  3. 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
  1. Validation — Checks that profile and goal are non-empty
  2. Profile discovery — Looks for HERMES_HOME/profiles/<name>
  3. Binary resolution — Finds the Hermes CLI binary via:
    • HERMES_BIN environment variable
    • Hardcoded fallback paths (/opt/hermes/.venv/bin/hermes, /opt/hermes/hermes)
    • System PATH lookup
  4. Command construction — Builds hermes -p <profile> chat -q <prompt> with shell-safe escaping
  5. Execution — Runs via subprocess.run() with configurable timeout
  6. 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 + file toolsets and a fast model
  • Heavy data processing → delegate to a profile with terminal + file toolsets
  • 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 instructions
  • delegate_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/hermes or 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.