Mock Tool Calls: Setup

​

Turn on mocking

​

ElevenLabs

• The branch is a copy of your live version. It has a client tool in place of each webhook tool, with the same name and schema. Tools set to Real backend stay webhooks and call your server.
• The branch takes 0% of traffic. Live callers and your main version are never touched.
• Bluejay reuses the branch for every run. When you publish a new live version, Bluejay rebuilds the branch the next time you queue a run. Changing a tool to or from Real backend rebuilds it right away.
• Don’t edit the branch. Bluejay overwrites it.

• Each tool gets the Digital Human’s override, the Fixed response, or a generated result, in that order.
• If Bluejay can’t produce a result, the tool gets an error, “No mock result is available for this tool in this test.” Your real tool never runs, including calls the agent makes early or drops after an interruption.

​

Google CES and Dialogflow CX

• A tool set to Real backend gets an error result, since nothing can run your real tool on this path.
• A result that is not a JSON object arrives as {"result": <value>}.
• Tools that Google runs itself, such as OpenAPI tools, still call your real system. Bluejay can’t mock them yet.

​

Retell, Vapi and other platforms

1. Read the Bluejay test id from the call.
2. Call POST /v1/tool-mocks/resolve with your Bluejay API key.
3. If mocked is true, return result and skip the real tool. On mocked: false, run the real tool.

curl -X POST https://api.getbluejay.ai/v1/tool-mocks/resolve \
  -H "X-API-Key: $BLUEJAY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"tool_name": "check_availability", "arguments": {"day": "Thursday"}, "test_result_id": 125145}'

{"mocked": true, "result": {"slots": ["Thursday 7:40 AM", "Thursday 4:05 PM"]}}

import os, httpx
from fastapi import FastAPI

app = FastAPI()

@app.post("/check_availability")
def check_availability(body: dict):
    test_id = (body["call"].get("metadata") or {}).get("test_result_id")
    if test_id:
        try:
            r = httpx.post("https://api.getbluejay.ai/v1/tool-mocks/resolve", timeout=10,
                headers={"X-API-Key": os.environ["BLUEJAY_API_KEY"]},
                json={"tool_name": "check_availability", "arguments": body["args"], "test_result_id": int(test_id)})
            r.raise_for_status()
            data = r.json()
        except Exception:
            return {"error": "This tool is unavailable in this test."}
        if data.get("mocked"):
            return data["result"]
    return my_calendar.slots(**body["args"])

• Only call Bluejay when the call has a test id or comes from a Bluejay number. Real callers then never wait on Bluejay.
• On mocked: false, run the real tool. When the call has a test id and Bluejay errors or times out, return an error result instead, so a test never reaches your real backend. Generated results can take a few seconds, so wait up to 10.
• When Bluejay can’t produce a result for a test, it answers mocked: true with an error result.
• A tool set to Real backend answers mocked: false, so your real tool runs. Every other tool is mocked, generated unless you set it to Fixed.

​

Custom agents (LiveKit, Pipecat)

pip install bluejay-sdk
export BLUEJAY_API_KEY=<your Bluejay API key>

​

LiveKit

from bluejay.helpers.tool_mocks import bind_livekit, mockable

class Scheduler(Agent):
    @function_tool
    @mockable
    async def check_availability(self, day: str) -> str:
        return await my_calendar.slots(day)

async def entrypoint(ctx: JobContext):
    bind_livekit(ctx)
    ...

​

Pipecat

from bluejay.helpers.tool_mocks import bind, mock_or_call

async def bot(args):
    bind(test_result_id=args.body.get("X-Simulation-Result-Id"))
    ...

async def check_availability(params):
    result = await mock_or_call("check_availability", params.arguments, lambda: my_calendar.slots(**params.arguments))
    await params.result_callback(result)

​

How the helper finds the call

• bind_livekit reads X-Simulation-Result-Id from the dispatch metadata, then from participant attributes. For SIP calls into LiveKit, map the header with headers_to_attributes on your inbound trunk.
• On plain phone calls the header is dropped, so bind_livekit falls back to the caller’s number, sip.phoneNumber.
• In any other server, call bind(test_result_id=...) or bind(caller_number=...) yourself.

​

Phone

• SIP calls carry X-Simulation-Result-Id. Send it as test_result_id.
• Phone calls drop SIP headers. Send the Digital Human’s phone number as caller_number, in E.164 form. Bluejay matches it to the Digital Human calling from that number right now.
• When your agent calls the Digital Human, the Digital Human’s number is the number your agent dialed.