ExecuteToolScope Classe

Fornece o escopo de rastreamento opentelemetry para operações de execução de ferramentas de IA.

Construtor

ExecuteToolScope()

Parâmetros

Nome	Description
request Obrigatório
details Obrigatório
agent_details Obrigatório
user_details	Valor padrão: None
span_details	Valor padrão: None

Métodos

__init__	Inicialize o escopo de execução da ferramenta.
__new__
dispose	Descarte o escopo e finalize a coleta de dados de telemetria.
get_context	Obtenha o contexto OpenTelemetry para o intervalo desse escopo. Esse método retorna um objeto Context que contém o intervalo desse escopo, que pode ser usado para propagar o contexto de rastreamento para operações filho ou serviços downstream.
inject_context_to_headers	Injete o contexto de rastreamento desse intervalo em cabeçalhos HTTP W3C. Retorna um dicionário de cabeçalhos que contém `traceparent` e, opcionalmente `tracestate` , que podem ser encaminhados para serviços downstream ou armazenados para propagação de contexto posterior. Exemplo de uso: `scope = OpenTelemetryScope(...) headers = scope.inject_context_to_headers() # Add headers to outgoing HTTP request requests.get("https://downstream-service/api", headers=headers)`
record_attributes	Registre vários pares de chave/valor de atributo para acompanhamento de telemetria. Esse método permite definir vários atributos personalizados no intervalo de uma só vez.
record_cancellation	Registrar cancelamento de tarefa.
record_error	Registre um erro no intervalo.
record_response	Registre o resultado da chamada da ferramenta para o acompanhamento de telemetria. Por especificação OTEL, espera-se que o resultado seja um objeto. Se uma cadeia de caracteres for fornecida, ela será registrada as-is (fallback da cadeia de caracteres JSON). Se um ditado for fornecido, ele será serializado para JSON.
set_end_time	Defina uma hora de término personalizada para o escopo. Quando definido, dispose() passará esse valor para span.end() em vez de usar o tempo atual do relógio de parede. Isso é útil quando a hora de término real da operação é conhecida antes de o escopo ser descartado.
set_tag_maybe	Defina uma marca no intervalo se o valor não for Nenhum.
start	Cria e inicia um novo escopo para rastreamento de execução de ferramentas.

init

Inicialize o escopo de execução da ferramenta.

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

Parâmetros

Nome	Description
request Obrigatório	Request Solicitar detalhes para a execução da ferramenta
details Obrigatório	ToolCallDetails Os detalhes da chamada de ferramenta
agent_details Obrigatório	AgentDetails Os detalhes do agente que está fazendo a chamada
user_details	UserDetails \| None Detalhes opcionais do usuário humano Valor padrão: None
span_details	SpanDetails \| None Configuração de intervalo opcional (contexto pai, tempo, tipo) Valor padrão: None

new

__new__(**kwargs)

dispose

Descarte o escopo e finalize a coleta de dados de telemetria.

dispose() -> None

Retornos

Tipo	Description
None

get_context

Obtenha o contexto OpenTelemetry para o intervalo desse escopo.

Esse método retorna um objeto Context que contém o intervalo desse escopo, que pode ser usado para propagar o contexto de rastreamento para operações filho ou serviços downstream.

get_context() -> Context | None

Retornos

Tipo	Description
Context \| None	Um contexto que contém o intervalo desse escopo ou Nenhum se a telemetria estiver desabilitada ou nenhum intervalo existir.

inject_context_to_headers

Injete o contexto de rastreamento desse intervalo em cabeçalhos HTTP W3C.

Retorna um dicionário de cabeçalhos que contém traceparent e, opcionalmente tracestate , que podem ser encaminhados para serviços downstream ou armazenados para propagação de contexto posterior.

Exemplo de uso:


   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]

Retornos

Tipo	Description
dict[str, str]	Um dicionário que contém cabeçalhos de contexto de rastreamento W3C. Retorna um dicionário vazio se a telemetria estiver desabilitada ou se não houver intervalo.

record_attributes

Registre vários pares de chave/valor de atributo para acompanhamento de telemetria.

Esse método permite definir vários atributos personalizados no intervalo de uma só vez.

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

Parâmetros

Nome	Description
attributes Obrigatório	dict[str, Any] \| list[tuple[str, Any]] Dicionário ou lista de tuplas que contêm pares chave-valor de atributo. As chaves que são Nenhuma ou vazias serão ignoradas.

Retornos

Tipo	Description
None

record_cancellation

Registrar cancelamento de tarefa.

record_cancellation() -> None

Retornos

Tipo	Description
None

record_error

Registre um erro no intervalo.

record_error(exception: Exception) -> None

Parâmetros

Nome	Description
exception Obrigatório	Exception A exceção que ocorreu

Retornos

Tipo	Description
None

record_response

Registre o resultado da chamada da ferramenta para o acompanhamento de telemetria.

Por especificação OTEL, espera-se que o resultado seja um objeto. Se uma cadeia de caracteres for fornecida, ela será registrada as-is (fallback da cadeia de caracteres JSON). Se um ditado for fornecido, ele será serializado para JSON.

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

Parâmetros

Nome	Description
result Obrigatório	dict[str, object] \| str Resultado da chamada de ferramenta como um ditado estruturado ou cadeia de caracteres JSON

Retornos

Tipo	Description
None

set_end_time

Defina uma hora de término personalizada para o escopo.

Quando definido, dispose() passará esse valor para span.end() em vez de usar o tempo atual do relógio de parede. Isso é útil quando a hora de término real da operação é conhecida antes de o escopo ser descartado.

set_end_time(end_time: datetime) -> None

Parâmetros

Nome	Description
end_time Obrigatório	datetime A hora de término como um objeto datetime.

Retornos

Tipo	Description
None

set_tag_maybe

Defina uma marca no intervalo se o valor não for Nenhum.

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

Parâmetros

Nome	Description
name Obrigatório	str O nome da marca
value Obrigatório	Any O valor a ser definido (será ignorado se Nenhum)

Retornos

Tipo	Description
None

start

Cria e inicia um novo escopo para rastreamento de execução de ferramentas.

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

Parâmetros

Nome	Description
request Obrigatório	Request Solicitar detalhes para a execução da ferramenta
details Obrigatório	ToolCallDetails Os detalhes da chamada de ferramenta
agent_details Obrigatório	AgentDetails Os detalhes do agente que está fazendo a chamada
user_details	UserDetails \| None Detalhes opcionais do usuário humano Valor padrão: None
span_details	SpanDetails \| None Configuração de intervalo opcional (contexto pai, tempo, tipo) Valor padrão: None

Retornos

Tipo	Description
ExecuteToolScope	Uma nova instância executeToolScope