Skip to content

feat(tools): add phone_call tool for outbound AI voice calls#847

Open
mormio wants to merge 1 commit intomainfrom
feat/phone-call-tool
Open

feat(tools): add phone_call tool for outbound AI voice calls#847
mormio wants to merge 1 commit intomainfrom
feat/phone-call-tool

Conversation

@mormio
Copy link

@mormio mormio commented Mar 10, 2026

## What does this PR do?

Add `phone_call` and `phone_call_result` tools for making outbound
phone calls via AI voice agents. Enables the agent to schedule
appointments, make reservations, and deliver messages by phone on
the user's behalf.

Two providers supported (user chooses during first-time setup):

- **Bland.ai** (default): all-in-one, one API key, built-in voices
- **Vapi**: flexible platform — plug in any voice provider
  (ElevenLabs, Deepgram, PlayHT) and telephony (Twilio, Vonage,
  Telnyx). Better voice quality, more setup.

Provider selected via config.yaml or env vars. Tools only appear
when at least one provider is configured (check_fn gates them).

## Related Issue

No existing issue — this is a new capability.

## Type of Change

- [x] ✨ New feature (non-breaking change that adds functionality)

## Changes Made

- `tools/phone_tool.py`: new tool module — `phone_call` (initiate
  outbound call) and `phone_call_result` (poll for transcript/status)
- `toolsets.py`: add "phone" toolset definition + add both tools
  to `_HERMES_CORE_TOOLS`
- `model_tools.py`: add `tools.phone_tool` to `_discover_tools()` list

## How to Test

**Bland.ai (quick):**
1. Sign up at https://app.bland.ai (free, ~$2 trial credit)
2. Set `BLAND_API_KEY` env var
3. Run: `hermes -q "Call +15551234567 and ask what time they close"`
4. Agent should confirm before dialing, make the call, then report transcript

**Vapi (better voice quality):**
1. Sign up at https://dashboard.vapi.ai + https://twilio.com
2. Buy a Twilio number, import into Vapi
3. Set `VAPI_API_KEY` and `VAPI_PHONE_NUMBER_ID`
4. Set `phone.provider: vapi` in config.yaml
5. Same test as above

**Without any provider configured:**
- Tools should not appear in the agent's tool list (check_fn returns False)

## Checklist

### Code
- [x] I've read the Contributing Guide
- [x] My commit messages follow Conventional Commits
- [x] I searched for existing PRs to make sure this isn't a duplicate
- [x] My PR contains only changes related to this feature
- [x] I've run `pytest tests/ -q` and all tests pass
      (same 8 pre-existing collection errors on main and this branch)
- [ ] I've added tests for my changes — not yet, would appreciate
      guidance on mocking external API calls in the test suite
- [x] I've tested on my platform: Ubuntu (Linux)

### Documentation & Housekeeping
- [ ] I've updated relevant documentation — N/A (tool is
      self-documenting via schema descriptions)
- [ ] I've updated cli-config.yaml.example — should add phone
      section, happy to do in a follow-up
- [ ] I've updated CONTRIBUTING.md or AGENTS.md — N/A
- [x] I've considered cross-platform impact — uses only `requests`
      library, no OS-specific code
- [x] I've updated tool descriptions/schemas

## Screenshots / Logs

Tested with real calls via both providers:

Bland.ai call

phone_call(<phone_number_hidden>, "Deliver a message from Morgane")
→ call_id: b1c18c55-...
→ Transcript: AI delivered message, user responded

Vapi + ElevenLabs + Twilio call

phone_call(<phone_number_hidden>, "Test voice quality")
→ call_id: 019cd87a-...
→ Transcript: User confirmed voice quality improvement

Add phone_call and phone_call_result tools for making outbound phone
calls via AI voice agents. Supports two providers:

- Bland.ai (default): simple all-in-one, one API key, built-in voices
- Vapi: flexible platform with ElevenLabs/Deepgram/PlayHT voices and
  Twilio/Vonage/Telnyx telephony. Better voice quality, more setup.

The tool handles the API plumbing (initiating calls, polling for
transcripts/recordings). Provider is selected via config.yaml or
env vars (BLAND_API_KEY or VAPI_API_KEY + VAPI_PHONE_NUMBER_ID).

Tools only appear when at least one provider is configured
(check_fn returns False otherwise).

Files changed:
- tools/phone_tool.py: new tool module (phone_call, phone_call_result)
- toolsets.py: add 'phone' toolset + tools to _HERMES_CORE_TOOLS
- model_tools.py: add tools.phone_tool to discovery list
@mormio mormio force-pushed the feat/phone-call-tool branch from 48ea4bb to 1cbadb7 Compare March 11, 2026 14:26
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant