feat(usage): add agent_name and model_name to RequestUsage (#2100)

[adityasingh2400]

Summary

Adds optional agent_name and model_name fields to RequestUsage so developers can attribute token usage and costs to specific agents and models in multi-agent workflows.

Problem

In complex multi-agent systems, result.context_wrapper.usage.request_usage_entries contains one RequestUsage per LLM call, but there is no way to know which agent or model generated each entry. This makes per-agent cost attribution impossible.

Solution

• Added agent_name: str | None = None and model_name: str | None = None to RequestUsage (backward-compatible — defaults to None)
• Modified Usage.add() to accept keyword-only agent_name and model_name parameters and annotate the resulting RequestUsage entry
• Added _get_model_name() helper that safely duck-types the model name from any Model implementation (e.g. OpenAIResponsesModel.model, OpenAIChatCompletionsModel.model)
• Updated both run_single_turn_streamed and get_new_response call-sites in run_loop.py to pass agent.name and resolved model name
• When merging pre-existing request_usage_entries, agent/model names are applied only to entries that don't already have them (existing names preserved)
• Updated serialize_usage / deserialize_usage to round-trip the new fields through JSON
• Zero breaking changes — existing code constructing RequestUsage or calling Usage.add() without these fields continues to work

Before / After

# Before
RequestUsage(input_tokens=65, output_tokens=13, ...)

# After
RequestUsage(agent_name="Math Tutor", model_name="gpt-4o", input_tokens=65, output_tokens=13, ...)

Usage Example

result = await Runner.run(triage_agent, input="help me")

for entry in result.context_wrapper.usage.request_usage_entries:
    print(f"{entry.agent_name} ({entry.model_name}): {entry.input_tokens} in / {entry.output_tokens} out")
# Triage Agent (gpt-4o-mini): 100 in / 10 out
# Specialist Agent (gpt-4o): 200 in / 20 out

Files Changed

File	Change
src/agents/usage.py	Added agent_name/model_name fields to RequestUsage; updated Usage.add(), serialize_usage, deserialize_usage
src/agents/run_internal/run_loop.py	Added _get_model_name() helper; updated both usage.add() call-sites
tests/test_usage.py	Added 9 new tests

Test Plan

• Unit tests for RequestUsage field population (explicit + default None)
• Usage.add() propagation and backward compat tests
• Entry merge semantics (names applied to un-named entries; existing names preserved)
• Single-agent runner integration test confirming agent_name is set
• Model-name detection test via duck-typed .model attribute
• Multi-agent scenario: each RequestUsage entry has the correct agent_name
• Full suite: 2198 tests pass, lint clean, pyright clean

Closes openai#2100

Summary by CodeRabbit

• New Features

  • Usage tracking now records agent and model names with each request for better attribution; model name is included only when reliably available. Merging preserves existing attribution and avoids mutating original usage entries.

• Tests

  • Added tests verifying capture, preservation, merging, immutability, and correct attribution across single- and multi-agent runs.