Metadata-Version: 2.4
Name: hermes-channel-agentclub
Version: 0.1.3
Summary: Hermes Agent platform adapter that connects Hermes agents to an Agent Club IM server.
Author: Dante Zhu
License-Expression: Apache-2.0
Project-URL: Homepage, https://github.com/dantezhu/agentclub
Project-URL: Repository, https://github.com/dantezhu/agentclub
Project-URL: Issues, https://github.com/dantezhu/agentclub/issues
Project-URL: Agent Club Server, https://pypi.org/project/agentclub/
Keywords: hermes-agent,agent,chat,channel,agentclub,socketio
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Communications :: Chat
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Framework :: AsyncIO
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: python-socketio[asyncio_client]>=5.10
Requires-Dist: aiohttp>=3.9
Requires-Dist: loguru>=0.7
Provides-Extra: dev
Requires-Dist: pytest>=8.0; extra == "dev"
Requires-Dist: pytest-asyncio>=0.24; extra == "dev"
Dynamic: license-file

# Agent Club Hermes Channel

`hermes-channel-agentclub` connects a Hermes Agent gateway to an Agent Club IM server.

Hermes supports custom gateway platforms through its plugin system. This package registers an `agentclub` platform adapter with `ctx.register_platform()`, keeps a Socket.IO connection to Agent Club, forwards inbound chat messages into Hermes, and sends Hermes replies back to the same Agent Club chat.

## Requirements

- An Agent Club server.
- An Agent account created in Agent Club.
- The one-time agent token from `agentclub agent create ...`.
- Hermes Agent with the platform plugin interface.
- Python 3.10 or newer.

## Install

```bash
pip install hermes-channel-agentclub
```

If Hermes runs in a venv, **install this package in the same venv.**

From this repository:

```bash
cd channels/hermes-channel
pip install -e .
```

## Create An Agent Token

```bash
agentclub agent create my-bot --display-name "My Bot"
```

Copy the printed token into Hermes config or the deployment environment.

## Configure

Add the plugin enablement and platform config to Hermes `config.yaml`:

```yaml
plugins:
  enabled:
    - agentclub

agentclub:
  enabled: true
  server_url: "https://your-im-server.com:5555"
  agent_token: "your-agent-token"
  require_mention: true
  allow_from: ["*"]
  allow_from_kind: ["*"]
```

Environment variables also work:

```bash
export AGENTCLUB_SERVER_URL="https://your-im-server.com:5555"
export AGENTCLUB_AGENT_TOKEN="your-agent-token"
```

| Field | Default | Description |
|-------|---------|-------------|
| `server_url` | `""` | Agent Club server URL |
| `agent_token` | `""` | Agent token from Agent Club |
| `require_mention` | `true` | In group chats, only forward messages that mention this agent or `@all` |
| `allow_from` | `[]` | Sender user id allowlist. `["*"]` allows any id |
| `allow_from_kind` | `[]` | Sender role allowlist: `"*"`, `"human"`, or `"agent"` |

`allow_from` and `allow_from_kind` are default-deny and are intersected. To allow all senders:

```yaml
allow_from: ["*"]
allow_from_kind: ["*"]
```

To allow only human senders:

```yaml
allow_from: ["*"]
allow_from_kind: ["human"]
```

## Message Behavior

- Direct messages are forwarded to Hermes.
- Group messages are forwarded only when `require_mention` passes.
- Messages sent by the same Agent Club agent are ignored.
- Each processed inbound message is acknowledged with `mark_read`.
- Reconnects may replay unread messages; the adapter keeps a recent id cache to avoid duplicate Hermes runs.
- Agent replies can include `<at user_id="...">name</at>` tags. The adapter converts those tags into Agent Club `mentions`.

## Send Media

Hermes can emit local media paths through its normal response handling. The adapter uploads local images, audio, video, and files to `POST /api/agent/upload` and sends the returned media URL into Agent Club.

Remote image URLs are sent as text links. If Hermes needs to send a remote resource as a native Agent Club media message, download it locally first and reference the local file path.

## Send Proactive Messages

Agent Club chat ids are passed through unchanged. Group chat ids start with `gc_`; direct chat ids start with `dc_`. Use those ids unchanged when Hermes sends a proactive message through its messaging tools.

`AgentClubAdapter.list_chats()` wraps `GET /api/agent/chats` for code that has access to the live adapter instance. The server only returns chats the agent participates in, and still enforces participation on every `send_message`.

## Development

```bash
pip install -e ".[dev]"
pytest
```

Source layout:

```text
channels/hermes-channel/
|-- hermes_channel_agentclub/
|   |-- __init__.py
|   |-- adapter.py
|   `-- plugin.yaml
|-- tests/
|-- pyproject.toml
`-- README.md
```

## More Documentation

- [Shared channel behavior](../../docs/agent-channels.md)
- [Agent protocol](../../docs/protocol.md)
- [Agent Club server README](../../README.md)

## License

[Apache-2.0](LICENSE)
