Skip to content

armgit / camel

Public Imported from GitHub
0

🐫 CAMEL: The first and the best multi-agent framework. Finding the Scaling Law of Agents. https://www.camel-ai.org

feat:add_request_level_token_callback (#3872)

Tao Sun6fa116f91d80
diff --git a/camel/agents/chat_agent.py b/camel/agents/chat_agent.py
index 537df6bea..1bc6921c0 100644
--- a/camel/agents/chat_agent.py
+++ b/camel/agents/chat_agent.py
@@ -452,6 +452,12 @@ class ChatAgent(BaseAgent):
step_timeout (Optional[float], optional): Timeout in seconds for the
entire step operation. If None, no timeout is applied.
(default: :obj:`None`)
+ on_request_usage (Optional[Callable[[Dict[str, Any]], Any]],
+ optional): Callback triggered after each LLM request completes.
+ Useful for real-time token metering within a single step loop.
+ The callback receives a payload with per-request usage and
+ cumulative step usage.
+ (default: :obj:`None`)
stream_accumulate (Optional[bool], optional): When True, partial
streaming updates return accumulated content. When False, partial
updates return only the incremental delta (recommended).
@@ -507,6 +513,7 @@ class ChatAgent(BaseAgent):
retry_attempts: int = 3,
retry_delay: float = 1.0,
step_timeout: Optional[float] = Constants.TIMEOUT_THRESHOLD,
+ on_request_usage: Optional[Callable[[Dict[str, Any]], Any]] = None,
stream_accumulate: Optional[bool] = None,
summary_window_ratio: float = 0.6,
) -> None:
@@ -619,6 +626,7 @@ class ChatAgent(BaseAgent):
self.retry_attempts = max(1, retry_attempts)
self.retry_delay = max(0.0, retry_delay)
self.step_timeout = step_timeout
+ self.on_request_usage = on_request_usage
self._context_utility: Optional[ContextUtility] = None
self._context_summary_agent: Optional["ChatAgent"] = None
@@ -1811,6 +1819,7 @@ class ChatAgent(BaseAgent):
agent_id=f"{self.agent_id}_context_summarizer",
token_limit=self.token_limit,
summarize_threshold=None,
+ on_request_usage=self.on_request_usage,
)
else:
self._context_summary_agent.reset()
@@ -2104,6 +2113,7 @@ class ChatAgent(BaseAgent):
agent_id=f"{self.agent_id}_context_summarizer",
token_limit=self.token_limit,
summarize_threshold=None,
+ on_request_usage=self.on_request_usage,
)
else:
self._context_summary_agent.reset()
@@ -2249,6 +2259,7 @@ class ChatAgent(BaseAgent):
agent_id=f"{self.agent_id}_context_summarizer",
token_limit=self.token_limit,
summarize_threshold=None,
+ on_request_usage=self.on_request_usage,
)
else:
self._context_summary_agent.reset()
@@ -2960,6 +2971,12 @@ class ChatAgent(BaseAgent):
self._update_token_usage_tracker(
step_token_usage, response.usage_dict
)
+ self._emit_request_usage(
+ usage_dict=response.usage_dict,
+ step_usage=step_token_usage.copy(),
+ request_index=iteration_count,
+ response_id=response.response_id,
+ )
# Update token cache from LLM response
self._update_token_cache(response.usage_dict, len(openai_messages))
@@ -3259,6 +3276,12 @@ class ChatAgent(BaseAgent):
self._update_token_usage_tracker(
step_token_usage, response.usage_dict
)
+ await self._aemit_request_usage(
+ usage_dict=response.usage_dict,
+ step_usage=step_token_usage.copy(),
+ request_index=iteration_count,
+ response_id=response.response_id,
+ )
# Update token cache from LLM response
self._update_token_cache(response.usage_dict, len(openai_messages))
@@ -3424,6 +3447,83 @@ class ChatAgent(BaseAgent):
)
tracker["total_tokens"] += usage_dict.get("total_tokens") or 0
+ def _emit_request_usage(
+ self,
+ usage_dict: Dict[str, Any],
+ step_usage: Dict[str, int],
+ request_index: int,
+ response_id: str,
+ ) -> None:
+ if self.on_request_usage is None:
+ return
+
+ payload = self._build_request_usage_payload(
+ usage_dict=usage_dict,
+ step_usage=step_usage,
+ request_index=request_index,
+ response_id=response_id,
+ )
+ try:
+ callback_result = self.on_request_usage(payload)
+ if inspect.isawaitable(callback_result):
+ logger.warning(
+ "on_request_usage returned awaitable in sync step. "
+ "Use a sync callback for `step`, or use `astep`."
+ )
+ if inspect.iscoroutine(callback_result):
+ callback_result.close()
+ except Exception as exc:
+ logger.warning(
+ f"on_request_usage callback failed at request "
+ f"{request_index}: {exc}"
+ )
+
+ async def _aemit_request_usage(
+ self,
+ usage_dict: Dict[str, Any],
+ step_usage: Dict[str, int],
+ request_index: int,
+ response_id: str,
+ ) -> None:
+ if self.on_request_usage is None:
+ return
+
+ payload = self._build_request_usage_payload(
+ usage_dict=usage_dict,
+ step_usage=step_usage,
+ request_index=request_index,
+ response_id=response_id,
+ )
+ try:
+ callback_result = self.on_request_usage(payload)
+ if inspect.isawaitable(callback_result):
+ await callback_result
+ except Exception as exc:
+ logger.warning(
+ f"on_request_usage callback failed at request "
+ f"{request_index}: {exc}"
+ )
+
+ def _build_request_usage_payload(
+ self,
+ usage_dict: Dict[str, Any],
+ step_usage: Dict[str, int],
+ request_index: int,
+ response_id: str,
+ ) -> Dict[str, Any]:
+ usage = usage_dict or {}
+ return {
+ "agent_id": self.agent_id,
+ "request_index": request_index,
+ "response_id": response_id,
+ "request_usage": {
+ "prompt_tokens": int(usage.get("prompt_tokens") or 0),
+ "completion_tokens": int(usage.get("completion_tokens") or 0),
+ "total_tokens": int(usage.get("total_tokens") or 0),
+ },
+ "step_usage": step_usage,
+ }
+
def _convert_to_chatagent_response(
self,
response: ModelResponse,
@@ -4317,17 +4417,26 @@ class ChatAgent(BaseAgent):
and not isinstance(response, ChatCompletion)
)
):
+ request_token_usage = self._create_token_usage_tracker()
(
stream_completed,
tool_calls_complete,
+ request_response_id,
) = yield from self._process_stream_chunks_with_accumulator(
response, # type: ignore[arg-type]
content_accumulator,
accumulated_tool_calls,
tool_call_records,
+ request_token_usage,
step_token_usage,
response_format,
)
+ self._emit_request_usage(
+ usage_dict=request_token_usage,
+ step_usage=step_token_usage.copy(),
+ request_index=iteration_count,
+ response_id=request_response_id,
+ )
if tool_calls_complete:
# Clear completed tool calls
@@ -4363,6 +4472,7 @@ class ChatAgent(BaseAgent):
elif hasattr(response, '__enter__') and not hasattr(
response, '__iter__'
):
+ request_token_usage = self._create_token_usage_tracker()
# Handle structured output stream (ChatCompletionStreamManager)
# This catches context managers that aren't iterators
with response as stream: # type: ignore[union-attr]
@@ -4419,17 +4529,27 @@ class ChatAgent(BaseAgent):
self.record_message(final_message)
- # Create final response
+ request_usage = (
+ safe_model_dump(final_completion.usage)
+ if final_completion.usage
+ else {}
+ )
+ self._update_token_usage_tracker(
+ request_token_usage,
+ request_usage,
+ )
+ self._update_token_usage_tracker(
+ step_token_usage,
+ request_usage,
+ )
+
+ # Create final response with cumulative step usage.
final_response = ChatAgentResponse(
msgs=[final_message],
terminated=False,
info={
"id": final_completion.id or "",
- "usage": safe_model_dump(
- final_completion.usage
- )
- if final_completion.usage
- else {},
+ "usage": step_token_usage.copy(),
"finish_reasons": [
choice.finish_reason or "stop"
for choice in final_completion.choices
@@ -4443,6 +4563,12 @@ class ChatAgent(BaseAgent):
"partial": False,
},
)
+ self._emit_request_usage(
+ usage_dict=request_token_usage,
+ step_usage=step_token_usage.copy(),
+ request_index=iteration_count,
+ response_id=final_completion.id or "",
+ )
yield final_response
break
@@ -4457,14 +4583,23 @@ class ChatAgent(BaseAgent):
model_response = self._handle_batch_response(
response # type: ignore[arg-type]
)
+ self._update_token_usage_tracker(
+ step_token_usage, model_response.usage_dict
+ )
+ self._emit_request_usage(
+ usage_dict=model_response.usage_dict,
+ step_usage=step_token_usage.copy(),
+ request_index=iteration_count,
+ response_id=model_response.response_id,
+ )
yield self._convert_to_chatagent_response(
model_response,
tool_call_records,
num_tokens,
None,
- model_response.usage_dict.get("prompt_tokens", 0),
- model_response.usage_dict.get("completion_tokens", 0),
- model_response.usage_dict.get("total_tokens", 0),
+ step_token_usage["prompt_tokens"],
+ step_token_usage["completion_tokens"],
+ step_token_usage["total_tokens"],
)
accumulated_tool_calls.clear()
break
@@ -4475,15 +4610,18 @@ class ChatAgent(BaseAgent):
content_accumulator: StreamContentAccumulator,
accumulated_tool_calls: Dict[str, Any],
tool_call_records: List[ToolCallingRecord],
+ request_token_usage: Dict[str, int],
step_token_usage: Dict[str, int],
response_format: Optional[Type[BaseModel]] = None,
- ) -> Generator[ChatAgentResponse, None, Tuple[bool, bool]]:
+ ) -> Generator[ChatAgentResponse, None, Tuple[bool, bool, str]]:
r"""Process streaming chunks with content accumulator."""
tool_calls_complete = False
stream_completed = False
+ last_response_id = ""
for chunk in stream:
+ last_response_id = getattr(chunk, 'id', '') or last_response_id
has_choices = bool(chunk.choices and len(chunk.choices) > 0)
# Process chunk delta
@@ -4590,6 +4728,9 @@ class ChatAgent(BaseAgent):
# Handle final usage chunk, whether or not choices are present.
# This happens when stream_options={"include_usage": True}
# Update the final usage from this chunk
+ self._update_token_usage_tracker(
+ request_token_usage, safe_model_dump(chunk.usage)
+ )
self._update_token_usage_tracker(
step_token_usage, safe_model_dump(chunk.usage)
)
@@ -4658,7 +4799,7 @@ class ChatAgent(BaseAgent):
# consuming remaining chunks to capture final metadata.
continue
- return stream_completed, tool_calls_complete
+ return stream_completed, tool_calls_complete, last_response_id
def _accumulate_tool_calls(
self,
@@ -5264,8 +5405,10 @@ class ChatAgent(BaseAgent):
and not isinstance(response, ChatCompletion)
)
):
+ request_token_usage = self._create_token_usage_tracker()
stream_completed = False
tool_calls_complete = False
+ request_response_id = ""
# Process chunks and forward them
async for (
@@ -5275,17 +5418,28 @@ class ChatAgent(BaseAgent):
content_accumulator,
accumulated_tool_calls,
tool_call_records,
+ request_token_usage,
step_token_usage,
response_format,
):
if isinstance(item, tuple):
- # This is the final return value (stream_completed,
- # tool_calls_complete)
- stream_completed, tool_calls_complete = item
+ # This is the final return value
+ # (stream_completed, tool_calls_complete, response_id)
+ (
+ stream_completed,
+ tool_calls_complete,
+ request_response_id,
+ ) = item
break
else:
# This is a ChatAgentResponse to be yielded
yield item
+ await self._aemit_request_usage(
+ usage_dict=request_token_usage,
+ step_usage=step_token_usage.copy(),
+ request_index=iteration_count,
+ response_id=request_response_id,
+ )
if tool_calls_complete:
# Clear completed tool calls
@@ -5321,6 +5475,7 @@ class ChatAgent(BaseAgent):
elif hasattr(response, '__aenter__') and not hasattr(
response, '__aiter__'
):
+ request_token_usage = self._create_token_usage_tracker()
# Handle structured output stream
# (AsyncChatCompletionStreamManager)
# Catches async context managers that aren't async iterators
@@ -5378,17 +5533,27 @@ class ChatAgent(BaseAgent):
self.record_message(final_message)
- # Create final response
+ request_usage = (
+ safe_model_dump(final_completion.usage)
+ if final_completion.usage
+ else {}
+ )
+ self._update_token_usage_tracker(
+ request_token_usage,
+ request_usage,
+ )
+ self._update_token_usage_tracker(
+ step_token_usage,
+ request_usage,
+ )
+
+ # Create final response with cumulative step usage.
final_response = ChatAgentResponse(
msgs=[final_message],
terminated=False,
info={
"id": final_completion.id or "",
- "usage": safe_model_dump(
- final_completion.usage
- )
- if final_completion.usage
- else {},
+ "usage": step_token_usage.copy(),
"finish_reasons": [
choice.finish_reason or "stop"
for choice in final_completion.choices
@@ -5402,6 +5567,12 @@ class ChatAgent(BaseAgent):
"partial": False,
},
)
+ await self._aemit_request_usage(
+ usage_dict=request_token_usage,
+ step_usage=step_token_usage.copy(),
+ request_index=iteration_count,
+ response_id=final_completion.id or "",
+ )
yield final_response
break
@@ -5418,14 +5589,23 @@ class ChatAgent(BaseAgent):
model_response = self._handle_batch_response(
response # type: ignore[arg-type]
)
+ self._update_token_usage_tracker(
+ step_token_usage, model_response.usage_dict
+ )
+ await self._aemit_request_usage(
+ usage_dict=model_response.usage_dict,
+ step_usage=step_token_usage.copy(),
+ request_index=iteration_count,
+ response_id=model_response.response_id,
+ )
yield self._convert_to_chatagent_response(
model_response,
tool_call_records,
num_tokens,
None,
- model_response.usage_dict.get("prompt_tokens", 0),
- model_response.usage_dict.get("completion_tokens", 0),
- model_response.usage_dict.get("total_tokens", 0),
+ step_token_usage["prompt_tokens"],
+ step_token_usage["completion_tokens"],
+ step_token_usage["total_tokens"],
)
accumulated_tool_calls.clear()
break
@@ -5530,17 +5710,22 @@ class ChatAgent(BaseAgent):
content_accumulator: StreamContentAccumulator,
accumulated_tool_calls: Dict[str, Any],
tool_call_records: List[ToolCallingRecord],
+ request_token_usage: Dict[str, int],
step_token_usage: Dict[str, int],
response_format: Optional[Type[BaseModel]] = None,
- ) -> AsyncGenerator[Union[ChatAgentResponse, Tuple[bool, bool]], None]:
+ ) -> AsyncGenerator[
+ Union[ChatAgentResponse, Tuple[bool, bool, str]], None
+ ]:
r"""Async version of process streaming chunks with
content accumulator.
"""
tool_calls_complete = False
stream_completed = False
+ last_response_id = ""
async for chunk in stream:
+ last_response_id = getattr(chunk, 'id', '') or last_response_id
has_choices = bool(chunk.choices and len(chunk.choices) > 0)
# Process chunk delta
@@ -5649,6 +5834,9 @@ class ChatAgent(BaseAgent):
# Handle final usage chunk, whether or not choices are present.
# This happens when stream_options={"include_usage": True}
# Update the final usage from this chunk
+ self._update_token_usage_tracker(
+ request_token_usage, safe_model_dump(chunk.usage)
+ )
self._update_token_usage_tracker(
step_token_usage, safe_model_dump(chunk.usage)
)
@@ -5716,7 +5904,7 @@ class ChatAgent(BaseAgent):
continue
# Yield the final status as a tuple
- yield (stream_completed, tool_calls_complete)
+ yield (stream_completed, tool_calls_complete, last_response_id)
async def _execute_tools_async_with_status_accumulator(
self,
@@ -5944,6 +6132,7 @@ class ChatAgent(BaseAgent):
tool_execution_timeout=self.tool_execution_timeout,
pause_event=self.pause_event,
prune_tool_calls_from_memory=self.prune_tool_calls_from_memory,
+ on_request_usage=self.on_request_usage,
stream_accumulate=self.stream_accumulate,
)
diff --git a/examples/agents/chatagent_request_usage_callback.py b/examples/agents/chatagent_request_usage_callback.py
new file mode 100644
index 000000000..b8db03d48
--- /dev/null
+++ b/examples/agents/chatagent_request_usage_callback.py
@@ -0,0 +1,105 @@
+# ========= Copyright 2023-2026 @ CAMEL-AI.org. All Rights Reserved. =========
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+# http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+# ========= Copyright 2023-2026 @ CAMEL-AI.org. All Rights Reserved. =========
+
+from camel.agents import ChatAgent
+from camel.models import ModelFactory
+from camel.toolkits import MathToolkit
+from camel.types import ModelPlatformType, ModelType
+
+
+def on_request_usage(payload: dict) -> None:
+ r"""Callback invoked after each LLM request."""
+ request_usage = payload["request_usage"]
+ step_usage = payload["step_usage"]
+ print(
+ f"[request {payload['request_index']}] "
+ f"response_id={payload['response_id']} "
+ f"request_total_tokens={request_usage['total_tokens']} "
+ f"step_total_tokens={step_usage['total_tokens']}"
+ )
+
+
+model = ModelFactory.create(
+ model_platform=ModelPlatformType.DEFAULT,
+ model_type=ModelType.DEFAULT,
+)
+
+agent = ChatAgent(
+ system_message=(
+ "You are a helpful math assistant. "
+ "Always use tools for arithmetic before giving the final answer."
+ ),
+ model=model,
+ tools=MathToolkit().get_tools(),
+ on_request_usage=on_request_usage,
+)
+
+response = agent.step("Calculate 123 + 456, then multiply the result by 2.")
+print("\nFinal answer:")
+print(response.msg.content)
+print("\nStep usage:")
+print(response.info.get("usage"))
+
+# Streaming mode (request-level usage callback is also supported)
+stream_model = ModelFactory.create(
+ model_platform=ModelPlatformType.DEFAULT,
+ model_type=ModelType.DEFAULT,
+ model_config_dict={
+ "stream": True,
+ "stream_options": {"include_usage": True},
+ },
+)
+
+stream_agent = ChatAgent(
+ system_message="You are a concise assistant.",
+ model=stream_model,
+ on_request_usage=on_request_usage,
+ stream_accumulate=False,
+)
+
+print("\nStreaming output:")
+streaming_response = stream_agent.step("Write one short sentence about CAMEL.")
+for chunk in streaming_response:
+ if chunk.msg and chunk.msg.content:
+ print(chunk.msg.content, end="", flush=True)
+
+print("\n\nStreaming final usage:")
+print(streaming_response.info.get("usage"))
+
+'''
+===============================================================================
+[request 1] response_id=chatcmpl-DChD9WKCUdpDYfH6M5TOnWLrxaoTW
+request_total_tokens=437 step_total_tokens=437
+[request 2] response_id=chatcmpl-DChDA0sYqi9lHpRTy86SvSs339tQ9
+request_total_tokens=470 step_total_tokens=907
+[request 3] response_id=chatcmpl-DChDBFYQnSla6ZokAdbIzVA1Day0R
+request_total_tokens=519 step_total_tokens=1426
+
+Final answer:
+The result of 123 + 456 is 579. When you multiply that by 2,
+the final result is 1158.
+
+Step usage:
+{'prompt_tokens': 1346, 'completion_tokens': 80, 'total_tokens': 1426}
+
+Streaming output:
+CAMEL is a banking supervision rating system assessing Capital, Assets,
+Management, Earnings, and Liquidity.[request 1]
+response_id=chatcmpl-DDqxHJPO7XUGOiBQri65Wiv3f87KH
+request_total_tokens=46 step_total_tokens=46
+
+Streaming final usage:
+{'prompt_tokens': 25, 'completion_tokens': 21, 'total_tokens': 46}
+===============================================================================
+'''
diff --git a/test/agents/test_chat_agent.py b/test/agents/test_chat_agent.py
index 058db434a..1d771a74d 100644
--- a/test/agents/test_chat_agent.py
+++ b/test/agents/test_chat_agent.py
@@ -15,7 +15,7 @@ import asyncio
import json
from copy import deepcopy
from io import BytesIO
-from typing import List
+from typing import List, Literal
from unittest.mock import AsyncMock, MagicMock
import pytest
@@ -589,6 +589,351 @@ async def test_chat_agent_astep_with_external_tools(step_call_count=3):
), f"Error in calling round {i + 1}"
+def _mock_completion_with_usage(
+ response_id: str,
+ *,
+ finish_reason: Literal[
+ "stop", "length", "tool_calls", "content_filter", "function_call"
+ ],
+ content: str | None,
+ created: int,
+ prompt_tokens: int,
+ completion_tokens: int,
+ total_tokens: int,
+ tool_call: ChatCompletionMessageFunctionToolCall | None = None,
+) -> ChatCompletion:
+ return ChatCompletion(
+ id=response_id,
+ choices=[
+ Choice(
+ finish_reason=finish_reason,
+ index=0,
+ logprobs=None,
+ message=ChatCompletionMessage(
+ content=content,
+ role="assistant",
+ function_call=None,
+ tool_calls=[tool_call] if tool_call else None,
+ ),
+ )
+ ],
+ created=created,
+ model="gpt-5-mini",
+ object="chat.completion",
+ usage=CompletionUsage(
+ completion_tokens=completion_tokens,
+ prompt_tokens=prompt_tokens,
+ total_tokens=total_tokens,
+ ),
+ )
+
+
+def _assert_request_usage_event(
+ event: dict,
+ *,
+ request_index: int,
+ response_id: str,
+ request_total_tokens: int,
+ step_total_tokens: int,
+) -> None:
+ assert event["request_index"] == request_index
+ assert event["response_id"] == response_id
+ assert event["request_usage"]["total_tokens"] == request_total_tokens
+ assert event["step_usage"]["total_tokens"] == step_total_tokens
+
+
+def test_chat_agent_step_on_request_usage_callback():
+ model = ModelFactory.create(
+ model_platform=ModelPlatformType.OPENAI,
+ model_type=ModelType.GPT_5_MINI,
+ )
+
+ def add(a: int, b: int) -> int:
+ return a + b
+
+ request_events = []
+
+ first_response = _mock_completion_with_usage(
+ "mock_step_usage_1",
+ finish_reason="tool_calls",
+ content=None,
+ created=123456789,
+ prompt_tokens=10,
+ completion_tokens=3,
+ total_tokens=13,
+ tool_call=ChatCompletionMessageFunctionToolCall(
+ id="call_mock_add_1",
+ function=Function(arguments='{"a": 1, "b": 2}', name="add"),
+ type="function",
+ ),
+ )
+ second_response = _mock_completion_with_usage(
+ "mock_step_usage_2",
+ finish_reason="stop",
+ content="The result is 3.",
+ created=123456790,
+ prompt_tokens=20,
+ completion_tokens=4,
+ total_tokens=24,
+ )
+ model.run = MagicMock(side_effect=[first_response, second_response])
+
+ agent = ChatAgent(
+ system_message="You are a helpful assistant.",
+ model=model,
+ tools=[FunctionTool(add)],
+ on_request_usage=lambda payload: request_events.append(payload),
+ )
+ response = agent.step("Please add 1 and 2.")
+
+ assert len(request_events) == 2
+ _assert_request_usage_event(
+ request_events[0],
+ request_index=1,
+ response_id="mock_step_usage_1",
+ request_total_tokens=13,
+ step_total_tokens=13,
+ )
+ _assert_request_usage_event(
+ request_events[1],
+ request_index=2,
+ response_id="mock_step_usage_2",
+ request_total_tokens=24,
+ step_total_tokens=37,
+ )
+ assert response.info["usage"]["total_tokens"] == 37
+
+
+async def test_chat_agent_astep_on_request_usage_callback():
+ model = ModelFactory.create(
+ model_platform=ModelPlatformType.OPENAI,
+ model_type=ModelType.GPT_5_MINI,
+ )
+
+ def add(a: int, b: int) -> int:
+ return a + b
+
+ request_events = []
+
+ async def on_request_usage(payload):
+ request_events.append(payload)
+
+ first_response = _mock_completion_with_usage(
+ "mock_astep_usage_1",
+ finish_reason="tool_calls",
+ content=None,
+ created=123456791,
+ prompt_tokens=12,
+ completion_tokens=5,
+ total_tokens=17,
+ tool_call=ChatCompletionMessageFunctionToolCall(
+ id="call_mock_add_2",
+ function=Function(arguments='{"a": 2, "b": 3}', name="add"),
+ type="function",
+ ),
+ )
+ second_response = _mock_completion_with_usage(
+ "mock_astep_usage_2",
+ finish_reason="stop",
+ content="The result is 5.",
+ created=123456792,
+ prompt_tokens=18,
+ completion_tokens=6,
+ total_tokens=24,
+ )
+ model.arun = AsyncMock(side_effect=[first_response, second_response])
+
+ agent = ChatAgent(
+ system_message="You are a helpful assistant.",
+ model=model,
+ tools=[FunctionTool(add)],
+ on_request_usage=on_request_usage,
+ )
+ response = await agent.astep("Please add 2 and 3.")
+
+ assert len(request_events) == 2
+ _assert_request_usage_event(
+ request_events[0],
+ request_index=1,
+ response_id="mock_astep_usage_1",
+ request_total_tokens=17,
+ step_total_tokens=17,
+ )
+ _assert_request_usage_event(
+ request_events[1],
+ request_index=2,
+ response_id="mock_astep_usage_2",
+ request_total_tokens=24,
+ step_total_tokens=41,
+ )
+ assert response.info["usage"]["total_tokens"] == 41
+
+
+def test_chat_agent_stream_step_on_request_usage_callback():
+ from openai.types.chat.chat_completion_chunk import (
+ ChatCompletionChunk,
+ ChoiceDelta,
+ )
+ from openai.types.chat.chat_completion_chunk import (
+ Choice as ChunkChoice,
+ )
+
+ model = ModelFactory.create(
+ model_platform=ModelPlatformType.OPENAI,
+ model_type=ModelType.GPT_5_MINI,
+ model_config_dict={"stream": True},
+ )
+ request_events = []
+
+ chunks = [
+ ChatCompletionChunk(
+ id="mock_stream_usage_1",
+ choices=[
+ ChunkChoice(
+ delta=ChoiceDelta(content="Hello", role="assistant"),
+ index=0,
+ finish_reason=None,
+ )
+ ],
+ created=1234567890,
+ model="gpt-5-mini",
+ object="chat.completion.chunk",
+ ),
+ ChatCompletionChunk(
+ id="mock_stream_usage_1",
+ choices=[
+ ChunkChoice(
+ delta=ChoiceDelta(content=" world"),
+ index=0,
+ finish_reason="stop",
+ )
+ ],
+ created=1234567890,
+ model="gpt-5-mini",
+ object="chat.completion.chunk",
+ usage={
+ "prompt_tokens": 10,
+ "completion_tokens": 3,
+ "total_tokens": 13,
+ },
+ ),
+ ]
+
+ def mock_stream():
+ for chunk in chunks:
+ yield chunk
+
+ model.run = MagicMock(return_value=mock_stream())
+
+ agent = ChatAgent(
+ system_message="You are a helpful assistant.",
+ model=model,
+ on_request_usage=lambda payload: request_events.append(payload),
+ )
+
+ responses = list(agent.step("Say hello"))
+ assert len(responses) > 0
+ assert responses[-1].info["usage"]["total_tokens"] == 13
+ assert len(request_events) == 1
+ _assert_request_usage_event(
+ request_events[0],
+ request_index=1,
+ response_id="mock_stream_usage_1",
+ request_total_tokens=13,
+ step_total_tokens=13,
+ )
+
+
+async def test_chat_agent_async_stream_on_request_usage_callback():
+ from typing import AsyncGenerator
+
+ from openai.types.chat.chat_completion_chunk import (
+ ChatCompletionChunk,
+ ChoiceDelta,
+ )
+ from openai.types.chat.chat_completion_chunk import (
+ Choice as ChunkChoice,
+ )
+
+ model = ModelFactory.create(
+ model_platform=ModelPlatformType.OPENAI,
+ model_type=ModelType.GPT_5_MINI,
+ model_config_dict={"stream": True},
+ )
+ request_events = []
+
+ async def on_request_usage(payload):
+ request_events.append(payload)
+
+ chunks = [
+ ChatCompletionChunk(
+ id="mock_async_stream_usage_1",
+ choices=[
+ ChunkChoice(
+ delta=ChoiceDelta(content="Hello", role="assistant"),
+ index=0,
+ finish_reason=None,
+ )
+ ],
+ created=1234567890,
+ model="gpt-5-mini",
+ object="chat.completion.chunk",
+ ),
+ ChatCompletionChunk(
+ id="mock_async_stream_usage_1",
+ choices=[
+ ChunkChoice(
+ delta=ChoiceDelta(content=" world"),
+ index=0,
+ finish_reason="stop",
+ )
+ ],
+ created=1234567890,
+ model="gpt-5-mini",
+ object="chat.completion.chunk",
+ usage={
+ "prompt_tokens": 11,
+ "completion_tokens": 4,
+ "total_tokens": 15,
+ },
+ ),
+ ]
+
+ async def mock_async_stream() -> AsyncGenerator[ChatCompletionChunk, None]:
+ for chunk in chunks:
+ yield chunk
+
+ model.arun = AsyncMock(return_value=mock_async_stream())
+
+ agent = ChatAgent(
+ system_message="You are a helpful assistant.",
+ model=model,
+ on_request_usage=on_request_usage,
+ )
+
+ responses = []
+ streaming_response = await agent.astep("Say hello")
+ async for response in streaming_response:
+ responses.append(response)
+
+ assert len(responses) > 0
+ assert responses[-1].info["usage"]["total_tokens"] == 15
+ assert len(request_events) == 1
+ _assert_request_usage_event(
+ request_events[0],
+ request_index=1,
+ response_id="mock_async_stream_usage_1",
+ request_total_tokens=15,
+ step_total_tokens=15,
+ )
+
+
@pytest.mark.model_backend
def test_chat_agent_messages_window():
system_msg = BaseMessage(