AI Voice Agent Tools

AI Voice Agent tool configuration lets the runtime end a call or transfer a caller to an approved destination. The public agent API exposes this configuration on the agent itself. The internal realtime tool execution endpoint is not a customer API; customers configure allowed behavior through POST /v1/ai/agents and PATCH /v1/ai/agents/:id.

Supported Tools

Tool	Purpose	Customer configuration
hangup_call	End the current call when the conversation is complete.	hangup_tool_description
transfer_call	Transfer the current call to an approved destination.	transfer_tool_description and transfer_destinations

Configure Transfer Destinations

curl -sS https://api.minivoice.eu/v1/ai/agents \
  -X POST \
  -H 'Authorization: Bearer $MINIVOICE_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
    "name": "Front Desk Receptionist",
    "greeting": "Thanks for calling Maple Clinic. How can I help?",
    "instructions": "Answer simple scheduling questions. If the caller asks for billing, urgent care, or a human receptionist, transfer to the correct approved destination.",
    "hangup_tool_description": "Use this when the caller has no more questions and the conversation is complete.",
    "transfer_tool_description": "Use this only when the caller asks for billing, urgent care, or a human receptionist.",
    "transfer_destinations": [
      {
        "id": "front_desk",
        "label": "Front Desk",
        "type": "phone",
        "value": "+15551230010"
      },
      {
        "id": "billing",
        "label": "Billing",
        "type": "sip",
        "value": "sip:billing@example.com"
      }
    ]
  }'

Response Excerpt

{
  "data": {
    "id": "agent_20260707T120000.000000000",
    "tool_config": {
      "type": "",
      "target": "",
      "message": "",
      "hangup_tool_description": "Use this when the caller has no more questions and the conversation is complete.",
      "transfer_tool_description": "Use this only when the caller asks for billing, urgent care, or a human receptionist.",
      "transfer_destinations": [
        {
          "id": "front_desk",
          "label": "Front Desk",
          "type": "phone",
          "value": "+15551230010"
        },
        {
          "id": "billing",
          "label": "Billing",
          "type": "sip",
          "value": "sip:billing@example.com"
        }
      ]
    }
  }
}

Parameters

Field	Type	Required	Description
hangup_tool_description	string	no	Instruction text describing when the agent should end the call. Must be at most 1000 characters.
transfer_tool_description	string	no	Instruction text describing when the agent should transfer. Must be at most 1000 characters.
transfer_destinations	array	no	Up to 10 approved destinations.
transfer_destinations[].id	string	yes	Unique destination ID. Runtime matching is case-insensitive.
transfer_destinations[].label	string	no	Human-readable name. Runtime matching can use this label.
transfer_destinations[].type	string	yes	Must be phone or sip.
transfer_destinations[].value	string	yes	E.164 phone number or SIP URI.

Transfer destination values must be valid E.164 numbers or SIP URIs. E.164 values must start with + and contain digits only after the plus. SIP URI query strings, fragments, and whitespace are rejected.

Execution Flow

1. The customer configures allowed transfer destinations on the agent.
2. During a live realtime session, the AI runtime can request hangup_call or transfer_call.
3. For transfer, MiniVoice checks that the requested destination matches an approved destination by ID, label, or value.
4. If allowed and the call is active, MiniVoice completes the AI session with completion_reason set to transferred and attempts the call transfer.
5. If hangup is requested, MiniVoice completes the AI session with completion_reason set to hangup and ends the call.

Common Failure

{
  "error": {
    "code": "invalid_ai_agent",
    "message": "transfer_destinations.type must be phone or sip"
  }
}

At runtime, an unapproved transfer request is rejected by MiniVoice and does not transfer the caller.

Testing

Create one destination for your own test phone number and one invalid destination in a negative test. The invalid destination should fail during agent create or update. For the positive test, call the agent and ask for the exact transfer label. After the call, fetch the AI session and confirm completion_reason is transferred and transfer_target is present.