Skip to content

Build and run agents you can see, understand and trust.

feat(msg): add usage field in Msg class to record the token usage (#1639)

qbc145bee0bd58f
diff --git a/src/agentscope/agent/_agent.py b/src/agentscope/agent/_agent.py
index c03f2cff4..a75331d33 100644
--- a/src/agentscope/agent/_agent.py
+++ b/src/agentscope/agent/_agent.py
@@ -70,6 +70,7 @@ from ..message import (
URLSource,
ToolCallState,
ToolResultState,
+ Usage,
)
from ..tool import (
Toolkit,
@@ -737,10 +738,20 @@ class Agent:
if not any(
isinstance(_, ToolCallBlock) for _ in completed_response.content
):
+ last_ctx = self._get_last_msg()
+ final_usage = (
+ Usage(
+ input_tokens=last_ctx.usage.input_tokens,
+ output_tokens=last_ctx.usage.output_tokens,
+ )
+ if last_ctx is not None and last_ctx.usage is not None
+ else None
+ )
yield AssistantMsg(
id=self.state.reply_id,
name=self.name,
content=list(completed_response.content),
+ usage=final_usage,
)
async def _check_incoming_event(
@@ -1984,7 +1995,7 @@ class Agent:
| ToolResultBlock
| DataBlock
],
- _usage: ChatUsage | None = None,
+ usage: ChatUsage | None = None,
) -> None:
"""Save content blocks into the context.
@@ -1992,12 +2003,22 @@ class Agent:
its id so that one reply corresponds to one message and the message
id matches the ``reply_id`` carried by streaming events.
"""
+ msg_usage = (
+ Usage(
+ input_tokens=usage.input_tokens,
+ output_tokens=usage.output_tokens,
+ )
+ if usage is not None
+ else None
+ )
+
if len(self.state.context) == 0:
self.state.context.append(
AssistantMsg(
id=self.state.reply_id,
name=self.name,
content=list(blocks),
+ usage=msg_usage,
),
)
else:
@@ -2006,13 +2027,19 @@ class Agent:
if isinstance(last_msg.content, str):
last_msg.content = [TextBlock(text=last_msg.content)]
last_msg.content.extend(blocks)
- # TODO: Merge usage if needed
+ if msg_usage is not None:
+ if last_msg.usage is None:
+ last_msg.usage = msg_usage
+ else:
+ last_msg.usage.input_tokens += msg_usage.input_tokens
+ last_msg.usage.output_tokens += msg_usage.output_tokens
else:
self.state.context.append(
AssistantMsg(
id=self.state.reply_id,
name=self.name,
content=list(blocks),
+ usage=msg_usage,
),
)
diff --git a/src/agentscope/message/__init__.py b/src/agentscope/message/__init__.py
index f27d4d2e5..ccc87602d 100644
--- a/src/agentscope/message/__init__.py
+++ b/src/agentscope/message/__init__.py
@@ -15,7 +15,7 @@ from ._block import (
Base64Source,
URLSource,
)
-from ._base import Msg, UserMsg, AssistantMsg, SystemMsg
+from ._base import Msg, UserMsg, AssistantMsg, SystemMsg, Usage
__all__ = [
@@ -35,4 +35,5 @@ __all__ = [
"UserMsg",
"AssistantMsg",
"SystemMsg",
+ "Usage",
]
diff --git a/src/agentscope/message/_base.py b/src/agentscope/message/_base.py
index 5fa1acf17..c68bb6ab7 100644
--- a/src/agentscope/message/_base.py
+++ b/src/agentscope/message/_base.py
@@ -53,6 +53,15 @@ def _to_blocks(content: str | list) -> list:
return content
+class Usage(BaseModel):
+ """The token usage information of a message."""
+
+ input_tokens: int
+ """The number of input tokens."""
+ output_tokens: int
+ """The number of output tokens."""
+
+
class Msg(BaseModel):
"""The message class in AgentScope, responsible for information storage
and transmission among different agents."""
@@ -71,6 +80,8 @@ class Msg(BaseModel):
"""The creation time of the message"""
finished_at: str | None = Field(default=None)
"""The finished time of the message"""
+ usage: Usage | None = Field(default=None)
+ """The token usage information of the message"""
@model_validator(mode="after")
def validate_role_content(self) -> Self:
@@ -199,7 +210,10 @@ class Msg(BaseModel):
def append_event(self, event: AgentEvent) -> Self:
"""Update the message by applying a streaming event.
- Only ``self.content`` and ``self.finished_at`` are ever modified.
+ Mutates ``self.content``, ``self.finished_at``, and ``self.usage``:
+ content blocks are appended/updated by block-level events,
+ ``finished_at`` is stamped by ``REPLY_END``, and ``usage`` is
+ initialized then accumulated across each ``MODEL_CALL_END``.
Events whose ``reply_id`` does not match ``self.id`` are skipped with
a warning. Block-level delta/end events whose target block cannot be
found are also skipped with a warning.
@@ -224,6 +238,16 @@ class Msg(BaseModel):
case EventType.REPLY_END:
self.finished_at = event.created_at
+ case EventType.MODEL_CALL_END:
+ if self.usage is None:
+ self.usage = Usage(
+ input_tokens=event.input_tokens,
+ output_tokens=event.output_tokens,
+ )
+ else:
+ self.usage.input_tokens += event.input_tokens
+ self.usage.output_tokens += event.output_tokens
+
case EventType.TEXT_BLOCK_START:
self.content.append(TextBlock(id=event.block_id, text=""))
@@ -459,6 +483,7 @@ def AssistantMsg(
created_at: str | None = None,
finished_at: str | None = None,
id: str | None = None, # pylint: disable=redefined-builtin
+ usage: Usage | None = None,
) -> Msg:
"""Create an assistant message with role ``"assistant"``.
@@ -481,6 +506,8 @@ def AssistantMsg(
id (`str | None`, optional):
A unique identifier for the message. A random UUID hex string is
generated when not provided.
+ usage (`Usage | None`, optional):
+ The token usage information of the message.
Returns:
`Msg`:
@@ -494,6 +521,7 @@ def AssistantMsg(
created_at=created_at or datetime.now().isoformat(),
finished_at=finished_at,
id=id or uuid.uuid4().hex,
+ usage=usage,
)
diff --git a/tests/agent_basic_test.py b/tests/agent_basic_test.py
index dda00369e..cd4e94173 100644
--- a/tests/agent_basic_test.py
+++ b/tests/agent_basic_test.py
@@ -124,6 +124,7 @@ class AgentBasicTest(IsolatedAsyncioTestCase):
"metadata": {},
"name": "Friday",
"role": "assistant",
+ "usage": None,
}
async def test_streaming_reasoning(self) -> None:
@@ -264,6 +265,7 @@ class AgentBasicTest(IsolatedAsyncioTestCase):
"finished_at": None,
"id": AnyString(),
"metadata": {},
+ "usage": None,
},
)
@@ -456,6 +458,7 @@ class AgentBasicTest(IsolatedAsyncioTestCase):
"finished_at": None,
"id": AnyString(),
"metadata": {},
+ "usage": None,
},
)
diff --git a/tests/compress_context_test.py b/tests/compress_context_test.py
index b006669ae..138329877 100644
--- a/tests/compress_context_test.py
+++ b/tests/compress_context_test.py
@@ -153,6 +153,7 @@ class ContextCompressionTest(IsolatedAsyncioTestCase):
},
],
"metadata": {},
+ "usage": None,
},
{
"id": "2",
@@ -168,6 +169,7 @@ class ContextCompressionTest(IsolatedAsyncioTestCase):
},
],
"metadata": {},
+ "usage": None,
},
],
)
@@ -188,6 +190,7 @@ class ContextCompressionTest(IsolatedAsyncioTestCase):
},
],
"metadata": {},
+ "usage": None,
},
{
"id": "3",
@@ -203,6 +206,7 @@ class ContextCompressionTest(IsolatedAsyncioTestCase):
},
],
"metadata": {},
+ "usage": None,
},
],
)
@@ -248,6 +252,7 @@ class ContextCompressionTest(IsolatedAsyncioTestCase):
},
],
"metadata": {},
+ "usage": None,
},
{
"id": "2",
@@ -268,6 +273,7 @@ class ContextCompressionTest(IsolatedAsyncioTestCase):
},
],
"metadata": {},
+ "usage": None,
},
],
)
@@ -288,6 +294,7 @@ class ContextCompressionTest(IsolatedAsyncioTestCase):
},
],
"metadata": {},
+ "usage": None,
},
],
)
@@ -332,6 +339,7 @@ class ContextCompressionTest(IsolatedAsyncioTestCase):
},
],
"metadata": {},
+ "usage": None,
},
{
"id": "2",
@@ -347,6 +355,7 @@ class ContextCompressionTest(IsolatedAsyncioTestCase):
},
],
"metadata": {},
+ "usage": None,
},
],
)
@@ -367,6 +376,7 @@ class ContextCompressionTest(IsolatedAsyncioTestCase):
},
],
"metadata": {},
+ "usage": None,
},
{
"id": "3",
@@ -382,6 +392,7 @@ class ContextCompressionTest(IsolatedAsyncioTestCase):
},
],
"metadata": {},
+ "usage": None,
},
],
)
@@ -426,6 +437,7 @@ class ContextCompressionTest(IsolatedAsyncioTestCase):
},
],
"metadata": {},
+ "usage": None,
},
],
)
@@ -451,6 +463,7 @@ class ContextCompressionTest(IsolatedAsyncioTestCase):
},
],
"metadata": {},
+ "usage": None,
},
{
"id": "3",
@@ -466,6 +479,7 @@ class ContextCompressionTest(IsolatedAsyncioTestCase):
},
],
"metadata": {},
+ "usage": None,
},
],
)
@@ -518,6 +532,7 @@ class ContextCompressionTest(IsolatedAsyncioTestCase):
},
],
"metadata": {},
+ "usage": None,
},
{
"id": "3",
@@ -533,6 +548,7 @@ class ContextCompressionTest(IsolatedAsyncioTestCase):
},
],
"metadata": {},
+ "usage": None,
},
],
)
@@ -620,6 +636,7 @@ class ContextCompressionTest(IsolatedAsyncioTestCase):
},
],
"metadata": {},
+ "usage": None,
},
{
"id": "3",
@@ -635,6 +652,7 @@ class ContextCompressionTest(IsolatedAsyncioTestCase):
},
],
"metadata": {},
+ "usage": None,
},
],
)
diff --git a/tests/event_to_message_test.py b/tests/event_to_message_test.py
index b9d18f343..6c4134f66 100644
--- a/tests/event_to_message_test.py
+++ b/tests/event_to_message_test.py
@@ -17,6 +17,7 @@ Coverage
* RequireExternalExecutionEvent → SUBMITTED state
* ExternalExecutionResultEvent → ToolResultBlock appended directly
* ToolResultBlock data output : base-64 delta + URL delta / end (ERROR)
+* ModelCallEndEvent (×2) → usage initialized then accumulated
* ReplyEndEvent → finished_at stamped
* Wrong reply_id → event silently skipped
* Missing block → warning, no crash
@@ -32,6 +33,7 @@ from agentscope.event import (
DataBlockEndEvent,
DataBlockStartEvent,
ExternalExecutionResultEvent,
+ ModelCallEndEvent,
ReplyEndEvent,
RequireExternalExecutionEvent,
RequireUserConfirmEvent,
@@ -153,7 +155,11 @@ class EventToMessageTest(IsolatedAsyncioTestCase):
)
_created_at = self.msg.created_at
- def _base(content: list, finished_at: str | None = None) -> dict:
+ def _base(
+ content: list,
+ finished_at: str | None = None,
+ usage: dict | None = None,
+ ) -> dict:
"""Return the expected model_dump() of self.msg."""
return {
"name": "TestAgent",
@@ -163,6 +169,7 @@ class EventToMessageTest(IsolatedAsyncioTestCase):
"created_at": _created_at,
"finished_at": finished_at,
"content": content,
+ "usage": usage,
}
# ================================================================
@@ -649,7 +656,8 @@ class EventToMessageTest(IsolatedAsyncioTestCase):
)
# ================================================================
- # Stage 8 – ReplyEndEvent
+ # Stage 8 – ModelCallEndEvent (first call: usage initialized;
+ # second call: usage accumulated)
# ================================================================
_final_content = _s7b_prefix + [
_trb(
@@ -666,12 +674,39 @@ class EventToMessageTest(IsolatedAsyncioTestCase):
"error",
),
]
+ ev_model_call_end_1 = ModelCallEndEvent(
+ reply_id=_REPLY_ID,
+ input_tokens=10,
+ output_tokens=20,
+ )
+ gt_model_call_end_1 = _base(
+ _final_content,
+ usage={"input_tokens": 10, "output_tokens": 20},
+ )
+
+ ev_model_call_end_2 = ModelCallEndEvent(
+ reply_id=_REPLY_ID,
+ input_tokens=5,
+ output_tokens=8,
+ )
+ gt_model_call_end_2 = _base(
+ _final_content,
+ usage={"input_tokens": 15, "output_tokens": 28},
+ )
+
+ # ================================================================
+ # Stage 9 – ReplyEndEvent
+ # ================================================================
ev_reply_end = ReplyEndEvent(
reply_id=_REPLY_ID,
session_id=_SESSION_ID,
created_at=_FIXED_END_TS,
)
- gt_reply_end = _base(_final_content, finished_at=_FIXED_END_TS)
+ gt_reply_end = _base(
+ _final_content,
+ finished_at=_FIXED_END_TS,
+ usage={"input_tokens": 15, "output_tokens": 28},
+ )
# ================================================================
# Assemble the two parallel lists
@@ -720,7 +755,10 @@ class EventToMessageTest(IsolatedAsyncioTestCase):
ev_res_img_b64,
ev_res_img_url,
ev_res_img_end,
- # Stage 8: REPLY_END
+ # Stage 8: MODEL_CALL_END (init + accumulate)
+ ev_model_call_end_1,
+ ev_model_call_end_2,
+ # Stage 9: REPLY_END
ev_reply_end,
]
self.ground_truths = [
@@ -768,6 +806,9 @@ class EventToMessageTest(IsolatedAsyncioTestCase):
gt_res_img_url,
gt_res_img_end,
# Stage 8
+ gt_model_call_end_1,
+ gt_model_call_end_2,
+ # Stage 9
gt_reply_end,
]
diff --git a/tests/hitl_external_execution_test.py b/tests/hitl_external_execution_test.py
index 16faaafa2..80ec0dbfd 100644
--- a/tests/hitl_external_execution_test.py
+++ b/tests/hitl_external_execution_test.py
@@ -183,6 +183,7 @@ class AgentExternalExecutionTest(IsolatedAsyncioTestCase):
"metadata": {},
"name": "Friday",
"role": "assistant",
+ "usage": None,
}
def _get_tool_call_events(
diff --git a/tests/hitl_user_confirmation_test.py b/tests/hitl_user_confirmation_test.py
index 26880418b..94ed0f192 100644
--- a/tests/hitl_user_confirmation_test.py
+++ b/tests/hitl_user_confirmation_test.py
@@ -232,6 +232,7 @@ class AgentUserConfirmationTest(IsolatedAsyncioTestCase):
"metadata": {},
"name": "Friday",
"role": "assistant",
+ "usage": None,
}
async def test_single_user_confirmation(self) -> None:
@@ -1445,6 +1446,7 @@ class AgentUserConfirmationTest(IsolatedAsyncioTestCase):
"text": self.user_input_text,
},
],
+ "usage": None,
},
)
diff --git a/tests/message_test.py b/tests/message_test.py
index 465f3de95..bf1c8130c 100644
--- a/tests/message_test.py
+++ b/tests/message_test.py
@@ -42,6 +42,7 @@ class MessageTest(IsolatedAsyncioTestCase):
"metadata": {},
"created_at": AnyString(),
"finished_at": AnyString(),
+ "usage": None,
},
)
@@ -63,6 +64,7 @@ class MessageTest(IsolatedAsyncioTestCase):
"metadata": {},
"created_at": AnyString(),
"finished_at": AnyString(),
+ "usage": None,
},
)
@@ -118,6 +120,7 @@ class MessageTest(IsolatedAsyncioTestCase):
"metadata": {},
"created_at": AnyString(),
"finished_at": AnyString(),
+ "usage": None,
},
)
@@ -142,6 +145,7 @@ class MessageTest(IsolatedAsyncioTestCase):
"metadata": {},
"created_at": AnyString(),
"finished_at": None,
+ "usage": None,
},
)
@@ -162,6 +166,7 @@ class MessageTest(IsolatedAsyncioTestCase):
"metadata": {},
"created_at": AnyString(),
"finished_at": None,
+ "usage": None,
},
)
diff --git a/tests/storage_redis_test.py b/tests/storage_redis_test.py
index cdfb000bb..97d3f0ad5 100644
--- a/tests/storage_redis_test.py
+++ b/tests/storage_redis_test.py
@@ -15,7 +15,7 @@ from agentscope.app.storage import (
SessionSource,
)
from agentscope.credential import OllamaCredential
-from agentscope.app.storage._model._agent import AgentData
+from agentscope.app.storage import AgentData
from agentscope.agent import ContextConfig, ReActConfig
from agentscope.message import UserMsg, AssistantMsg, TextBlock