ExecuteToolScope Class

Provides OpenTelemetry tracing scope for AI tool execution operations.

Constructor

ExecuteToolScope()

Parameters

Name	Description
request Required
details Required
agent_details Required
user_details	Default value: None
span_details	Default value: None

Methods

__init__	Initialize the tool execution scope.
__new__
dispose	Dispose the scope and finalize telemetry data collection.
get_context	Get the OpenTelemetry context for this scope's span. This method returns a Context object containing this scope's span, which can be used to propagate trace context to child operations or downstream services.
inject_context_to_headers	Inject this span's trace context into W3C HTTP headers. Returns a dictionary of headers containing `traceparent` and optionally `tracestate` that can be forwarded to downstream services or stored for later context propagation. Example usage: `scope = OpenTelemetryScope(...) headers = scope.inject_context_to_headers() # Add headers to outgoing HTTP request requests.get("https://downstream-service/api", headers=headers)`
record_attributes	Record multiple attribute key/value pairs for telemetry tracking. This method allows setting multiple custom attributes on the span at once.
record_cancellation	Record task cancellation.
record_error	Record an error in the span.
record_response	Record the tool call result for telemetry tracking. Per OTEL spec, the result is expected to be an object. If a string is provided, it is recorded as-is (JSON string fallback). If a dict is provided, it is serialized to JSON.
set_end_time	Set a custom end time for the scope. When set, dispose() will pass this value to span.end() instead of using the current wall-clock time. This is useful when the actual end time of the operation is known before the scope is disposed.
set_tag_maybe	Set a tag on the span if the value is not None.
start	Creates and starts a new scope for tool execution tracing.

init

Initialize the tool execution scope.

__init__(request: Request, details: ToolCallDetails, agent_details: AgentDetails, user_details: UserDetails | None = None, span_details: SpanDetails | None = None)

Parameters

Name	Description
request Required	Request Request details for the tool execution
details Required	ToolCallDetails The details of the tool call
agent_details Required	AgentDetails The details of the agent making the call
user_details	UserDetails \| None Optional human user details Default value: None
span_details	SpanDetails \| None Optional span configuration (parent context, timing, kind) Default value: None

new

__new__(**kwargs)

dispose

Dispose the scope and finalize telemetry data collection.

dispose() -> None

Returns

Type	Description
None

get_context

Get the OpenTelemetry context for this scope's span.

This method returns a Context object containing this scope's span, which can be used to propagate trace context to child operations or downstream services.

get_context() -> Context | None

Returns

Type	Description
Context \| None	A Context containing this scope's span, or None if telemetry is disabled or no span exists.

inject_context_to_headers

Inject this span's trace context into W3C HTTP headers.

Returns a dictionary of headers containing traceparent and optionally tracestate that can be forwarded to downstream services or stored for later context propagation.

Example usage:


   scope = OpenTelemetryScope(...)
   headers = scope.inject_context_to_headers()
   # Add headers to outgoing HTTP request
   requests.get("https://downstream-service/api", headers=headers)

inject_context_to_headers() -> dict[str, str]

Returns

Type	Description
dict[str, str]	A dictionary containing W3C trace context headers. Returns an empty dictionary if telemetry is disabled or no span exists.

record_attributes

Record multiple attribute key/value pairs for telemetry tracking.

This method allows setting multiple custom attributes on the span at once.

record_attributes(attributes: dict[str, Any] | list[tuple[str, Any]]) -> None

Parameters

Name	Description
attributes Required	dict[str, Any] \| list[tuple[str, Any]] Dictionary or list of tuples containing attribute key-value pairs. Keys that are None or empty will be skipped.

Returns

Type	Description
None

record_cancellation

Record task cancellation.

record_cancellation() -> None

Returns

Type	Description
None

record_error

Record an error in the span.

record_error(exception: Exception) -> None

Parameters

Name	Description
exception Required	Exception The exception that occurred

Returns

Type	Description
None

record_response

Record the tool call result for telemetry tracking.

Per OTEL spec, the result is expected to be an object. If a string is provided, it is recorded as-is (JSON string fallback). If a dict is provided, it is serialized to JSON.

record_response(result: dict[str, object] | str) -> None

Parameters

Name	Description
result Required	dict[str, object] \| str Tool call result as a structured dict or JSON string

Returns

Type	Description
None

set_end_time

Set a custom end time for the scope.

When set, dispose() will pass this value to span.end() instead of using the current wall-clock time. This is useful when the actual end time of the operation is known before the scope is disposed.

set_end_time(end_time: datetime) -> None

Parameters

Name	Description
end_time Required	datetime The end time as a datetime object.

Returns

Type	Description
None

set_tag_maybe

Set a tag on the span if the value is not None.

set_tag_maybe(name: str, value: Any) -> None

Parameters

Name	Description
name Required	str The name of the tag
value Required	Any The value to set (will be skipped if None)

Returns

Type	Description
None

start

Creates and starts a new scope for tool execution tracing.

static start(request: Request, details: ToolCallDetails, agent_details: AgentDetails, user_details: UserDetails | None = None, span_details: SpanDetails | None = None) -> ExecuteToolScope

Parameters

Name	Description
request Required	Request Request details for the tool execution
details Required	ToolCallDetails The details of the tool call
agent_details Required	AgentDetails The details of the agent making the call
user_details	UserDetails \| None Optional human user details Default value: None
span_details	SpanDetails \| None Optional span configuration (parent context, timing, kind) Default value: None

Returns

Type	Description
ExecuteToolScope	A new ExecuteToolScope instance