InvokeAgentScope 类

为 AI 代理调用作提供 OpenTelemetry 跟踪范围。

构造函数

InvokeAgentScope()

参数

名称	说明
request 必需
scope_details 必需
agent_details 必需
caller_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_input_messages	记录遥测跟踪的输入消息。 接受纯字符串（以角色 user自动包装为 一种 一样）或版本控制 InputMessages 包装器。
record_output_messages	记录遥测跟踪的输出消息。 接受纯字符串（作为角色 assistant自动包装为 一个 一个 一级输出消息）或版本控制 OutputMessages 包装器。
record_response	记录遥测跟踪的响应信息。
set_end_time	设置范围的自定义结束时间。 设置后，dispose（） 会将此值传递给 span.end（），而不是使用当前的时钟时间。 当在释放作用域之前已知操作的实际结束时间时，这非常有用。
set_tag_maybe	如果值不是 None，则设置范围上的标记。
start	创建并启动代理调用跟踪的新范围。

__init__

初始化代理调用范围。

__init__(request: Request, scope_details: InvokeAgentScopeDetails, agent_details: AgentDetails, caller_details: CallerDetails | None = None, span_details: SpanDetails | None = None)

参数

名称	说明
request 必需	Request 调用的请求详细信息
scope_details 必需	InvokeAgentScopeDetails 范围级别配置（终结点）
agent_details 必需	AgentDetails 正在调用的代理的详细信息
caller_details	CallerDetails | None 可选复合调用方详细信息（A2A 方案的人工用户和/或呼叫代理） 默认值: 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

record_cancellation

记录任务取消。

record_cancellation() -> None

返回

类型	说明
None

record_error

记录跨度中的错误。

record_error(exception: Exception) -> None

参数

名称	说明
exception 必需	Exception 发生的异常

返回

类型	说明
None

record_input_messages

记录遥测跟踪的输入消息。

接受纯字符串（以角色 user自动包装为 一种 一样）或版本控制 InputMessages 包装器。

record_input_messages(messages: str | list[str] | InputMessages) -> None

参数

名称	说明
messages 必需	str | list[str] | InputMessages 输入消息字符串或 InputMessages 包装器的列表

返回

类型	说明
None

record_output_messages

记录遥测跟踪的输出消息。

接受纯字符串（作为角色 assistant自动包装为 一个 一个 一级输出消息）或版本控制 OutputMessages 包装器。

record_output_messages(messages: str | list[str] | OutputMessages) -> None

参数

名称	说明
messages 必需	str | list[str] | OutputMessages 输出消息字符串或 OutputMessages 包装器的列表

返回

类型	说明
None

record_response

记录遥测跟踪的响应信息。

record_response(response: str) -> None

参数

名称	说明
response 必需	str 要记录的响应字符串

返回

类型	说明
None

set_end_time

设置范围的自定义结束时间。

设置后，dispose（） 会将此值传递给 span.end（），而不是使用当前的时钟时间。 当在释放作用域之前已知操作的实际结束时间时，这非常有用。

set_end_time(end_time: datetime) -> None

参数

名称	说明
end_time 必需	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, scope_details: InvokeAgentScopeDetails, agent_details: AgentDetails, caller_details: CallerDetails | None = None, span_details: SpanDetails | None = None) -> InvokeAgentScope

参数

名称	说明
request 必需	Request 调用的请求详细信息
scope_details 必需	InvokeAgentScopeDetails 范围级别配置（终结点）
agent_details 必需	AgentDetails 正在调用的代理的详细信息
caller_details	CallerDetails | None 可选复合调用方详细信息（A2A 方案的人工用户和/或呼叫代理） 默认值: None
span_details	SpanDetails | None 可选范围配置（父上下文、计时、类型） 默认值: None

返回

类型	说明
InvokeAgentScope	新的 InvokeAgentScope 实例