feat(usage): add agent_name and model_name to RequestUsage

[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 #2100

Summary by CodeRabbit

• New Features

  • Usage tracking now records agent name and model name with each request for improved visibility and attribution; model name is included only when available.
  • Usage exports/records now include these metadata fields when present.

• Tests

  • Added tests verifying capture and preservation of agent and model names across runs, merges, and multi-agent scenarios.

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 80262bcf4d

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

[chatgpt-codex-connector]

Do not mutate incoming request usage entries

Usage.add() now assigns agent_name/model_name directly onto other.request_usage_entries before extending, which mutates caller-owned objects. If the same Usage instance is aggregated more than once (for example into two different parents with different attribution labels), the first aggregation permanently stamps the entries and the second one cannot correct them because of the non-overwrite guard, causing silent mis-attribution of usage. Please annotate copied entries instead of mutating other in place.

Useful? React with 👍 / 👎.

[seratch]

We're not yet fully convinced to add these data because they could be incomplete in many cases. Refer to the discussion at #2114 for more details.

[adityasingh2400]

Thanks for the feedback @seratch!

Bug fix: The elif other.request_usage_entries branch was mutating agent_name/model_name directly on the original RequestUsage objects, bypassing the non-overwrite guard and causing silent mis-attribution. Fixed by creating a copy of each entry with the annotation applied rather than mutating in place. Added a regression test to cover this.

On completeness concerns: I've read the discussion at #2114. The fields are already guarded against the incompleteness issue:

• agent_name is always available (it's agent.name, which every agent has)
• model_name uses getattr(model, 'model', None) — if a custom Model implementation doesn't expose a model attribute, the field stays None and nothing breaks

Both fields are typed str | None and documented as 'if available', so callers can't assume they're always set. The data is as complete as it can be given the existing Model interface.

Happy to drop model_name entirely and only keep agent_name if that better fits the project's direction — agent_name has no completeness risk since it's always a string.