Create a hosted voice AI agent with one REST call

AI Agentshosted voice AI agent (no server)

Turn the agent definition you would serve yourself into a resource SignalWire hosts, with one POST, then put a phone number on it with one more.

resthosted

The claim

Every agent recipe here serves a document from your host. This one hands the same definition to the platform instead. AgentBase renders the ai verb as it would for a call. Its prompt, params and post_prompt become the body of a create request, and the response is a resource with an id.

Why it holds

The vendored REST spec, tools/openapi/rest.json, is the authority.

POST /api/fabric/resources/ai_agents requires name and prompt. The spec describes prompt, params and post_prompt by pointing at the SWML ai reference, so the objects the SDK renders are the objects the endpoint wants.
POST /api/fabric/resources/{id}/phone_routes requires phone_route_id and a handler, whose enum is calling or messaging.
The number’s id comes from GET /api/relay/rest/phone_numbers with filter_number, which is a contains match, so the recipe compares the number exactly and refuses one the project does not hold.

A hosted agent has no tool webhooks of yours to call, because there is no host of yours. This one has none. An agent with tools stays a served agent, or uses serverless tools. That pattern is [Let the agent call an API with no server of yours](../call-an-api-without-a-backend/).

How it works

class FrontDesk(AgentBase):
    def __init__(self):
        super().__init__(name=NAME, route="/front-desk")
        self.prompt_add_section("Role", "You answer the phone for Ridgeline Cycles...")
        self.set_post_prompt("Summarise the call in one sentence.")
        self.set_params({"end_of_speech_timeout": 700})

def definition():
    doc = json.loads(FrontDesk()._render_swml())
    (ai,) = [step["ai"] for step in doc["sections"]["main"] if "ai" in step]
    return {"name": NAME, "prompt": ai["prompt"], "params": ai["params"],
            "post_prompt": ai["post_prompt"]}

client.fabric.ai_agents.create(**definition())

What the platform receives, from the Python SDK:

{"name": "ridgeline-front-desk",
 "prompt": {"pom": [{"title": "Role", "body": "You answer the phone for ..."},
                    {"title": "Hours", "body": "Open Monday to Friday, ..."},
                    {"title": "Limits", "body": "You cannot book repairs. ..."}]},
 "params": {"end_of_speech_timeout": 700},
 "post_prompt": {"text": "Summarise the call in one sentence."}}

The two SDKs render the same sections in different forms. Python 3.0.1 emits a pom list; @signalwire/sdk 2.0.5 emits them as markdown text with one ## heading per section. The ai.prompt schema allows both, and the verifier validates each as SWML before trusting it as a request body.

The second call is the one every no-server recipe shares: client.fabric.resources.assign_phone_route(agent_id, phone_route_id=..., handler="calling").

Limitations

The verifier proves the requests and the documents, not the call. What the hosted agent says when the number rings is live behaviour.

A hosted agent cannot call tool webhooks on a host you do not have. Keep tools serverless, or keep the agent served.

What to change first

Add self.define_tool(...) with a webhook handler to FrontDesk and run the verifier. The rendered ai now carries a SWAIG object pointing at your host, and definition() drops it. That is the point: the fields this recipe posts are the ones a hosted agent can honour.

Where this sits

Before this

Route a call to an AI agent Build an IVR without a server

Run a voice AI agent from one YAML file Buy a number and point it at your app Configure a voice AI agent per request for many tenants

python/app.py

"""Create a hosted voice AI agent with one REST call.

The agent you would serve from your own host is the agent SignalWire can host
for you. `AgentBase` renders the `ai` verb; its `prompt`, `params` and
`post_prompt` are exactly the fields `POST /api/fabric/resources/ai_agents`
takes, and the spec points at the SWML `ai` reference for each. One more POST
puts a phone number on the resource. No server of yours stays running.

Written against signalwire-sdk 3.0.1 (AgentBase, RestClient.fabric).

    python app.py create                  # the hosted agent, printed with its id
    python app.py point <agent_id> +15551230000
"""
import json
import sys

from dotenv import load_dotenv
from signalwire import AgentBase
from signalwire.rest import RestClient

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

# reads SIGNALWIRE_PROJECT_ID / SIGNALWIRE_API_TOKEN / SIGNALWIRE_SPACE from the env
client = RestClient()

NAME = "ridgeline-front-desk"


class FrontDesk(AgentBase):
    """The same definition you would run yourself, rendered rather than served."""

    def __init__(self):
        super().__init__(name=NAME, route="/front-desk")
        self.prompt_add_section("Role", "You answer the phone for Ridgeline Cycles, "
                                        "a bike shop. Be brief and warm.")
        self.prompt_add_section("Hours", "Open Monday to Friday, nine to five, "
                                         "Eastern time. Closed weekends.")
        self.prompt_add_section("Limits", "You cannot book repairs. Offer the shop "
                                          "number for that and end the call kindly.")
        self.set_post_prompt("Summarise the call in one sentence.")
        self.set_params({"end_of_speech_timeout": 700})


def definition(agent=None):
    """The `ai` verb the agent renders, which is what the hosted resource needs."""
    agent = agent or FrontDesk()
    doc = agent._render_swml()
    if isinstance(doc, str):  # 3.0.1 renders the document as a JSON string
        doc = json.loads(doc)
    (ai,) = [step["ai"] for step in doc["sections"]["main"] if "ai" in step]
    body = {"name": NAME, "prompt": ai["prompt"]}
    for key in ("params", "post_prompt"):
        if key in ai:
            body[key] = ai[key]
    return body


def create():
    """One POST. The response carries the resource id a number can point at."""
    return client.fabric.ai_agents.create(**definition())


def number_id(e164):
    """`filter_number` is a contains match, so compare the number exactly."""
    for item in client.phone_numbers.list(filter_number=e164).get("data", []):
        if item.get("number") == e164:
            return item["id"]
    raise LookupError(f"{e164} is not a number in this project")


def point_number(resource_id, e164):
    """Route inbound calls on the number to the hosted agent."""
    return client.fabric.resources.assign_phone_route(
        resource_id, phone_route_id=number_id(e164), handler="calling")


if __name__ == "__main__":
    args = sys.argv[1:]
    if args[:1] == ["create"]:
        made = create()
        print(made.get("id"), made.get("display_name"))
    elif len(args) == 3 and args[0] == "point":
        print(point_number(args[1], args[2]))
    else:
        print(__doc__)

/**
 * Create a hosted voice AI agent with one REST call.
 *
 * The agent you would serve from your own host is the agent SignalWire can
 * host for you. `AgentBase` renders the `ai` verb; its `prompt`, `params` and
 * `post_prompt` are exactly the fields `POST /api/fabric/resources/ai_agents`
 * takes, and the spec points at the SWML `ai` reference for each. One more
 * POST puts a phone number on the resource. No server of yours stays running.
 *
 * Written against @signalwire/sdk 2.0.5 (AgentBase, RestClient.fabric).
 *
 *     npm start create
 *     npm start point <agent_id> +15551230000
 */
import "dotenv/config";
import { AgentBase, RestClient } from "@signalwire/sdk";

// reads SIGNALWIRE_PROJECT_ID / SIGNALWIRE_API_TOKEN / SIGNALWIRE_SPACE
export const client = new RestClient();

export const NAME = "ridgeline-front-desk";

/** The same definition you would run yourself, rendered rather than served. */
export class FrontDesk extends AgentBase {
  constructor() {
    super({ name: NAME, route: "/front-desk" });
    this.promptAddSection("Role", { body: "You answer the phone for Ridgeline Cycles, "
                                          + "a bike shop. Be brief and warm." });
    this.promptAddSection("Hours", { body: "Open Monday to Friday, nine to five, "
                                           + "Eastern time. Closed weekends." });
    this.promptAddSection("Limits", {
      body: "You cannot book repairs. Offer the shop number for that "
          + "and end the call kindly.",
    });
    this.setPostPrompt("Summarise the call in one sentence.");
    this.setParams({ end_of_speech_timeout: 700 });
  }
}

type Step = Record<string, Record<string, unknown>>;

/** The `ai` verb the agent renders, which is what the hosted resource needs. */
export async function definition(agent: AgentBase = new FrontDesk()) {
  const doc = JSON.parse(await agent.renderSwml()) as { sections: { main: Step[] } };
  const ai = doc.sections.main.find((step) => "ai" in step)!["ai"];
  const body: Record<string, unknown> = { name: NAME, prompt: ai["prompt"] };
  for (const key of ["params", "post_prompt"]) {
    if (key in ai) body[key] = ai[key];
  }
  return body;
}

/** One POST. The response carries the resource id a number can point at. */
export async function create() {
  return client.fabric.aiAgents.create(await definition());
}

/** `filter_number` is a contains match, so compare the number exactly. */
export async function numberId(e164: string): Promise<string> {
  const page = await client.phoneNumbers.list({ filter_number: e164 });
  for (const item of (page["data"] ?? []) as { id: string; number: string }[]) {
    if (item.number === e164) return item.id;
  }
  throw new Error(`${e164} is not a number in this project`);
}

/** Route inbound calls on the number to the hosted agent. */
export async function pointNumber(resourceId: string, e164: string) {
  return client.fabric.resources.assignPhoneRoute(resourceId, {
    phone_route_id: await numberId(e164), handler: "calling",
  });
}

if (process.argv[1] && import.meta.url.endsWith(process.argv[1].replace(/\\/g, "/"))) {
  const [cmd, id, number] = process.argv.slice(2);
  if (cmd === "create") {
    const made = await create();
    console.log(made["id"], made["display_name"]);
  } else if (cmd === "point" && id && number) {
    console.log(await pointNumber(id, number));
  } else {
    console.log("usage: npm start create | npm start point <agent_id> <e164>");
  }
}

Run it

cd python
pip install -r requirements.txt
cp ../.env.example .env          # project id, API token, space
python app.py create             # prints the resource id
python app.py point <agent_id> +15551230000

The TypeScript surface renders its own agent the same way, on Node 20.18.1 or newer:

cd typescript
npm ci
cp ../.env.example .env
npm start create

The number has to be one the project already holds. Buying it is [Buy a number and point it at your app](../buy-a-number-and-point-it-at-your-app/). After the second call, dialling the number reaches the hosted agent, and there is nothing to keep running.

Verify it

No network, no account.

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

The verifier renders the agent, swaps the SDK’s HTTP layer for a recorder, and asserts the following.

the request body is the rendered agent: three sections in order, the post prompt, and the params
POST /api/fabric/resources/ai_agents requires name and prompt, every key sent is documented, and the spec describes the three objects by pointing at the SWML reference
the same prompt, params and post_prompt, wrapped back into an ai verb, validate against the bundled SWML schema
the number lookup sends filter_number, and with two numbers in the answer the recipe picks the exact match
the phone route body is exactly phone_route_id plus handler: calling, and the handler enum is calling and messaging
a number the project does not hold raises after the lookup and before any route is posted
the TypeScript surface renders the same three sections as prompt text, the same params and post prompt, sends the same three requests, and refuses the same number

Report an issue