Skip to main content
The FunctionCallObserver reports each function call a conversation makes, tracking it through multiple moments rather than summarizing it once it is over. This is useful 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.

​
Function Call Lifecycle

A function call progresses through several distinct moments:
  1. Started: When the LLM asks for the call
  2. In Progress: When the call begins running (can wait between these two)
  3. Settled: One of four outcomes:
    • Completed: The handler returned successfully
    • Failed: The handler raised an exception
    • Timed Out: The call ran past its deadline
    • Cancelled: Interrupted or cancelled by the LLM

​
Events

The observer emits one event:
  • on_function_call_event: Emitted for each moment a call reaches
    • Parameters: observer (FunctionCallObserver), event (FunctionCallEvent)

​
Usage

​
Configuration

​
bool
default:"True"
Whether to report the arguments a call was made with. Arguments are small and the reason a call is worth reading at all, so they travel by default.
​
bool
default:"False"
Whether to report what a call returned. Results are whatever a provider decided to return and can be large, so they do not travel by default.
​
Callable[[], float]
default:"time.time"
Reads the current time in seconds. Supplying one lets a test place moments without waiting.

​
FunctionCallEvent

Each event is a FunctionCallEvent with the following fields:
​
FunctionCallEventKind
required
What happened to the call. One of: function_call_started, function_call_in_progress, function_call_completed, function_call_failed, function_call_timed_out, or function_call_cancelled.
​
str
required
The name of the function.
​
str
required
The LLM’s identifier for this call, unique within a conversation.
​
float
required
Unix timestamp of the moment.
​
str | None
default:"None"
Identifies the calls the LLM asked for in one response, which run together. Set when the call goes in progress.
​
bool | None
default:"None"
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.
​
Any | None
default:"None"
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.
​
float | None
default:"None"
When the call started, on the moment it goes in progress, so the wait between the two reads from one record.
​
float | None
default:"None"
When the call went in progress, on the moment that settles it, so the time it ran reads from one record.
​
Any | None
default:"None"
What the handler returned, when the observer is reporting results.
​
str | None
default:"None"
What went wrong, on a call whose handler raised.

​
Example Event Sequence

For a successful function call:

​
Use Cases

  • Analytics: Measure function call latency, success rates, and wait times
  • Debugging: Track which calls are made, what arguments they receive, and how they settle
  • Monitoring: Alert on failed or timed-out calls
  • Tracing: Build complete traces of function call execution