function_call_observer

Observer reporting the function calls a conversation makes.

A function call is the one thing a bot does rather than says, and the part of a turn whose duration belongs to the application’s own code. This observer reports a call when it starts, when it goes in progress, and when it settles, so a call that stops short of any of those reads as one still waiting rather than one that quietly stopped mattering.

class pipecat.observers.function_call_observer.FunctionCallEventKind(*values)[source]

Bases: StrEnum

Where a function call has got to.

A call starts when the LLM asks for it and is in progress once it is running, which are two moments rather than one: calls run one at a time unless the service was built to run them in parallel, so a call can wait in between, and a call still waiting when the conversation moves on never runs at all. A call settles in one of four ways: it returned, its handler raised, it ran past its deadline, or it was cancelled — by an interruption, or by the LLM asking for it.

STARTED = 'function_call_started'
IN_PROGRESS = 'function_call_in_progress'
COMPLETED = 'function_call_completed'
FAILED = 'function_call_failed'
TIMED_OUT = 'function_call_timed_out'
CANCELLED = 'function_call_cancelled'
class pipecat.observers.function_call_observer.FunctionCallEvent(*, kind: FunctionCallEventKind, function_name: str, tool_call_id: str, timestamp: float, group_id: str | None = None, blocking: bool | None = None, arguments: Any | None = None, started_at: float | None = None, in_progress_at: float | None = None, result: Any | None = None, error: str | None = None)[source]

Bases: BaseModel

One moment in the life of a function call.

The moments that open a call describe it; the moment that settles it describes what became of it. Each names the call, so they read as a sequence without any of them repeating the others.

Parameters:

  • kind – What happened to the call.

  • function_name – The name of the function.

  • tool_call_id – The LLM’s identifier for this call, unique within a conversation.

  • timestamp – Unix timestamp of the moment.

  • group_id – Identifies the calls the LLM asked for in one response, which run together. Set when the call goes in progress.

  • blocking – Whether the conversation waited for this call. A call that doesn’t block is answered later through a developer message, while the LLM carries on talking. Set when the call goes in progress.

  • arguments – What the LLM passed to the function, when the observer is reporting arguments. Set both when the call starts and when it goes in progress, since a call can be reported at either moment without the other.

  • started_at – When the call started, on the moment it goes in progress, so the wait between the two reads from one record.

  • in_progress_at – When the call went in progress, on the moment that settles it, so the time it ran reads from one record.

  • result – What the handler returned, when the observer is reporting results.

  • error – What went wrong, on a call whose handler raised.

class pipecat.observers.function_call_observer.FunctionCallObserver(*, include_arguments: bool = True, include_results: bool = False, time_source: Callable[[], float]=<built-in function time>, **kwargs)[source]

Bases: BaseObserver

Reports each function call a conversation makes, from start to outcome.

A call is reported at each moment it reaches rather than summarized once it is over, because the moments can be far apart and a call need not reach all of them: one waiting its turn to run is dropped if the conversation moves on, and one the conversation doesn’t wait for can settle long after the turn that asked for it.

Arguments and results are where a call holds whatever the conversation was about, so each is a choice: arguments travel by default, being small and the reason a call is worth reading at all, and results do not, being whatever a provider decided to return.

Events:
on_function_call_event(observer, event): Emitted for each moment, as a

FunctionCallEvent.

Example:

observer = FunctionCallObserver()

@observer.event_handler("on_function_call_event")
async def on_function_call_event(observer, event):
    logger.info(event.model_dump_json())
__init__(*, include_arguments: bool = True, include_results: bool = False, time_source: Callable[[], float]=<built-in function time>, **kwargs)[source]

Initialize the function call observer.

Parameters:

  • include_arguments – Whether to report the arguments a call was made with.

  • include_results – Whether to report what a call returned.

  • time_source – Reads the current time in seconds. Supplying one lets a test place moments without waiting.

  • **kwargs – Additional arguments passed to parent class.

async on_push_frame(data: FramePushed)[source]

Report the moment a frame represents.

Parameters:

data – Frame push event containing the frame and direction.