Let a voice AI agent call an API without your server

AI Agentsserverless API integration for voice AI

SignalWire makes the API call, so no service of yours is in the tool path.

datamapserverless

The claim

A tool that reaches a third-party API with no service of yours in the tool path. The HTTP request, the response template and the failure path are fields in the document SignalWire runs, so there is no handler and no callback URL.

Why it holds

A normal tool gives the platform a URL to call back to. A DataMap tool gives it the request to make instead. The document itself still has to be served from somewhere. The Python surface below hosts it, and the SWML surface can be pasted into a hosted SWML Script so nothing of yours runs at all.

How it works

DataMap builds a function definition whose body is a data_map rather than a url. ${args.x} is substituted into the request before it is sent; ${response.x} reads the parsed JSON body on the way back.

DataMap("look_up_book")
    .parameter("isbn", "string", "The 10 or 13 digit ISBN.", required=True)
    .webhook("GET", "https://openlibrary.org/isbn/${args.isbn}.json")
    .output(FunctionResult("ISBN ${args.isbn} is ${response.title}."))
    .error_keys(["error"])
    .fallback_output(FunctionResult("I could not reach the book catalogue."))

Where each result lands is the part worth reading twice. .output() attaches to the webhook directly above it, so a chain of webhooks each carry their own. Only .fallback_output() sits at the top of the data_map, and it is spoken when every webhook has failed. .error_keys() names the JSON keys whose presence means failure even though the request returned 200.

Limitations

Templating is the only transform available. There is no place to put a conditional or a unit conversion, so an API whose response needs reshaping wants a normal tool with a handler (give-an-agent-a-tool).

Anything in headers ships inside the document SignalWire serves. For an API that needs a secret, weigh that before choosing a DataMap.

What to change first

Point the webhook at a URL that returns 404 and call the agent. The fallback is what the caller hears, which is the difference between a degraded answer and silence.

python/app.py

"""Call an API without a backend.

A DataMap tool is executed by SignalWire, not by you. The HTTP request, the
response templating and the error handling all travel inside the SWML document,
so there is no webhook of yours for the platform to call back to.

This one looks a book up by ISBN against Open Library, which needs no API key,
so the recipe runs as written.

Written against signalwire-sdk 3.0.1.
"""
import os

from dotenv import load_dotenv
from signalwire import AgentBase, DataMap, FunctionResult

# the SDK does not read .env for you
load_dotenv()


def book_lookup():
    """A tool with no handler. The platform performs the call."""
    return (
        DataMap("look_up_book")
        .purpose(
            "Look up a book by its ISBN to confirm the title before ordering. "
            "Use this whenever the caller reads out an ISBN."
        )
        .parameter(
            "isbn", "string",
            "The 10 or 13 digit ISBN, digits only, no dashes.",
            required=True,
        )
        # ${args.x} is substituted into the URL before the platform sends it
        .webhook("GET", "https://openlibrary.org/isbn/${args.isbn}.json")
        # ${response.x} reads the parsed JSON body. This output belongs to the
        # webhook above it.
        .output(FunctionResult(
            "ISBN ${args.isbn} is ${response.title}, published "
            "${response.publish_date}."
        ))
        # a body carrying this key means the lookup failed
        .error_keys(["error"])
        # top-level: spoken only when every webhook above has failed
        .fallback_output(FunctionResult(
            "I could not reach the book catalogue. Ask the caller to read the "
            "ISBN again, or offer to take the title instead."
        ))
    )


class CatalogueAgent(AgentBase):
    def __init__(self):
        super().__init__(name="catalogue", route="/catalogue")
        self.prompt_add_section(
            "Role",
            "You take book orders for an independent bookshop. Confirm the "
            "title with the lookup tool before you add anything to an order.",
        )
        # a DataMap is registered as a raw function definition
        self.register_swaig_function(book_lookup().to_swaig_function())


agent = CatalogueAgent()

if __name__ == "__main__":
    agent.serve(host="0.0.0.0", port=int(os.getenv("PORT", "3000")))

# Call an API without a backend.
#
# The whole tool is data. The request, the response template and the failure
# path all sit inside the document SignalWire runs, so there is no service of
# yours in the path and nothing to deploy.
version: "1.0.0"
sections:
  main:
    - answer: {}
    - ai:
        prompt:
          text: >
            You take book orders for an independent bookshop. Confirm the title
            with the lookup tool before you add anything to an order.
        SWAIG:
          functions:
            - function: look_up_book
              description: >
                Look up a book by its ISBN to confirm the title before
                ordering. Use this whenever the caller reads out an ISBN.
              parameters:
                type: object
                properties:
                  isbn:
                    type: string
                    description: The 10 or 13 digit ISBN, digits only, no dashes.
                required:
                  - isbn
              data_map:
                webhooks:
                  # ${args.isbn} is substituted before SignalWire sends this
                  - url: "https://openlibrary.org/isbn/${args.isbn}.json"
                    method: GET
                    # this output belongs to the webhook above it
                    output:
                      response: >-
                        ISBN ${args.isbn} is ${response.title}, published
                        ${response.publish_date}.
                    # a body carrying this key means the lookup failed
                    error_keys:
                      - error
                # top level: spoken only when every webhook above has failed
                output:
                  response: >-
                    I could not reach the book catalogue. Ask the caller to read
                    the ISBN again, or offer to take the title instead.

Run it

cd python
pip install -r requirements.txt
cp ../.env.example .env          # set SWML_BASIC_AUTH_PASSWORD
python app.py

Point a phone number’s SWML webhook at https://<user>:<password>@<your-host>/catalogue/, using the credentials you set. Without them the request is refused. Open Library needs no key, so it works as written.

Verify it

No network, no account:

python verify.py          # from the recipe folder, not python/

It renders the SWML and asserts:

the function carries a data_map and no url of ours
the request is GET with ${args.isbn} templated into the path
the webhook’s own output holds the ${response.title} template
the top-level output is the fallback, with no ${response.*} in it
the SDK refuses to run the tool locally, naming SignalWire as the executor
the hand-written SWML surface is the same artifact, not a paraphrase

Report an issue