Mock Tool Calls Reference

​

How it works

1. Open the agent’s Simulation Settings and turn on Mock tool calls. Every tool the agent has is listed.
2. Pick a mode for each tool. Tools start on Generated.
3. Run a simulation. Each tool call gets its answer from Bluejay.

1. The Digital Human’s Tool Response Overrides entry for the tool.
2. The agent’s Fixed response for the tool.
3. A generated result, unless the tool is on Real backend.
4. Your real tool.

​

Override a tool for one test case

​

Example

1. Turn on Mock tool calls in the agent’s Simulation Settings.
2. Set check_availability to Fixed with {"slots": ["Thursday 7:40 AM", "Thursday 4:05 PM"]}. Leave lookup_patient on Generated.
3. Create a Digital Human who asks for a Thursday appointment, with the success criterion “The agent reads back the Thursday times that check_availability returned.”

​

Set up by platform

​

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 on 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.

​

Google CES and Dialogflow CX

• A tool on 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.

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.
• When the call has a test id and Bluejay errors or times out, return an error result instead of running the real tool, so a test never reaches your real backend. Generated results can take a few seconds, so wait up to 10.

​

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.

​

LiveKit and Pipecat

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

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)
    ...

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)

• 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.

​

API and MCP

​

Turn mocking on or off

curl -X PUT https://api.getbluejay.ai/v1/agents/$AGENT_ID/mock-tools \
  -H "X-API-Key: $BLUEJAY_API_KEY" -H "Content-Type: application/json" \
  -d '{"enabled": true, "tools": {"check_availability": {"mode": "fixed", "response": {"slots": ["Thursday 7:40 AM"]}}}}'

​

Set one tool

​

Resolve a mock

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"]}}

• When the call is a Bluejay simulation and Bluejay can’t produce a result, the answer is mocked: true with the result {"error": "This tool is unavailable in this test."}.
• caller_number matches the Digital Human with that number whose conversation is running now. If none is running, the answer is mocked: false.
• An unknown id, an id from another organization, and an id from a workspace your key can’t read all answer mocked: false. Bluejay never reveals whether the id exists.
• The limit is 600 requests per minute per organization. Over it, the endpoint answers 429. Treat a 429 like any other error: return an error result when the call has a test id, otherwise run the real tool.

​

SDK helper

• A call with no test id and no caller number never contacts Bluejay.
• With a test id, a lookup that fails, times out, or answers 429 returns {"error": "This tool is unavailable in this test."}. Your real tool never runs.
• With only a caller number, the call may be a real caller, so a failed lookup runs your real tool.
• A mocked result is returned as a string. Objects are JSON-encoded.

​

Which calls reach your real tool

​

Related

• Digital Human Reference
• Create a Simulation