ExecuteToolScope クラス

AI ツール実行操作の OpenTelemetry トレース スコープを提供します。

コンストラクター

ExecuteToolScope()

パラメーター

名前	説明
request 必須
details 必須
agent_details 必須
user_details	規定値: None
span_details	規定値: None

メソッド

__init__	ツールの実行スコープを初期化します。
__new__
dispose	スコープを破棄し、テレメトリ データ収集を完了します。
get_context	このスコープのスパンの OpenTelemetry コンテキストを取得します。 このメソッドは、このスコープのスパンを含む Context オブジェクトを返します。これは、トレース コンテキストを子操作またはダウンストリーム サービスに伝達するために使用できます。
inject_context_to_headers	このスパンのトレース コンテキストを W3C HTTP ヘッダーに挿入します。 ダウンストリーム サービスに転送したり、後でコンテキスト伝達のために格納したりできる traceparent と必要に応じて tracestate を含むヘッダーのディクショナリを返します。 使用例: 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_cancellation	タスクの取り消しを記録します。
record_error	スパンにエラーを記録します。
record_response	テレメトリ追跡用のツール呼び出し結果を記録します。 OTEL 仕様では、結果はオブジェクトであることが期待されます。 文字列が指定されている場合は、as-is 記録されます (JSON 文字列フォールバック)。 dict が指定されている場合は、JSON にシリアル化されます。
set_end_time	スコープのカスタム終了時刻を設定します。 この値を設定すると、dispose() は現在の実時間を使用する代わりに span.end() にこの値を渡します。 これは、スコープが破棄される前に、操作の実際の終了時刻がわかっている場合に便利です。
set_tag_maybe	値が None でない場合は、スパンにタグを設定します。
start	ツール実行トレースの新しいスコープを作成して開始します。

__init__

ツールの実行スコープを初期化します。

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

パラメーター

名前	説明
request 必須	Request ツール実行の詳細を要求する
details 必須	ToolCallDetails ツール呼び出しの詳細
agent_details 必須	AgentDetails 呼び出しを行っているエージェントの詳細
user_details	UserDetails | None 省略可能な人間のユーザーの詳細 規定値: None
span_details	SpanDetails | None オプションのスパン構成 (親コンテキスト、タイミング、種類) 規定値: None

__new__

__new__(**kwargs)

dispose

スコープを破棄し、テレメトリ データ収集を完了します。

dispose() -> None

返品

型	説明
None

get_context

このスコープのスパンの OpenTelemetry コンテキストを取得します。

このメソッドは、このスコープのスパンを含む Context オブジェクトを返します。これは、トレース コンテキストを子操作またはダウンストリーム サービスに伝達するために使用できます。

get_context() -> Context | None

返品

型	説明
Context | None	このスコープのスパンを含むコンテキスト。テレメトリが無効になっているか、スパンが存在しない場合は None。

inject_context_to_headers

このスパンのトレース コンテキストを W3C HTTP ヘッダーに挿入します。

ダウンストリーム サービスに転送したり、後でコンテキスト伝達のために格納したりできる traceparent と必要に応じて tracestate を含むヘッダーのディクショナリを返します。

使用例:

   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]

返品

型	説明
dict[str, str]	W3C トレース コンテキスト ヘッダーを含むディクショナリ。 テレメトリが無効になっている場合、またはスパンが存在しない場合は、空のディクショナリを返します。

record_attributes

テレメトリ追跡のために、複数の属性キーと値のペアを記録します。

このメソッドを使用すると、スパンに複数のカスタム属性を一度に設定できます。

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

パラメーター

名前	説明
attributes 必須	dict[str, Any] | list[tuple[str, Any]] 属性キーと値のペアを含むタプルのディクショナリまたはリスト。 None または空のキーはスキップされます。

返品

型	説明
None

record_cancellation

タスクの取り消しを記録します。

record_cancellation() -> None

返品

型	説明
None

record_error

スパンにエラーを記録します。

record_error(exception: Exception) -> None

パラメーター

名前	説明
exception 必須	Exception 発生した例外

返品

型	説明
None

record_response

テレメトリ追跡用のツール呼び出し結果を記録します。

OTEL 仕様では、結果はオブジェクトであることが期待されます。 文字列が指定されている場合は、as-is 記録されます (JSON 文字列フォールバック)。 dict が指定されている場合は、JSON にシリアル化されます。

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

パラメーター

名前	説明
result 必須	dict[str, object] | str 構造化された dict または JSON 文字列としてのツール呼び出しの結果

返品

型	説明
None

set_end_time

スコープのカスタム終了時刻を設定します。

この値を設定すると、dispose() は現在の実時間を使用する代わりに span.end() にこの値を渡します。 これは、スコープが破棄される前に、操作の実際の終了時刻がわかっている場合に便利です。

set_end_time(end_time: datetime) -> None

パラメーター

名前	説明
end_time 必須	datetime datetime オブジェクトとしての終了時刻。

返品

型	説明
None

set_tag_maybe

値が None でない場合は、スパンにタグを設定します。

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

パラメーター

名前	説明
name 必須	str タグの名前
value 必須	Any 設定する値 (None の場合はスキップされます)

返品

型	説明
None

start

ツール実行トレースの新しいスコープを作成して開始します。

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

パラメーター

名前	説明
request 必須	Request ツール実行の詳細を要求する
details 必須	ToolCallDetails ツール呼び出しの詳細
agent_details 必須	AgentDetails 呼び出しを行っているエージェントの詳細
user_details	UserDetails | None 省略可能な人間のユーザーの詳細 規定値: None
span_details	SpanDetails | None オプションのスパン構成 (親コンテキスト、タイミング、種類) 規定値: None

返品

型	説明
ExecuteToolScope	新しい ExecuteToolScope インスタンス