Skip to content

docs: document provides_tools client-tool registration for platform plugins #86714

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
teknium1 merged 1 commit into from
Aug 15, 2026
+37 −1
Merged

docs: document provides_tools client-tool registration for platform plugins #86714

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
28 changes: 28 additions & 0 deletions website/docs/developer-guide/adding-platform-adapters.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -61,6 +61,34 @@ optional_env:
password: false
```

#### Outbound client tools: `provides_tools`

`kind: platform` plugins are **deferred**: the adapter module (and its SDK
imports) only load when a gateway, cron, or `send_message` path first asks the
platform registry for the platform. If your plugin also ships outbound *client
tools* the agent should be able to call from any session (the bundled `a2a`
plugin's `a2a_call` / `a2a_discover` etc.), put them in a dedicated `tools.py`
with a `register_tools(ctx)` function and declare them in the manifest:

```yaml
provides_tools:
- my_platform_call
- my_platform_list
```

With `provides_tools` declared, Hermes imports only `tools.py` during plugin
discovery and registers the client tools in every process — CLI and TUI
included — while the adapter stays deferred. Keep the package `__init__.py`
import-light and pull the adapter in from inside `register()` so the eager
import stays cheap. Without the field, nothing changes: the whole plugin stays
deferred.

Users enable the toolset per platform like any other, e.g.
`hermes tools enable my_platform --platform cli`, or by listing the toolset
key under `platform_toolsets` in `config.yaml`. Plugin platform names are
also valid `--platform` targets, so an inbound session on your platform can
be granted its own outbound tools.

### adapter.py

```python
Expand Down
10 changes: 9 additions & 1 deletion website/docs/user-guide/messaging/a2a.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -29,7 +29,15 @@ gateway:
port: 9900
```

The outbound client tools ship as the `a2a` toolset, **off by default** — enable it with `hermes tools`.
The outbound client tools ship as the `a2a` toolset, **off by default** — enable it per platform:

```bash
hermes tools enable a2a --platform cli # CLI/TUI sessions
hermes tools enable a2a --platform telegram # or any messaging platform
hermes tools enable a2a --platform a2a # let inbound A2A tasks call peers (agent chaining)
```

The tools are available in every process type — CLI, TUI, gateway, and cron — without the inbound platform needing to be enabled.

## Outbound: calling other agents

Expand Down
Loading