Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.inference.net/llms.txt

Use this file to discover all available pages before exploring further.

Catalyst instruments the ElevenLabs Agents SDK in TypeScript and Python. Initialize tracing before starting a conversation so the SDK conversation lifecycle and client-tool callbacks are patched before the session begins. Use this guide for applications that use @elevenlabs/client or the Python elevenlabs.conversational_ai.conversation APIs.

​
What Is Captured

  • One AGENT span named ElevenLabs Conversation for each conversation session
  • User and agent transcript messages as OpenInference message attributes
  • ElevenLabs metadata such as agent ID, conversation ID, user ID, auth mode, and text-only mode
  • TOOL child spans for registered client tools, including tool name, arguments, result, and errors
  • Error status and exception details when session startup, tool execution, or shutdown fails

​
Install

bun add @inference/tracing @elevenlabs/client

​
TypeScript Conversation Session

Pass the ElevenLabs SDK namespace into setup() before calling Conversation.startSession().
TypeScript
import * as ElevenLabs from "@elevenlabs/client";
import { Conversation } from "@elevenlabs/client";
import { setup } from "@inference/tracing";

const tracing = await setup({
  serviceName: "voice-support",
  modules: { elevenlabs: ElevenLabs },
});

const conversation = await Conversation.startSession({
  agentId: process.env.ELEVENLABS_AGENT_ID!,
  textOnly: true,
  userId: "user_123",
  clientTools: {
    lookupAppointment: async ({ user_id }) => {
      return JSON.stringify({
        user_id,
        starts_at: "2026-04-29T10:30:00Z",
      });
    },
  },
  onMessage: (message) => {
    console.log(message.role, message.message);
  },
});

conversation.sendUserMessage("When is my next appointment?");
await conversation.endSession();
await tracing.shutdown();
For private agents, use the same tracing setup and pass the signedUrl or conversationToken options that your ElevenLabs app already uses. Catalyst keeps the same outer ElevenLabs Conversation span shape.

​
Python Conversation Session

Call setup() before constructing and starting the Conversation. This patches the installed ElevenLabs SDK and records the session lifecycle automatically.
Python
import os

from elevenlabs.client import ElevenLabs
from elevenlabs.conversational_ai.conversation import ClientTools, Conversation
from inference_catalyst_tracing import setup

tracing = setup(service_name="voice-support")

client = ElevenLabs(api_key=os.environ.get("ELEVENLABS_API_KEY"))
client_tools = ClientTools()
client_tools.register(
    "lookupAppointment",
    lambda params: {
        "user_id": params["user_id"],
        "starts_at": "2026-04-29T10:30:00Z",
    },
)

conversation = Conversation(
    client,
    os.environ["ELEVENLABS_AGENT_ID"],
    user_id="user_123",
    requires_auth=bool(os.environ.get("ELEVENLABS_API_KEY")),
    audio_interface=None,
    client_tools=client_tools,
    callback_agent_response=lambda text: print(f"Agent: {text}"),
    callback_user_transcript=lambda text: print(f"User: {text}"),
)

conversation.start_session()
conversation.send_user_message("When is my next appointment?")
conversation.end_session()
conversation_id = conversation.wait_for_session_end()
print(f"Conversation ID: {conversation_id}")

tracing.shutdown()
audio_interface=None keeps the example text-only. For voice conversations, use your normal ElevenLabs audio interface; the instrumentation records the same conversation span and transcript callbacks.

​
Verify In Catalyst

Filter traces by service.name=voice-support. A successful session should show an ElevenLabs Conversation AGENT span with nested TOOL spans when your agent calls lookupAppointment. For short-lived scripts, always call tracing.shutdown() before process exit so batched spans are flushed to Catalyst.