Simulation Tool Calls

Bluejay can ingest the tool calls and metadata your voice agent produces during simulations, giving you evaluation data that goes far beyond transcript analysis. By capturing every API call, database query, and business action your agent takes, you can measure whether it performed the right operations — not just whether it said the right things.

The /v1/update-simulation-result endpoint also accepts trace_ids for linking OpenTelemetry traces to simulation results. See Traces for details.

How It Works

During a simulation, Bluejay provides a unique X-Simulation-Result-Id for each conversation. Your agent must extract this ID, track its tool calls and metadata during the call, and then send that data back to Bluejay post-call via the /v1/update-simulation-result endpoint.

Integration Methods

Bluejay supports three methods for tool call tracking, depending on your infrastructure.

SIP Integration (Recommended for Phone Systems)

Best for: traditional phone systems (PSTN), VoIP providers, and telephony infrastructure. When Bluejay initiates calls via SIP, it injects custom headers including X-Simulation-Result-Id directly into the SIP INVITE message. Flow:

Bluejay sends a SIP INVITE with custom headers to your agent
Your agent must extract X-Simulation-Result-Id from the SIP headers
During the call, your agent must log every tool call and relevant metadata
After the call ends, you must send the collected data to /v1/update-simulation-result

SIP Integration Guide →

WebSocket Integration

Best for: modern web-based agents and non-phone-based systems. WebSocket integration using the CHIRP protocol provides real-time, bidirectional communication. The X-Simulation-Result-Id is sent as an HTTP header on the WebSocket upgrade request. Flow:

Bluejay opens the WebSocket connection with X-Simulation-Result-Id as a header on the upgrade request
Real-time CHIRP message exchange during the conversation
Your agent must log tool calls and metadata throughout the session
After the call ends, you must send the collected data to /v1/update-simulation-result

WebSocket Integration Guide →

LiveKit Integration

Best for: agents built on the LiveKit Agents framework. Bluejay joins the LiveKit room alongside your agent. When your agent invokes a tool, publish a data packet to a configured topic and Bluejay ingests it automatically — no post-call API call needed. Flow:

Set the LiveKit Customer Tool Topic in your Agent Connection settings
Publish a JSON packet to that topic whenever your agent calls a tool
Bluejay ingests packets in real time and persists them when the call ends

LiveKit Integration Guide →

Why SIP for Phone-Based Agents?

If your agent runs through traditional phone systems (PSTN), basic telephony integration does not support tool call enrichment. To unlock tool call and metadata tracking for phone-based agents, you need SIP.

Feature	Basic Telephony	SIP Integration
Setup Complexity	Simple phone number	SIP endpoint configuration
Tool Call Tracking	❌ Not supported	✅ Complete tracking
Custom Metadata	❌ Not supported	✅ Rich metadata support
Evaluations	Conversation-focused	✅ Comprehensive insights
Integration Effort	Minimal	Moderate (one-time setup)

Compatible phone systems: traditional PBX, VoIP providers (Twilio, RingCentral, Telnyx, etc.), and any SIP-based platform.

Step-by-Step Guide

1. Choose Your Integration Method

Phone-based agents → follow the SIP Integration Guide
Web-based agents → follow the WebSocket Integration Guide

2. Track Tool Calls in Your Agent

Implement tool call tracking wherever your agent invokes external tools, APIs, or business logic during a call:

def track_tool_call(name, parameters, output, start_offset_ms):
    return {
        "name": name,                      # required: the tool that was invoked
        "parameters": parameters,          # optional: input arguments
        "output": output,                  # optional: return value
        "start_offset_ms": start_offset_ms # required: milliseconds from call start
    }

3. Send Data to Bluejay

After the call ends, use the X-Simulation-Result-Id to call the /v1/update-simulation-result endpoint with the tool calls, events, and metadata you collected. Endpoint: POST /v1/update-simulation-result Headers:

X-API-Key: <your-api-key>
Content-Type: application/json

Request body:

{
  "simulation_result_id": "1234",
  "events": [
    {
      "title": "Customer verified",
      "description": "Voice biometric check passed",
      "start_offset_ms": 30000,
      "tags": ["verification"]
    }
  ],
  "tool_calls": [
    {
      "name": "transfer_funds",
      "parameters": {"from": "12345", "to": "67890", "amount": 500},
      "output": {"transaction_id": "txn_abc123", "status": "completed"},
      "start_offset_ms": 120000
    }
  ],
  "metadata": {
    "call_duration": 180,
    "customer_satisfaction": 5,
    "resolution_status": "resolved",
    "custom_tags": ["account_inquiry", "funds_transfer"]
  }
}

Process tool calls and metadata asynchronously and call the endpoint after the call has ended. This avoids adding latency to the live conversation and ensures Bluejay can use the data during evaluation.

Use Cases

Multi-Agent Orchestration

Track tool calls across agent handoffs and escalation workflows:

{
  "tool_calls": [
    {
      "name": "route_to_specialist",
      "parameters": {"customer_issue": "billing_inquiry", "current_agent": "tier1_support"},
      "output": {"routed_to": "billing_specialist", "agent_id": "agent_billing_001"},
      "start_offset_ms": 45000
    }
  ],
  "metadata": {
    "workflow_type": "escalation",
    "total_agents_involved": 2,
    "handoff_duration_seconds": 15
  }
}

Financial Services

Monitor critical financial operations with audit trails:

{
  "tool_calls": [
    {
      "name": "verify_account_ownership",
      "parameters": {"account_id": "12345", "verification_method": "voice_biometric"},
      "output": {"verified": true, "confidence_score": 0.95},
      "start_offset_ms": 30000
    },
    {
      "name": "initiate_wire_transfer",
      "parameters": {"from_account": "12345", "to_account": "67890", "amount": 1000.00},
      "output": {"transaction_id": "wire_xyz789", "status": "pending_approval"},
      "start_offset_ms": 90000
    }
  ],
  "metadata": {
    "compliance_flags": ["high_value_transaction", "cross_border"],
    "risk_score": 0.3,
    "authentication_methods": ["voice_biometric", "account_verification"]
  }
}

E-commerce & Order Management

Track customer service interactions with order processing systems:

{
  "tool_calls": [
    {
      "name": "lookup_order",
      "parameters": {"order_id": "ORD-2024-001"},
      "output": {"order_status": "shipped", "tracking_number": "1Z999AA1234567890"},
      "start_offset_ms": 20000
    },
    {
      "name": "initiate_return",
      "parameters": {"order_id": "ORD-2024-001", "reason": "size_issue"},
      "output": {"return_id": "RET-2024-456", "prepaid_label": true},
      "start_offset_ms": 80000
    }
  ],
  "metadata": {
    "customer_tier": "premium",
    "order_value": 299.99,
    "resolution_time_seconds": 120
  }
}

Best Practices

Capture everything — track all external interactions, including failed calls, for complete visibility
Include timing — record start_offset_ms (milliseconds from call start) so Bluejay can place each tool call at the right moment in the transcript
Log errors — failed tool calls and error details are just as valuable as successes for debugging agent behavior
Store parameters — input parameters enable reproducibility analysis across simulation runs
Process async, send post-call — handle tracking asynchronously during the call, then batch-send to /v1/update-simulation-result after the call ends

Next Steps

Update Simulation Result API

Full endpoint reference for enriching simulation results.

SIP Integration

Set up SIP connectivity for phone-based agents.

WebSocket Integration

Connect web-based agents via CHIRP protocol.

Traces

Link OpenTelemetry traces to simulation results.

Tool Calls

Pass tool calls for production conversation evaluations instead.

Getting Started

Key Concepts

Test

Monitor

Integrations

How It Works

Integration Methods

SIP Integration (Recommended for Phone Systems)

WebSocket Integration

LiveKit Integration

Why SIP for Phone-Based Agents?

Step-by-Step Guide

1. Choose Your Integration Method

2. Track Tool Calls in Your Agent

3. Send Data to Bluejay

Use Cases

Multi-Agent Orchestration

Financial Services

E-commerce & Order Management

Best Practices

Next Steps

Update Simulation Result API

SIP Integration

WebSocket Integration

Traces

Tool Calls

​How It Works

​Integration Methods

​SIP Integration (Recommended for Phone Systems)

​WebSocket Integration

​LiveKit Integration

​Why SIP for Phone-Based Agents?

​Step-by-Step Guide

​1. Choose Your Integration Method

​2. Track Tool Calls in Your Agent

​3. Send Data to Bluejay

​Use Cases

​Multi-Agent Orchestration

​Financial Services

​E-commerce & Order Management

​Best Practices

​Next Steps

Update Simulation Result API

SIP Integration

WebSocket Integration

Traces

Tool Calls

How It Works

Integration Methods

SIP Integration (Recommended for Phone Systems)

WebSocket Integration

LiveKit Integration

Why SIP for Phone-Based Agents?

Step-by-Step Guide

1. Choose Your Integration Method

2. Track Tool Calls in Your Agent

3. Send Data to Bluejay

Use Cases

Multi-Agent Orchestration

Financial Services

E-commerce & Order Management

Best Practices

Next Steps