hermes - ✅(Solved) Fix QQ Bot: File attachments downloaded but not passed to agent [1 pull requests, 2 comments, 2 participants]

Official PRs (…)
ON THIS PAGE

Recommended Tools

×6

Utilities matched from this issue’s tags and category — try them while you read without losing context.

GitHub issue graph ai analysis

Paste a GitHub issue URL. We fetch that issue, discover linked issues from bodies/comments/timeline, collect linked pull requests, and produce a structured English report.

The report is written in English Markdown for sharing and archival.

Helpful · Quick feedback

Loading…
GitHub stats
NousResearch/hermes-agent#14301Fetched 2026-04-23 07:45:43
View on GitHub
Comments
2
Participants
2
Timeline
8
Reactions
0
Author
Participants
Timeline (top)
labeled ×4commented ×2cross-referenced ×2

Root Cause

In gateway/platforms/qqbot/adapter.py, _process_attachments() method:

  • Line 1187-1194: Files are downloaded via _download_and_cache() and cached_path is obtained ✅
  • However, cached_path is only used to append text [Attachment: {filename}] to other_attachments
  • The cached_path is NOT passed to MessageEvent.media_urls
  • In contrast, images correctly populate image_urls which is passed to MessageEvent.media_urls
# Current (buggy) code in _process_attachments():
else:
    cached_path = await self._download_and_cache(url, ct)
    if cached_path:
        other_attachments.append(f"[Attachment: {filename or ct}]")  # ← only text, not path

And when building MessageEvent:

media_urls=image_urls,  # ← only image_urls, no file paths

Fix Action

Fixed

PR fix notes

PR #14305: fix(qqbot): pass cached attachments to message events

Description (problem / solution / changelog)

Summary

  • keep cached QQ document and file attachments on the inbound MessageEvent instead of reducing them to text-only placeholders
  • classify non-image cached attachments as document media so attachment-only QQ messages still reach the agent correctly
  • add regressions for attachment processing and C2C event delivery

Testing

  • python3 -m pytest -o addopts='' tests/gateway/test_qqbot.py

Fixes #14301

Changed files

  • gateway/platforms/qqbot/adapter.py (modified, +54/-41)
  • tests/gateway/test_qqbot.py (modified, +72/-0)

Code Example

# Current (buggy) code in _process_attachments():
else:
    cached_path = await self._download_and_cache(url, ct)
    if cached_path:
        other_attachments.append(f"[Attachment: {filename or ct}]")  # ← only text, not path

---

media_urls=image_urls,  # ← only image_urls, no file paths
RAW_BUFFERClick to expand / collapse

Bug Description

When receiving file attachments via QQ Bot, the adapter successfully downloads the file to local cache, but the cached file path is never passed to the MessageEvent. The agent only receives [Attachment: filename] as text instead of the actual file.

Steps to Reproduce

  1. Send any file (e.g., .xlsx, .csv) to Hermes via QQ Bot
  2. Observe that only [Attachment: filename] text appears in the chat
  3. The file is NOT accessible to the agent

Expected Behavior

The downloaded file should be accessible to the agent (similar to how images are passed via media_urls).

Root Cause

In gateway/platforms/qqbot/adapter.py, _process_attachments() method:

  • Line 1187-1194: Files are downloaded via _download_and_cache() and cached_path is obtained ✅
  • However, cached_path is only used to append text [Attachment: {filename}] to other_attachments
  • The cached_path is NOT passed to MessageEvent.media_urls
  • In contrast, images correctly populate image_urls which is passed to MessageEvent.media_urls
# Current (buggy) code in _process_attachments():
else:
    cached_path = await self._download_and_cache(url, ct)
    if cached_path:
        other_attachments.append(f"[Attachment: {filename or ct}]")  # ← only text, not path

And when building MessageEvent:

media_urls=image_urls,  # ← only image_urls, no file paths

Environment

  • Hermes Agent v0.10.0 (2026.4.16)
  • QQ Bot platform

Suggested Fix

Either:

  1. Add downloaded file paths to MessageEvent.media_urls alongside images, OR
  2. Add a new field like document_urls to MessageEvent and pass file paths there

extent analysis

TL;DR

Modify the _process_attachments() method to pass the cached_path to MessageEvent.media_urls or introduce a new field like document_urls to handle file attachments.

Guidance

  • Identify the lines in adapter.py where cached_path is obtained and modify the code to append this path to MessageEvent.media_urls instead of just the filename text.
  • Consider introducing a new field document_urls in MessageEvent to handle file attachments separately from images, to avoid potential conflicts or limitations.
  • Verify that the media_urls or new field is correctly populated with the file path by logging or debugging the MessageEvent object after modification.
  • Ensure that the agent can access and handle the file attachments correctly once the file path is passed to MessageEvent.

Example

# Modified code in _process_attachments():
else:
    cached_path = await self._download_and_cache(url, ct)
    if cached_path:
        other_attachments.append(cached_path)  # ← append the actual file path
        # or introduce a new field like document_urls
        document_urls.append(cached_path)

Notes

The suggested fix assumes that the media_urls field can handle both image and file attachments. If there are specific requirements or limitations for handling different types of attachments, introducing a new field like document_urls might be a better approach.

Recommendation

Apply workaround by modifying the _process_attachments() method to pass the cached_path to MessageEvent.media_urls or introduce a new field like document_urls, as this directly addresses the identified issue and allows for a straightforward verification of the fix.

Vote matrix · Quick signals

Works
Did the solution work? Tap to confirm.
Easy Fix
Was it a quick fix?
Time Saver
Did it save you time?
Blocking
Was it severely blocking?
Common Issue
Are others likely hitting this too?
Flaky / Intermittent
Is it intermittent?
Verified / Reproducible
Can you reproduce it reliably?
Loading…

Still need to ship something?

×6

Another batch ranked right after the header list — different links, same matching logic.

Back to top recommendations

TRENDING