docs: update

Author: BinglanLi

examples/01_basic_usage.py

@@ -14,11 +14,16 @@
 log, result = agent.run("Analyze the dataset and create a visualization")
 print(result)
 
-# Access usage metrics — _usage_metrics accumulates across all runs
-total_cost = sum(u.cost for u in agent._usage_metrics if u.cost is not None)
-total_input = sum(u.input_tokens for u in agent._usage_metrics if u.input_tokens is not None)
-total_output = sum(u.output_tokens for u in agent._usage_metrics if u.output_tokens is not None)
+# Access usage metrics — agent.usage_metrics accumulates across all runs.
+# Note: cost may be None for providers that do not return it in streaming events (e.g. Anthropic).
+total_cost = sum(u.cost for u in agent.usage_metrics if u.cost is not None)
+total_input = sum(u.input_tokens for u in agent.usage_metrics if u.input_tokens is not None)
+total_output = sum(u.output_tokens for u in agent.usage_metrics if u.output_tokens is not None)
+total_cache_creation = sum(u.cache_creation_tokens for u in agent.usage_metrics if u.cache_creation_tokens is not None)
+total_cache_read = sum(u.cache_read_tokens for u in agent.usage_metrics if u.cache_read_tokens is not None)
 print(f"\nUsage Metrics:")
-print(f"Input tokens:  {total_input}")
-print(f"Output tokens: {total_output}")
-print(f"Total cost:    ${total_cost:.4f}")
+print(f"Input tokens:         {total_input}")
+print(f"Output tokens:        {total_output}")
+print(f"Cache creation tokens:{total_cache_creation}")
+print(f"Cache read tokens:    {total_cache_read}")
+print(f"Total cost:           ${total_cost:.4f} (may not reflect actual expense for streaming)")

examples/10_error_handling.py

@@ -61,7 +61,7 @@
     print(f"Agent error: {e}")
 
 # ── 5. Lifetime vs per-run usage tracking ─────────────────────────────────────
-# agent._usage_metrics accumulates across ALL runs on this instance.
+# agent.usage_metrics accumulates across ALL runs on this instance.
 # max_cost is checked against only the CURRENT run's metrics.
 
 agent5 = BaseAgent(llm="claude-sonnet-4-20250514")
@@ -70,7 +70,7 @@
 log_a, _ = agent5.run("What is DNA?")
 log_b, _ = agent5.run("What is RNA?")  # new run; budget resets
 
-total_cost = sum(u.cost for u in agent5._usage_metrics if u.cost is not None)
+total_cost = sum(u.cost for u in agent5.usage_metrics if u.cost is not None)
 print(f"Lifetime cost across both runs: ${total_cost:.4f}")
 
 # ── 6. Configure via environment variables ────────────────────────────────────