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".

[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.

[adityasingh2400]

@seratch quick FYI while we wait, pushed 5ac2475 with three small hardening follow-ups that are directly relevant to the "could be incomplete in many cases" concern:

• _get_model_name is now defensive against custom Model implementations whose descriptors or properties raise on attribute access. It swallows exceptions, falls back to model_name when model is missing, and rejects empty strings, so usage accounting can't crash a run on a third-party Model subclass that doesn't fit the pattern.
• New test_serialize_deserialize_roundtrip_preserves_agent_and_model_names exercises both branches of the conditional emit in serialize_usage: builds a Usage with one named and one unnamed RequestUsage, runs serialize_usage then deserialize_usage, asserts both fields survive on the named entry and stay None on the unnamed one.
• test_multi_agent_run_attributes_usage_to_correct_agents now sets a distinct model on each FakeModel and asserts model_name on both the triage and specialist RequestUsage entries, so a regression that drops or cross-wires model_name during handoff aggregation surfaces in tests rather than as a silent mis-attribution at runtime.

The completeness contract is unchanged: both fields are str | None and documented as best-effort, never required, so callers that don't have the data simply see None. The standing offer from the previous comment also still applies: if you'd prefer to keep just agent_name (which is always a string and carries no completeness risk), I'm happy to drop model_name in a follow-up commit.

[chatgpt-codex-connector]

💡 Codex Review

openai-agents-python/src/agents/usage.py

Lines 226 to 230 in 5ac2475

	if other.requests == 1 and other.total_tokens > 0:
	input_details = other.input_tokens_details or InputTokensDetails(cached_tokens=0)
	output_details = other.output_tokens_details or OutputTokensDetails(reasoning_tokens=0)
	request_usage = RequestUsage(
	input_tokens=other.input_tokens,

Preserve existing attribution on single-request merges

When other.requests == 1, this fast path runs even if other.request_usage_entries already exists, so the new RequestUsage is rebuilt from aggregate totals and uses only the passed agent_name/model_name values. In scenarios like re-aggregating deserialized usage, this can silently drop or overwrite existing per-request attribution (entry.agent_name / entry.model_name), while the elif other.request_usage_entries branch explicitly preserves existing names. Please prefer merging other.request_usage_entries first (or copy attribution from the existing entry) so single-request usages keep their original metadata.

ℹ️ 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]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: fa0a85f3b8

ℹ️ 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".

[adityasingh2400]

Follow-up pushed (617a77c)

Addressed both open Codex threads on Usage.add():

1. No in-place mutation — already landed earlier via copied RequestUsage rows in the request_usage_entries merge path; left as-is.

2. Single-request + pre-built request_usage_entries — when other.requests == 1 and other.request_usage_entries is non-empty, we now fold those entries in with the same agent/model annotation rules as the multi-entry branch, instead of building one new RequestUsage from totals + add() kwargs only (which dropped existing attribution).

Added test_usage_add_single_request_preserves_prebuilt_entry_attribution.

Threads marked resolved; CI should re-run on the push.