hermes-plivo-tools
Plivo tools for Hermes Agent. The agent sends text messages, places phone calls and looks up numbers through Plivo.
| Tool | Detail |
|---|---|
send_sms |
Sends a text message to a phone number |
make_call |
Places a call answered by Plivo call-control XML, for notifications and alerts |
lookup_number |
Returns carrier, country, line type and formatting details |
The plugin registers tools only. It hosts no server and registers no messaging platform, and runs anywhere a Hermes agent runs. Standard library only, with no third-party dependencies.
Requirements
| Hermes Agent | Python 3.11 or later |
| Plivo | An account, an SMS-capable number for send_sms, a voice-capable number for make_call |
Installation
1. Install
pip install hermes-plivo-tools
Installing hermes-plivo-phone-gateway brings the plugin in as a dependency.
2. Enable
hermes plugins enable plivo-tools
hermes tools list
Hermes is opt-in and loads no plugin until enabled. Each tool is its own toolset, listed as
plivo_send_sms, plivo_make_call and plivo_lookup_number, and each one can be enabled or
disabled separately.
3. Add credentials
In ~/.hermes/.env:
PLIVO_AUTH_ID=MAxxxxxxxxxxxxxxxxxx
PLIVO_AUTH_TOKEN=xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
PLIVO_PHONE_NUMBER=+14155550100
The tools register whether or not credentials are present and refuse to dispatch without them, leaving the plugin safe to install before the account is configured.
Configuration
| Variable | Required | Purpose |
|---|---|---|
PLIVO_AUTH_ID |
yes | Plivo account auth ID |
PLIVO_AUTH_TOKEN |
yes | Plivo account auth token |
PLIVO_PHONE_NUMBER |
yes | Default sender and caller ID, E.164 |
PLIVO_ANSWER_URL |
no | Default document returning call-control XML for make_call. Plivo's demo document answers when absent |
Credentials are read through the Hermes profile-scoped secret store, with an environment fallback, matching the bundled plugins.
What an outbound call says
make_call needs a Plivo answer URL, a fetchable document returning call-control XML. The
Plivo API accepts no inline text and rejects a data: URI.
With none configured, calls reach Plivo's demo document, which speaks a single fixed sentence. The tool result carries a warning whenever the demo document answers.
| To control what is said | Result |
|---|---|
| Install hermes-plivo-phone-gateway | The agent answers the call and holds a real-time conversation. The gateway names the numbers it will call in PLIVO_VOICE_ALLOWED_DESTINATIONS, and make_call refuses a number it does not list rather than placing a call the gateway would drop on answer |
Pass answer_url and answer_method |
Whatever the document returns, for example <Response><Speak>Deploy finished</Speak></Response> |
Set PLIVO_ANSWER_URL in ~/.hermes/.env |
The same, applied to every call |
Security
- Credentials are read from the Hermes secret store or the environment, never from a file the plugin ships
- Phone numbers in tool results are masked to their last four digits
- Failures return structured JSON rather than raising, and a failed send leaves the agent turn intact
Troubleshooting
| Symptom | Cause |
|---|---|
Agent has no send_sms, make_call or lookup_number |
The plugin is not enabled as plivo-tools |
| Only some of the three appear | Each tool is its own toolset and can be disabled separately |
| A call speaks one fixed sentence | No answer URL is configured, and Plivo's demo document answered |
make_call refuses a number before contacting Plivo |
The phone gateway is answering and PLIVO_VOICE_ALLOWED_DESTINATIONS does not list it. Empty refuses every outbound call |
| A tool reports missing credentials | PLIVO_AUTH_ID or PLIVO_AUTH_TOKEN is unset in ~/.hermes/.env |
Tests
python -m unittest discover -s tests
ruff check .
The suite covers number normalisation, credential handling, schema shapes and the handler contract with the REST layer stubbed. It needs no Hermes install and touches no network.
Limitations
make_callon its own plays a fixed document. A spoken conversation needshermes-plivo-phone-gateway- Inbound SMS is a separate plugin,
hermes-plivo-sms
License
MIT
1 maintainer
Metadata
1 maintainer
Release files for hermes-plivo-tools 0.1.3
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| hermes_plivo_tools-0.1.3.tar.gz | 20.4 kB | With provenance | Details for hermes_plivo_tools-0.1.3.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| hermes_plivo_tools-0.1.3-py3-none-any.whl | Python 3 | none | any | Details for hermes_plivo_tools-0.1.3-py3-none-any.whl |
Total release size: 34.9 kB
Release files / hermes_plivo_tools-0.1.3.tar.gz
| Download URL | hermes_plivo_tools-0.1.3.tar.gz |
|---|---|
| Size | 20.4 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
426e71b73346685e4ba45ef3b9ee2ab4a2089645d58a3baf90404981d1cfa5ef
|
|
BLAKE2b-256 checksum How to use checksums |
87036ec3708b90b694bff94be4fd8e66a9f0474beb51c867e6f9c8d50556d64f
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.14
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Sep 7, 2026.
Transparency logRelease files / hermes_plivo_tools-0.1.3-py3-none-any.whl
| Download URL | hermes_plivo_tools-0.1.3-py3-none-any.whl |
|---|---|
| Size | 14.5 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
a44d656292066bed7864d5c5726d80cd64f73fbbc340e04bb382610b11a6c206
|
|
BLAKE2b-256 checksum How to use checksums |
d6c8cdb8e4d0687c178bc88ca07c1dc7c54c073cde2ed4369c9983f8ee142252
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.14
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Sep 7, 2026.
Transparency logSecurity for hermes-plivo-tools 0.1.3
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
Full provenance
All 2 files in this release have been uploaded with provenance metadata.
Attestation for hermes_plivo_tools-0.1.3.tar.gz
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Sep 7, 2026.
Transparency logA note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.
