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:- Started: When the LLM asks for the call
- In Progress: When the call begins running (can wait between these two)
- 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)
- Parameters:
Usage
Configuration
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.
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.
Reads the current time in seconds. Supplying one lets a test place moments
without waiting.
FunctionCallEvent
Each event is aFunctionCallEvent with the following fields:
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.Identifies the calls the LLM asked for in one response, which run together.
Set when the call goes in progress.
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.
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.
When the call started, on the moment it goes in progress, so the wait between
the two reads from one record.
When the call went in progress, on the moment that settles it, so the time it
ran reads from one record.
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