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
Download files
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.
Source Distribution
Built Distribution
Filter files by name, interpreter, ABI, and platform.
If you're not sure about the file name format, learn more about wheel file names.
Copy a direct link to the current filters
File details
Details for the file hermes_plivo_tools-0.1.3.tar.gz.
File metadata
- Download URL: hermes_plivo_tools-0.1.3.tar.gz
- Upload date:
- Size: 20.4 kB
- Tags: Source
- Uploaded using Trusted Publishing? Yes
- Uploaded via:
twine/7.0.0 CPython/3.13.14
File hashes
| Algorithm | Hash digest | |
|---|---|---|
| SHA256 |
426e71b73346685e4ba45ef3b9ee2ab4a2089645d58a3baf90404981d1cfa5ef
|
|
| MD5 |
2eb8aeb01fcb3dc293ee55496511d8e4
|
|
| BLAKE2b-256 |
87036ec3708b90b694bff94be4fd8e66a9f0474beb51c867e6f9c8d50556d64f
|
Provenance
The following attestation bundles were made for hermes_plivo_tools-0.1.3.tar.gz:
Publisher:
publish.yml on plivo-dev/hermes-plivo-tools
-
Statement:
-
Statement type:
https://in-toto.io/Statement/v1 -
Predicate type:
https://docs.pypi.org/attestations/publish/v1 -
Subject name:
hermes_plivo_tools-0.1.3.tar.gz -
Subject digest:
426e71b73346685e4ba45ef3b9ee2ab4a2089645d58a3baf90404981d1cfa5ef - Sigstore transparency entry: 2747947581
- Sigstore integration time:
-
Permalink:
plivo-dev/hermes-plivo-tools@c5314f731e467984dda6001ef15b3b5b22a1ce30 -
Branch / Tag:
refs/tags/v0.1.3 - Owner: https://github.com/plivo-dev
-
Access:
public
-
Token Issuer:
https://token.actions.githubusercontent.com -
Runner Environment:
github-hosted -
Publication workflow:
publish.yml@c5314f731e467984dda6001ef15b3b5b22a1ce30 -
Trigger Event:
push
-
Statement type:
File details
Details for the file hermes_plivo_tools-0.1.3-py3-none-any.whl.
File metadata
- Download URL: hermes_plivo_tools-0.1.3-py3-none-any.whl
- Upload date:
- Size: 14.5 kB
- Tags: Python 3
- Uploaded using Trusted Publishing? Yes
- Uploaded via:
twine/7.0.0 CPython/3.13.14
File hashes
| Algorithm | Hash digest | |
|---|---|---|
| SHA256 |
a44d656292066bed7864d5c5726d80cd64f73fbbc340e04bb382610b11a6c206
|
|
| MD5 |
7c091ae12e1d752bd55712317ff1eb6e
|
|
| BLAKE2b-256 |
d6c8cdb8e4d0687c178bc88ca07c1dc7c54c073cde2ed4369c9983f8ee142252
|
Provenance
The following attestation bundles were made for hermes_plivo_tools-0.1.3-py3-none-any.whl:
Publisher:
publish.yml on plivo-dev/hermes-plivo-tools
-
Statement:
-
Statement type:
https://in-toto.io/Statement/v1 -
Predicate type:
https://docs.pypi.org/attestations/publish/v1 -
Subject name:
hermes_plivo_tools-0.1.3-py3-none-any.whl -
Subject digest:
a44d656292066bed7864d5c5726d80cd64f73fbbc340e04bb382610b11a6c206 - Sigstore transparency entry: 2747947588
- Sigstore integration time:
-
Permalink:
plivo-dev/hermes-plivo-tools@c5314f731e467984dda6001ef15b3b5b22a1ce30 -
Branch / Tag:
refs/tags/v0.1.3 - Owner: https://github.com/plivo-dev
-
Access:
public
-
Token Issuer:
https://token.actions.githubusercontent.com -
Runner Environment:
github-hosted -
Publication workflow:
publish.yml@c5314f731e467984dda6001ef15b3b5b22a1ce30 -
Trigger Event:
push
-
Statement type:
