External Actions

1. give the agent context to inform the rest of the phone call
2. change the agent’s behavior based on the pulled information
3. run functions/tasks outside the call

​

How it Works

​

Configuring an External Action with ExecuteExternalActionVocodeActionConfig

​

Overview

• processing_mode: We currently only support muted, which makes the agent silent while processing the request.
• name: the name of the external action — this has no impact on the functionality of action itself.
• description: Used by the Function Calling API to determine when to make the External Action call itself. See the description field section below for more info!
• url: The API request is sent to this URL in the format defined below in Responding to External Action API Requests
• input_schema: A JSON Schema for the payload to send to the External API. See the input_schema field section below for more info!
• speak_on_send: if True, then the underlying LLM will generate a message to be spoken as the API request is being sent.
• speak_on_receive: if True, then the agent will speak once it receives a result from the API Response. If the response does not contain an agent_message (see Response Formatting), the agent will query the LLM for the message to speak.
• signature_secret: a base64 encoded string to enable request validation, see the Signature Validation section below for more info

​

input_schema Field

{
  "type": "object",
  "properties": {
    "length": {
      "type": "string",
      "enum": ["30m", "1hr"]
    },
    "time": {
      "type": "string",
      "pattern": "^d{2}:d0[ap]m$"
    }
  }
}

• Two fields
  • length (string): either “30m” or “1hr”
  • time (string): a regex pattern defining a time ending in a zero with am/pm on the end ie: 10:30am

​

description Field

​

Responding to External Action API Requests

POST url HTTP/1.1
Accept: application/json
Content-Type: application/json
x-vocode-signature: <encoded_signature>

{
  "payload": {
    "length": "30m",
    "time": "10:30am"
  }
}

​

Signature Validation

import os
import base64

signature_secret = base64.b64encode(os.urandom(32)).decode()

import base64
import hashlib
import hmac

async def test_requester_encodes_signature(
  request_signature_value: str, signature_secret: str, payload: dict
):
    """
    Asynchronous function to check if the request signature is encoded correctly.

    Args:
        request_signature_value (str): The request signature to be decoded.
        signature_secret (str): The secret for the action (make sure this is stored securely).
        payload (dict): The payload to be used for digest calculation.

    Returns:
        None
    """
    signature_secret_as_bytes = base64.b64decode(signature_secret)
    decoded_digest = base64.b64decode(request_signature_value)
    calculated_digest = hmac.new(signature_secret_as_bytes, json.dumps(payload).encode(), hashlib.sha256).digest()
    assert hmac.compare_digest(decoded_digest, calculated_digest) is True

​

Response Formatting

Response {
  result: Any
  agent_message: Optional[str] = None
}

• result is a payload containing the result of the action on the user’s side, and can be in any format
• agent_message optionally contains a message that will be synthesized into audio and sent back to the phone call. Note this means the LLM will not be queried to send a message (see Configuring the External Action above for more info)

{
  "result": {
    "success": true
  },
  "agent_message": "I've set up a calendar appointment at 10:30am tomorrow for 30 minutes"
}

​

EA Local Response Server Example:

import asyncio
import base64
import hashlib
import hmac
import json
import time

from fastapi import FastAPI, HTTPException, Request, status
from pydantic import BaseModel

app = FastAPI()

action_secret = ""


def is_signature_valid(request: Request, json_payload: dict):
    signature_secret_as_bytes = base64.b64decode(action_secret)
    decoded_digest = base64.b64decode(request.headers.get("x-vocode-signature"))
    calculated_digest = hmac.new(
        signature_secret_as_bytes, json.dumps(json_payload).encode(), hashlib.sha256
    ).digest()
    return hmac.compare_digest(decoded_digest, calculated_digest)


@app.post("/external_action")
def update_item(request: Request):
    json_payload = asyncio.run(request.json())
    print(json_payload)
    if not is_signature_valid(request, json_payload):
        raise HTTPException(
            status_code=status.HTTP_401_UNAUTHORIZED,
            detail="Signature verification failed for payload",
        )
    time.sleep(3)
    return {
        "result": {"success": True},
    }

​

Meeting Assistant Example

import json
import base64
import os

from vocode.streaming.action.execute_external_action import (
    ExecuteExternalAction,
    ExecuteExternalActionVocodeActionConfig,
)

ACTION_INPUT_SCHEMA = {
    "type": "object",
    "properties": {
        "length": {
            "type": "string",
            "enum": ["30m", "1hr"],
        },
        "time": {
            "type": "string",
            "pattern": "^\d{2}:\d0[ap]m$",
        },
    },
}

action_config = ExecuteExternalActionVocodeActionConfig(
    name = "Meeting_Booking_Assistant",
    description = "Book a meeting for a 30 minute or 1 hour call.",
    url = "http://example.com/booking",
    speak_on_send = True,
    speak_on_receive = True,
    input_schema = json.dumps(ACTION_INPUT_SCHEMA),
    signature_secret = base64.b64encode(os.urandom(32)).decode(),
)