mirror of
https://github.com/NousResearch/hermes-agent.git
synced 2026-07-31 19:16:29 +00:00
43874d1a96
Accuracy pass (all 373 pages audited against code, 13 parallel audits):
- configuration.md: 12 stale defaults/keys (file-sync rewrite, clarify
timeout, streaming knobs, iteration budget, TTS/STT enums)
- reference/: commands/env-vars/toolsets/tools synced with
COMMAND_REGISTRY, argparse tree, OPTIONAL_ENV_VARS, TOOLSETS
(28 env vars added, 3 phantom removed, mcp__ naming, webhook
platform restricted toolset)
- features/, messaging/, developer-guide/, guides/: ~60 factual fixes
(web_extract truncation, dashboard auth fail-closed, delegation
blocked tools, adapter signatures, session schema v23, phantom
Matrix env vars, hermes setup tts, auth spotify, webhook --skills)
- zh-Hans: explicit heading IDs fix 2 broken WSL2 anchors
New coverage for features shipped in the last 2 months (verified
against code before writing):
- compression.in_place, verify-on-stop (+v31/v32 migration reality),
${env:VAR} SecretRef, display.timestamp_format, session:compress
hook + thread_id/chat_type fields
- /journey learning timeline, per-channel model/system-prompt
overrides, /sessions search, clarify multi-select, -z --usage-file,
uninstall --dry-run, config get/unset
- MCP elicitation, extra_headers, discover_models, api-server run cap,
Bedrock cachePoint, Discord reasoning_style, Google Chat clarify
cards, vibe reactions, resume cwd restore, Yuanbao forwarded
messages, api_content sidecar, roaming pet, tool_progress log mode,
WhatsApp polls/locations, kanban per-task model + lifecycle hooks
134 lines
5.7 KiB
Markdown
134 lines
5.7 KiB
Markdown
---
|
|
title: Deliverable Mode (Artifacts in Chat)
|
|
sidebar_label: Deliverable Mode
|
|
description: How the agent ships generated charts, PDFs, spreadsheets, and other files as native attachments in messaging platforms.
|
|
---
|
|
|
|
# Deliverable Mode
|
|
|
|
When Hermes Agent runs inside a messaging gateway (Slack, Discord, Telegram,
|
|
WhatsApp, Signal, etc.), it can deliver generated files directly into the
|
|
chat — not as paths the user has to copy, but as native attachments.
|
|
|
|
A chart shows up as an inline image. A PDF report shows up as a file
|
|
download. A spreadsheet uploads as `.xlsx`. The agent does not need to
|
|
write a `MEDIA:` tag or do anything special — it just generates the file
|
|
and mentions its absolute path in the response. The gateway picks the path
|
|
out of the text, removes it from the visible message, and uploads the
|
|
file natively.
|
|
|
|
## How it works
|
|
|
|
Three pieces fit together:
|
|
|
|
1. **The agent has tools that produce files.** `execute_code` for charts via
|
|
matplotlib, the `docx` skill for Word documents, the `xlsx` skill for
|
|
spreadsheets, the `pdf` and `latex-pdf-report` skills for PDFs, the
|
|
`powerpoint` skill for decks, `image_generate` for images,
|
|
`text_to_speech` for audio, and so on.
|
|
|
|
2. **The gateway scans agent responses for file paths.** Any absolute path
|
|
(`/tmp/...`) or home-relative path (`~/...`) ending in a supported
|
|
extension gets extracted. Paths inside code blocks and inline code are
|
|
ignored so code samples are never mutilated.
|
|
|
|
3. **The gateway dispatches by file type.** Images embed inline where the
|
|
platform supports it; videos embed inline; audio routes to voice/audio
|
|
attachments; everything else uploads as a file attachment.
|
|
|
|
## Supported file extensions
|
|
|
|
| Category | Extensions | Delivery |
|
|
|---|---|---|
|
|
| Images | `.png .jpg .jpeg .gif .webp .bmp .tiff .svg` | Inline embed |
|
|
| Video | `.mp4 .mov .avi .mkv .webm .3gp` | Inline embed (where supported) |
|
|
| Audio | `.mp3 .m2a .wav .ogg .opus .m4a .flac` | Voice / audio attachment |
|
|
| Documents | `.pdf .docx .doc .odt .rtf .txt .md .epub` | File upload |
|
|
| Data | `.xlsx .xls .ods .csv .tsv .json .xml .yaml .yml` | File upload |
|
|
| Geospatial | `.kmz .kml .geojson .gpx` | File upload |
|
|
| Presentations | `.pptx .ppt .odp .key` | File upload |
|
|
| Archives | `.zip .tar .gz .tgz .bz2 .xz .7z .rar .apk .ipa` | File upload |
|
|
| Web | `.html .htm` | File upload |
|
|
|
|
`.py`, `.log`, and other source-file extensions are intentionally excluded so
|
|
the agent doesn't auto-ship arbitrary source files; if you want to send code
|
|
to the user, use a code block.
|
|
|
|
## Encouraging the agent to produce artifacts
|
|
|
|
The agent doesn't reach for artifacts by default — it has to know to.
|
|
Two ways to nudge it:
|
|
|
|
**Per-session:** ask explicitly ("send me the comparison as a chart",
|
|
"return the data as a CSV") or write your own custom-instructions /
|
|
personality entry that biases toward artifact-style replies on
|
|
messaging platforms.
|
|
|
|
**Project-level:** add the bias to `AGENTS.md` / `CLAUDE.md` /
|
|
`.cursorrules` in a project the agent works from, to your global
|
|
persona in `~/.hermes/SOUL.md`, or as a named preset under
|
|
`agent.personalities` in `~/.hermes/config.yaml` (switchable per session
|
|
via `/personality`).
|
|
|
|
The mechanic the agent has to use is simple: render the file to an
|
|
absolute path (e.g. `/tmp/q3-revenue.png`) and mention that path as
|
|
plain text in the reply. The gateway does the rest. Paths inside
|
|
fenced code blocks or backticks are ignored so code samples are never
|
|
mutilated.
|
|
|
|
## Kanban: artifacts ride completion notifications
|
|
|
|
If you use Hermes' kanban multi-agent workflow, workers can attach
|
|
deliverable files to their `kanban_complete` call:
|
|
|
|
```python
|
|
kanban_complete(
|
|
summary="rendered Q3 revenue chart and report",
|
|
artifacts=[
|
|
"/tmp/q3-revenue.png",
|
|
"/tmp/q3-report.pdf",
|
|
],
|
|
)
|
|
```
|
|
|
|
When the gateway notifier delivers the "task completed" message to whoever
|
|
subscribed to the task in Slack/Telegram/etc., it also uploads each artifact
|
|
as a native attachment to that chat. The human gets the deliverable and the
|
|
summary in one place.
|
|
|
|
Files that don't exist on disk when the notifier runs are silently skipped.
|
|
|
|
## Connecting more services with MCP
|
|
|
|
Beyond the artifact-delivery pipeline, the agent can reach into other
|
|
services via MCP (Model Context Protocol). The MCP ecosystem ships
|
|
community servers for most popular tools — install whichever you need:
|
|
|
|
| Service | What it unlocks |
|
|
|---|---|
|
|
| **Notion** | Read/write Notion pages, databases, query workspace |
|
|
| **GitHub** | Issues, PRs, comments, repo search beyond the gh CLI |
|
|
| **Linear** | Tickets, projects, cycles |
|
|
| **Slack** | Workspace-wide search, read other channels |
|
|
| **Gmail** | Inbox triage, send mail, label management |
|
|
| **Salesforce** | Leads, opportunities, account data |
|
|
| **Snowflake / BigQuery** | SQL against data warehouses |
|
|
| **Google Drive** | File search, contents, share management |
|
|
|
|
Install MCP servers via `~/.hermes/config.yaml` under the `mcp_servers`
|
|
section. See [MCP integration](./mcp.md) for the full setup guide.
|
|
|
|
## Comparison to Perplexity Computer in Slack
|
|
|
|
Perplexity Computer's Slack integration is built around the same idea:
|
|
the agent generates a deliverable (chart, PDF, slide deck) and posts it
|
|
back into the thread as a native attachment. Hermes Agent's deliverable
|
|
mode provides the same user-facing pattern locally:
|
|
|
|
- Generation happens in the user's own venv / sandbox (no remote tenant).
|
|
- Files land in the chat via the same Slack `files.uploadV2` API.
|
|
- Connector breadth comes via MCP rather than a curated catalog of 400
|
|
hosted integrations — install the ones you actually use.
|
|
|
|
OAuth tokens stay on the user's machine in `auth.json` / `.env`. No hosted
|
|
token storage. No multi-tenant microVM. Same end result.
|