Multi-Agent Workgroup

← back to homework

Build and orchestrate a multi-agent workgroup using Paperclip, Hugging Face MCP tools, and Hermes skills; learn to construct, test, and deploy custom Python tools and MCP connectors.

Folder: /mnt/datapool/hermes_workspace/projects/multi-agent-workgroup · in progress - company ndyinc live with 4 agents (Wind Sculptor, Render Artist, Draftsman, Cart Builder); 8 issues NDY-1..8 (7 done, 1 backlog); Slow Bloom design docs + BOM delivered & verified

Start a session here (paste into a terminal):

cd /mnt/datapool/hermes_workspace/projects/multi-agent-workgroup && hermes

What's in the folder

docs/
log.md · report-2026-11-01.md

schemas/
book_progress.schema.json · health_watch.schema.json · md_to_pdf.schema.json · new_tool.schema.json · system_health.schema.json

Project notes

Project: Multi-Agent Workgroup (multi-agent-workgroup)

Hermes: this file is the context for the Multi-Agent Workgroup project assistant.

You are in /mnt/datapool/hermes_workspace/projects/multi-agent-workgroup. Work from here unless told otherwise.

Objective

Build and orchestrate a multi-agent workgroup using Paperclip, Hugging Face MCP tools, and Hermes skills; learn to construct, test, and deploy custom Python tools and MCP connectors.

Status

the tailnet :3100, board admin Mike, employees: Wind Sculptor, Render Artist, Draftsman,

Cart Builder. 8 issues NDY-1–8 (7 done, 1 backlog). Next: the open item NDY-8 or Mike's next

choice. For learning the tool, see the paperclip-learning project.

Built so far (each = script + schema, tested)

| Tool | What it does |

|---|---|

| scripts/system_health.py | One JSON answer to "is the 3050 healthy?": T130 mount, root disk, bookapp, Hermes gateway, all cron jobs, Drive token. 3s, exit 1 if anything failed. |

| scripts/book_progress.py | Word counts per Google Doc in the Drive "Book Sections" folder, plus totals and a markdown table. Stdlib only (refreshes the Google token itself). |

| scripts/new_tool.py | Scaffolds the next tool pair (scripts/x.py + schemas/x.schema.json) and runs an import + run check before reporting success. |

| scripts/health_watch.py | Watchdog around system_health: prints a message only on a NEW problem, a problem still present after 12h, or a recovery. Silent when healthy. Runs hourly via cron 2029a25b3d3a ("3050 health watchdog") → Telegram on failure only. Cron needs scripts under ~/.hermes/scripts/, so the job calls the thin shim ~/.hermes/scripts/watch_system_health.py, which execs this tool and reports if the share (and therefore the tool) is unreachable. |

| scripts/mcp_server.py | MCP wrapper (not a tool pair): a stdio MCP server exposing the project's own tools under the names health (= system_health) and book_words (= book_progress). Registered in Hermes as mcp_servers.workgroup → agent sees mcp_workgroup_health / mcp_workgroup_book_words. Imports the two modules by path, so there is exactly one implementation of each. Uses the MCP Python SDK v2 API (from mcp.server.mcpserver import MCPServer — v1's mcp.server.fastmcp.FastMCP no longer exists). |

Found on 2026-10-30 with book_progress: the book is 3,333 words — Chapter 1 (1,198),

Chapter 2 (1,322), Part I (813). Chapters 3–10 are empty stubs (Drive docs contain only

a BOM).

What "done" looks like

At least 3 working custom tools each with a JSON schema, one Hugging Face MCP connector wired up, and a documented multi-agent run.

Paths (all under this project root)

```

/mnt/datapool/hermes_workspace/projects/multi-agent-workgroup/

.hermes.md this file — auto-loaded project rules

README.md human quickstart (how to start THIS assistant)

src/ source code for the project

scripts/ runnable one-off scripts + generated tools

schemas/ JSON schemas for every custom tool (<name>.schema.json)

output/ generated artifacts, reports, exports

docs/ notes, decisions, references

venv/ per-project Python venv (created on demand)

```

Shared, project-independent facts (host, storage, runtime) live in

/mnt/datapool/hermes_workspace/ENVIRONMENT.md — read it instead of assuming.

Working rules

1. Save every generated script, schema, and output under /mnt/datapool/hermes_workspace/projects/multi-agent-workgroup/ —

never leave artifacts in ~ or the scratch dir.

2. Every custom tool ships as two files in the same change:

scripts/<tool_name>.py and schemas/<tool_name>.schema.json.

Copy the working pair at /mnt/datapool/hermes_workspace/templates/example_tool.py +

example_tool.schema.json as the starting shape: pure function, stdin JSON →

stdout JSON, no side effects on import.

3. Test before marking anything complete. No Docker here: use

/usr/bin/python3 -m venv venv && ./venv/bin/pip install ... (bare python3

in a Hermes session is Hermes' own runtime and has no pip), or run the script

and show real output. Paste actual command output, never a description of it.

4. Keep terminal explanations to a single copy-and-pasteable command per step.

5. Custom tools must be importable as plain Python before they are wrapped as MCP tools.

Tools, MCP & workgroup

Hermes on the 3050; delegate_task subagents; Hugging Face MCP installed and live (4 tools: hf_whoami, hub_repo_search, hub_repo_details, hf_fs; header auth via MCP_HUGGING_FACE_API_KEY in ~/.hermes/.env, account @criticalmike); workgroup MCP server live — this project's own tools wrapped and callable as mcp_workgroup_health / mcp_workgroup_book_words (stdio, config at mcp_servers.workgroup in ~/.hermes/config.yaml; needs a new Hermes session to appear — MCP tools do not hot-reload); Paperclip on the 9010 — now defined, see the Paperclip section: the open-source multi-agent orchestration app (paperclipai/paperclip) that can hire this Hermes as an employee via NousResearch/hermes-paperclip-adapter. Needs Node 24.11+ (host has 22.23.3).

Paperclip — what it is (defined 2026-10-31)

Paperclip (github.com/paperclipai/paperclip, MIT, ~74k★, by pseudonymous dev @dotta,

launched March 2026) is an open-source app that runs a team of AI agents like a company.

It is deliberately not an agent framework — it is the management layer above agents:

an org chart (roles, titles, reporting lines, permissions), a ticket board, per-agent

budgets with hard stops, heartbeat scheduling, human approval gates, and a durable

audit log. It's a Node.js server + React UI on http://localhost:3100 with an

embedded PostgreSQL — no Docker and no database setup required.

Its hiring rule: "If it can receive a heartbeat, it's hired."

Why this matters for this project: Nous Research ships an official adapter —

NousResearch/hermes-paperclip-adapter (npm install hermes-paperclip-adapter, adapter

type hermes_local) — which hires this Hermes as a managed employee. On each heartbeat

Paperclip wakes Hermes with the task, Hermes works using its full tool suite (including the

workgroup and hugging_face MCP tools), and reports back into Paperclip. The adapter reads

~/.hermes/config.yaml for the model and scans ~/.hermes/skills/. That is exactly the

"multi-agent workgroup" this project exists to build: **Paperclip is the org, Hermes is the

employee.**

the Tailscale setup; use --bind lan for the home LAN).

read "Workstation: Dell OptiPlex 9010 (daily interface for Paperclip & VS Code)". It sat

undefined as a project keyword until this date.

Outputs / deliverables

Under this project's output/ and scripts/.

Environment

Shared Environment — 3050 / T130 (single source of truth)

This block is injected into every project's .hermes.md by bin/new-project, so

host facts live in ONE place. Update here, not per project.

(cifs, vers=3.1.1, uid/gid 1000, rw). There is NO /mnt/t130_storage on this host.

⚠ Inside a Hermes session, bare python3 resolves to Hermes' own bundled runtime

(3.14.7) which has no pip — python3 -m pip install x fails with

"No module named pip". Always build project venvs explicitly:

/usr/bin/python3 -m venv venv && ./venv/bin/pip install ...

2.5.4 (cp314 wheel) and tokenizers 0.23.3 all resolve — the HF/MCP stack is fine

on this Python, no downgrade needed.

Version control & backup

mandatory on the SMB share, not cosmetic: core.filemode=false (the share forces

0755) and core.trustctime=false — CIFS ctimes are unreliable, and with them

trusted git add can treat a just-written file as unchanged and commit a **stale

blob**. Commit when a unit of work is finished:

cd /mnt/datapool/hermes_workspace && git add -A && git commit -m "...", then

confirm git status --short is empty — if it still lists files, re-add and commit

again before trusting the commit.

gdrive:3050-HOME/hermes_workspace (one-way up, .git included, so the

Drive copy is a real clonable repo). Script ~/.hermes/scripts/backup_hermes_workspace.sh,

log ~/.hermes/cron/output/hermes-workspace-backup.log. It prints nothing on

success and pings Telegram only on failure.

rclone sync against a missing mount would delete the Drive copy, so it gates

on the mount, a sentinel file, and a minimum file count, and caps deletions.

job (sync_to_drive.sh, which covers $HOME/{book,hermes-3050,agent-os,projects,bookapp}).

Two sync jobs touching one tree is how you get conflicts.

Verified against live command output 2026-10-30. Re-verify with:

hostname; ip -4 addr; mount | grep datapool; python3 -V; node -v; docker --version

Session handoff

When work stops: update Status (state + next step) in this file, then log one

line in /mnt/datapool/hermes_workspace/projects/multi-agent-workgroup/docs/log.md with date + what changed + what's next.

Built live from your own files — nothing here is typed by hand.