Skip to content

Commit 93ebe1e

Browse files
committed
fix: make usage-less request accounting internal and visible in tracing
Two follow-ups from review. Rename `mark_request_completed_without_usage` and `requests_for_response_without_usage` to underscore-prefixed helpers. They are adapter and run-loop plumbing rather than supported `agents.usage` API, so they should not create an accidental public contract. Also record the request in the generation span, not only in the run result. Non-streaming already writes a span usage object with `requests: 1` when the provider reports no usage, but the streaming paths populated span usage only when the terminal response carried a usage payload. A streamed run therefore reported one request while its model span omitted the request entirely. The OpenAI Chat Completions, LiteLLM and AnyLLM chat spans now fall back to a shared `_span_usage_without_provider_totals()`, so streamed and non-streaming tracing agree. Token totals stay at zero, since the provider reported none.
1 parent 7b52a69 commit 93ebe1e

8 files changed

Lines changed: 98 additions & 15 deletions

File tree

‎src/agents/extensions/models/any_llm_model.py‎

Lines changed: 8 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -56,8 +56,10 @@
5656
Usage,
5757
_attach_raw_usage_snapshot,
5858
_extract_raw_usage_snapshot,
59+
_mark_request_completed_without_usage,
5960
_raw_usage_snapshot,
60-
mark_request_completed_without_usage,
61+
_requests_for_response_without_usage,
62+
_span_usage_without_provider_totals,
6163
)
6264
from ...util._error_tracing import model_span_errors, record_model_error_on_span
6365
from ...util._json import _to_dump_compatible
@@ -487,7 +489,7 @@ async def _stream_response_via_responses(
487489
# Match the non-streaming path: the request happened even though
488490
# the provider reported no usage. Recorded without synthesizing a
489491
# usage payload, so tokens are not reported as real zeros.
490-
mark_request_completed_without_usage(final_response)
492+
_mark_request_completed_without_usage(final_response)
491493
elif chunk_type in {"response.failed", "response.incomplete"}:
492494
terminal_response = getattr(chunk, "response", None)
493495
terminal_failure_error = response_terminal_failure_error(
@@ -791,6 +793,10 @@ def _populate_chat_generation_span(
791793
else {"reasoning_tokens": 0}
792794
),
793795
}
796+
elif _requests_for_response_without_usage(final_response):
797+
# Keep streamed tracing aligned with the non-streaming path, which records the
798+
# request even when the provider reports no usage.
799+
span_generation.span_data.usage = _span_usage_without_provider_totals()
794800

795801
@overload
796802
async def _fetch_chat_response(

‎src/agents/extensions/models/litellm_model.py‎

Lines changed: 13 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -58,7 +58,13 @@
5858
from ...tracing import generation_span
5959
from ...tracing.span_data import GenerationSpanData
6060
from ...tracing.spans import Span
61-
from ...usage import Usage, _cache_write_tokens, _make_input_tokens_details
61+
from ...usage import (
62+
Usage,
63+
_cache_write_tokens,
64+
_make_input_tokens_details,
65+
_requests_for_response_without_usage,
66+
_span_usage_without_provider_totals,
67+
)
6268
from ...util._error_tracing import model_span_errors
6369
from ...util._json import _to_dump_compatible
6470

@@ -465,6 +471,12 @@ async def stream_response(
465471
else {"reasoning_tokens": 0}
466472
),
467473
}
474+
elif final_response is not None and _requests_for_response_without_usage(
475+
final_response
476+
):
477+
# Keep streamed tracing aligned with the non-streaming path, which records the
478+
# request even when the provider reports no usage.
479+
span_generation.span_data.usage = _span_usage_without_provider_totals()
468480

469481
@overload
470482
async def _fetch_response(

‎src/agents/models/chatcmpl_stream_handler.py‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -56,7 +56,7 @@
5656
_cache_write_tokens,
5757
_extract_raw_usage_snapshot,
5858
_make_input_tokens_details,
59-
mark_request_completed_without_usage,
59+
_mark_request_completed_without_usage,
6060
)
6161
from .chatcmpl_helpers import ChatCmplHelpers
6262
from .fake_id import FAKE_RESPONSES_ID
@@ -1290,7 +1290,7 @@ async def handle_stream(
12901290
# The stream reached a terminal response, so a request was made even though the
12911291
# provider reported no usage. Record that without inventing a usage payload, so
12921292
# the raw usage snapshot stays absent and tokens are not reported as real zeros.
1293-
mark_request_completed_without_usage(final_response)
1293+
_mark_request_completed_without_usage(final_response)
12941294

12951295
yield ResponseCompletedEvent(
12961296
response=final_response,

‎src/agents/models/openai_chatcompletions.py‎

Lines changed: 12 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -31,7 +31,12 @@
3131
from ..tracing import generation_span
3232
from ..tracing.span_data import GenerationSpanData
3333
from ..tracing.spans import Span
34-
from ..usage import Usage, _raw_usage_snapshot
34+
from ..usage import (
35+
Usage,
36+
_raw_usage_snapshot,
37+
_requests_for_response_without_usage,
38+
_span_usage_without_provider_totals,
39+
)
3540
from ..util._error_tracing import model_span_errors
3641
from ..util._json import _to_dump_compatible
3742
from ._openai_retry import get_openai_retry_advice
@@ -506,6 +511,12 @@ async def stream_response(
506511
else {"reasoning_tokens": 0}
507512
),
508513
}
514+
elif final_response is not None and _requests_for_response_without_usage(
515+
final_response
516+
):
517+
# Keep streamed tracing aligned with the non-streaming path, which records the
518+
# request even when the provider reports no usage.
519+
span_generation.span_data.usage = _span_usage_without_provider_totals()
509520

510521
def _handle_unsupported_server_managed_conversation_state(
511522
self,

‎src/agents/run_internal/run_loop.py‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -82,8 +82,8 @@
8282
from ..usage import (
8383
Usage,
8484
_extract_raw_usage_snapshot,
85+
_requests_for_response_without_usage,
8586
_response_usage_to_usage,
86-
requests_for_response_without_usage,
8787
)
8888
from ..util import _coro, _error_tracing
8989
from ..util._asyncio_tasks import gather_with_cancel
@@ -1732,7 +1732,7 @@ async def rewind_model_request() -> None:
17321732
if terminal_response.usage
17331733
# Defaults to zero requests, so adapters that fold several provider
17341734
# responses into one and report counts separately are not double-counted.
1735-
else Usage(requests=requests_for_response_without_usage(terminal_response))
1735+
else Usage(requests=_requests_for_response_without_usage(terminal_response))
17361736
),
17371737
stream_failed_retry_attempts[0],
17381738
)

‎src/agents/usage.py‎

Lines changed: 18 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -313,7 +313,7 @@ def add(self, other: Usage) -> None:
313313
_REQUEST_WITHOUT_USAGE_ATTR = "_agents_sdk_request_completed_without_usage"
314314

315315

316-
def mark_request_completed_without_usage(response: Any) -> None:
316+
def _mark_request_completed_without_usage(response: Any) -> None:
317317
"""Record that a response completed even though the provider reported no usage.
318318
319319
Adapters call this instead of synthesizing a zero-filled usage payload, so the raw
@@ -322,7 +322,23 @@ def mark_request_completed_without_usage(response: Any) -> None:
322322
object.__setattr__(response, _REQUEST_WITHOUT_USAGE_ATTR, True)
323323

324324

325-
def requests_for_response_without_usage(response: Any) -> int:
325+
def _span_usage_without_provider_totals() -> dict[str, Any]:
326+
"""Span usage for a response that completed without any provider usage payload.
327+
328+
The request is recorded so streamed and non-streaming tracing agree, while every token
329+
total stays at zero because the provider genuinely reported none.
330+
"""
331+
return {
332+
"requests": 1,
333+
"input_tokens": 0,
334+
"output_tokens": 0,
335+
"total_tokens": 0,
336+
"input_tokens_details": {"cached_tokens": 0, "cache_write_tokens": 0},
337+
"output_tokens_details": {"reasoning_tokens": 0},
338+
}
339+
340+
341+
def _requests_for_response_without_usage(response: Any) -> int:
326342
"""How many requests a usage-less response represents.
327343
328344
Defaults to zero so adapters that multiplex several provider responses into one

‎tests/models/test_any_llm_model.py‎

Lines changed: 4 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -1957,13 +1957,13 @@ async def response_stream() -> AsyncIterator[ResponseCompletedEvent]:
19571957
)
19581958
]
19591959

1960-
from agents.usage import requests_for_response_without_usage
1960+
from agents.usage import _requests_for_response_without_usage
19611961

19621962
terminal = events[-1]
19631963
assert isinstance(terminal, ResponseCompletedEvent)
19641964
# No usage payload is synthesized, so token counts are not reported as real zeros.
19651965
assert terminal.response.usage is None
1966-
assert requests_for_response_without_usage(terminal.response) == 1
1966+
assert _requests_for_response_without_usage(terminal.response) == 1
19671967

19681968

19691969
@pytest.mark.allow_call_model_methods
@@ -1995,9 +1995,9 @@ async def response_stream() -> AsyncIterator[ResponseCompletedEvent]:
19951995
)
19961996
]
19971997

1998-
from agents.usage import requests_for_response_without_usage
1998+
from agents.usage import _requests_for_response_without_usage
19991999

20002000
terminal = events[-1]
20012001
assert isinstance(terminal, ResponseCompletedEvent)
20022002
assert terminal.response.usage is not None
2003-
assert requests_for_response_without_usage(terminal.response) == 0
2003+
assert _requests_for_response_without_usage(terminal.response) == 0

‎tests/models/test_openai_chatcompletions_stream.py‎

Lines changed: 39 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -34,7 +34,7 @@
3434
ResponseReasoningItem,
3535
)
3636

37-
from agents import Agent, Runner, function_tool
37+
from agents import Agent, Runner, function_tool, trace
3838
from agents.exceptions import ModelBehaviorError, UserError
3939
from agents.model_settings import ModelSettings
4040
from agents.models.chatcmpl_converter import Converter
@@ -50,6 +50,7 @@
5050
from agents.models.interface import ModelTracing
5151
from agents.models.openai_chatcompletions import OpenAIChatCompletionsModel
5252
from agents.models.openai_provider import OpenAIProvider
53+
from tests.testing_processor import fetch_ordered_spans
5354
from tests.utils.simple_session import SimpleListSession
5455

5556

@@ -3995,3 +3996,40 @@ async def test_streamed_run_does_not_double_count_when_usage_is_present(monkeypa
39953996

39963997
assert result.context_wrapper.usage.requests == 1
39973998
assert result.context_wrapper.usage.total_tokens == 12
3999+
4000+
4001+
@pytest.mark.allow_call_model_methods
4002+
@pytest.mark.asyncio
4003+
async def test_streamed_span_records_the_request_when_provider_omits_usage(monkeypatch) -> None:
4004+
"""Streamed tracing must record the request the same way the non-streaming path does.
4005+
4006+
Non-streaming writes a span usage object with `requests: 1` when the provider reports no
4007+
usage. Streaming used to omit span usage entirely, so the run reported one request while
4008+
the model span showed none.
4009+
"""
4010+
monkeypatch.setattr(
4011+
OpenAIChatCompletionsModel, "_fetch_response", _usageless_stream_patch(usage=None)
4012+
)
4013+
model = OpenAIProvider(use_responses=False).get_model("gpt-4")
4014+
4015+
with trace(workflow_name="test"):
4016+
async for _ in model.stream_response(
4017+
system_instructions=None,
4018+
input="",
4019+
model_settings=ModelSettings(),
4020+
tools=[],
4021+
output_schema=None,
4022+
handoffs=[],
4023+
tracing=ModelTracing.ENABLED,
4024+
previous_response_id=None,
4025+
conversation_id=None,
4026+
prompt=None,
4027+
):
4028+
pass
4029+
4030+
spans = fetch_ordered_spans()
4031+
generation = next(s for s in spans if s.span_data.type == "generation")
4032+
assert generation.span_data.usage is not None
4033+
assert generation.span_data.usage["requests"] == 1
4034+
# The provider reported no tokens, so every total stays at zero.
4035+
assert generation.span_data.usage["total_tokens"] == 0

0 commit comments

Comments
 (0)