Run a Bedrock voice agent

AI AgentsAmazon Bedrock voice agent

Run the same voice AI agent and tool handler through Amazon Bedrock by changing the agent class and Bedrock settings.

The claim

You swap the base class and the SDK’s agents/bedrock.py renders the base document, then rebuilds the verb as amazon_bedrock. The prompt, SWAIG, params, global_data and post-prompt settings are copied over. Inside the prompt it adds voice_id, temperature and top_p; its comment says that in Bedrock the voice configuration is part of the prompt object. It also drops three text-model prompt settings if you set them. The bundled schema documents the verb as AmazonBedrock. The SWAIG.functions list renders the same on both, and because one configure() registers the tool on each agent, the same handler runs on both.

How it works

def configure(agent):
    agent.prompt_add_section("Role", "You are the parts desk at Ridgeline Cycles. ...")
    agent.define_tool(name="check_stock",
                      description="Check whether a bike part is in stock before promising it.",
                      parameters=PARAMETERS, handler=check_stock)
    return agent

def build(kind="bedrock"):
    if kind == "ai":
        return configure(AgentBase(name="parts", route="/parts"))
    return configure(BedrockAgent(name="parts", route="/parts", voice_id="matthew"))

What the platform receives, on each base class:

{"ai": {"prompt": {"pom": [...]},
        "SWAIG": {"functions": [{"function": "check_stock", ...}]}}}

{"amazon_bedrock": {"prompt": {"pom": [...], "voice_id": "matthew",
                               "temperature": 0.7, "top_p": 0.9},
                    "SWAIG": {"functions": [{"function": "check_stock", ...}]}}}

One configure() builds the desk on either class, so there is one place the prompt and the tool live. AGENT_KIND in the environment picks which one python app.py serves, BEDROCK_VOICE_ID picks the voice, and any other kind stops the process with a message.

Limitations

You prove the documents and the handler. What the Bedrock model does with the prompt and the voice, and how it sounds, are the platform’s side of a live call. The tool keeps the SDK’s secure default, so each render carries a per-call token in its webhook URL; the verifier compares the URLs without it.

BedrockAgent drops barge_confidence, presence_penalty and frequency_penalty from the prompt if you set them; the comment in agents/bedrock.py calls them text-model settings. The verifier sets none, so it does not exercise that.

What to change first

Give the Bedrock desk a different tool description in configure() by branching on isinstance(agent, BedrockAgent), and run the verifier. The functions-equal assertion fails. The recipe’s point is that you do not have to branch.

Where this sits

Before this

Route a call to an AI agent

Start from a prefab AI agent

python/app.py

"""Run a Bedrock voice agent.

`BedrockAgent` renders `amazon_bedrock` where `AgentBase` renders `ai`. The
SDK's `agents/bedrock.py` renders the base document, then rebuilds the verb
with the same `prompt` plus `voice_id`, `temperature` and `top_p` inside it.
It copies `SWAIG`, `params`, `global_data` and the post-prompt settings. So
the SWAIG functions render the same on both, and one `configure()` registers
the same handler on each agent. This file configures one parts desk twice,
once on each base class, from that one function.

Written against signalwire-sdk 3.0.1 (AgentBase, BedrockAgent).
"""
import os

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

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

STOCK = {"brake pads": 12, "chain": 4, "tubes": 0}

PARAMETERS = {
    "type": "object",
    "properties": {"part": {
        "type": "string",
        "description": "The part the caller asked about, as they said it."}},
    "required": ["part"],
}


def check_stock(args, raw_data):
    """The handler both agents run. Fixed data, so the reply is checkable."""
    part = args.get("part", "").strip().lower()
    count = STOCK.get(part)
    if count is None:
        return FunctionResult(f"We do not carry {part}.")
    if count == 0:
        return FunctionResult(f"{part} are out of stock. A restock lands Thursday.")
    return FunctionResult(f"{count} {part} in stock.")


def configure(agent):
    """One parts desk, whichever base class it sits on."""
    agent.prompt_add_section(
        "Role",
        "You are the parts desk at Ridgeline Cycles. Check stock before you promise "
        "anything, and say exactly what the check returned.")
    agent.define_tool(
        name="check_stock",
        description="Check whether a bike part is in stock before promising it.",
        parameters=PARAMETERS,
        handler=check_stock,
    )
    return agent


def build(kind="bedrock"):
    """`ai` for the standard agent, `bedrock` for the same desk on Bedrock."""
    if kind == "ai":
        return configure(AgentBase(name="parts", route="/parts"))
    if kind == "bedrock":
        return configure(BedrockAgent(name="parts", route="/parts",
                                      voice_id=os.getenv("BEDROCK_VOICE_ID", "matthew")))
    raise SystemExit(f"AGENT_KIND must be ai or bedrock, not {kind!r}")


agent = build(os.getenv("AGENT_KIND", "bedrock"))

if __name__ == "__main__":
    agent.run()

Run it

cd python
pip install -r requirements.txt
cp ../.env.example .env          # then edit .env: the basic-auth pair; AGENT_KIND and BEDROCK_VOICE_ID if you like
python app.py

The webhook needs a public HTTPS URL. For a local run, expose port 3000 with a tunnel such as ngrok and use that hostname. Point a number’s SWML webhook at https://<user>:<password>@<your-host>/parts/ and ask about brake pads. Set AGENT_KIND=ai and restart to hear the same desk on the standard model.

Verify it

No network, no account.

cd ..                     # back to the recipe folder
python verify.py

The verifier builds the desk on both classes, renders each with the same call id, and asserts the following.

the standard document’s verbs are answer, ai; the Bedrock document’s are answer, amazon_bedrock; both validate
the two SWAIG.functions lists are equal once each webhook URL’s per-call token is set aside, and each URL points at that agent’s /swaig/ path
the one function is check_stock with part required
the Bedrock prompt’s keys are exactly the standard prompt’s plus voice_id, temperature and top_p, and every standard key is equal
the values are the voice the environment set, tiffany, and 0.7 and 0.9
AGENT_KIND=ai makes the module’s agent render ai; an unknown kind stops with a message naming the two choices
check_stock executed on each agent returns the same exact reply for a stocked part, an out-of-stock part and an unknown one
the bundled schema has an AmazonBedrock definition

Report an issue