From b15d5218a6bc93f94c20130dd36a858b37c36514 Mon Sep 17 00:00:00 2001
From: LI <2484593937@qq.com>
Date: Wed, 28 Oct 2026 15:30:12 +0800
Subject: [PATCH] docs(core): clarify optional usage counter handling

---
 python/packages/core/agent_framework/_types.py | 5 +++--
 1 file changed, 3 insertions(+), 2 deletions(-)

diff --git a/python/packages/core/agent_framework/_types.py b/python/packages/core/agent_framework/_types.py
index 7eca7a0fe2..12886970ff 100644
--- a/python/packages/core/agent_framework/_types.py
+++ b/python/packages/core/agent_framework/_types.py
@@ -652,8 +652,9 @@ def _has_reasoning_text_marker(additional_properties: Mapping[str, Any]) -> bool
 def add_usage_details(usage1: UsageDetails | None, usage2: UsageDetails | None) -> UsageDetails:
     """Add two UsageDetails dictionaries by summing all numeric values.
 
-    If any of the two usage details contains a key with a non-int value, it will be skipped,
-    even if the other contains a int-value on that key.
+    Missing keys and ``None`` values contribute zero. If either dictionary contains
+    a non-integer value other than ``None`` for a key, that key is skipped even if
+    the other value is an integer. Boolean values are also skipped.
 
     Args:
         usage1: First usage details dictionary.