Track Agent and Model Identifiers in Usage Statistics

[RVV-karma]

Feature Request: Track Agent and Model Identifiers in Usage Statistics

Have you read the docs?

Yes — Agents SDK documentation.

Have you searched for related issues?

Yes; no existing issue addresses per-agent or per-model usage tracking.

---

Motivation

In complex multi-agent systems, it is common for each agent to serve a distinct purpose and often use different model endpoints. For effective monitoring, accountability, and optimization, developers need granular visibility into which agent made which API request, and with which model. Currently, the usage reporting aggregates statistics without linking them to specific agents or models, making it hard to analyze efficiency or cost per agent.

---

Current Implementation

Currently, usage statistics returned by the SDK do not include agent or model identifiers. Here’s a typical implementation and output:

Example Code

from agents import Agent
from agents.extensions.models.litellm_model import LitellmModel

math_tutor_agent = Agent(
    name="Math Tutor",
    handoff_description="Specialist agent for math questions",
    instructions="Return just the answer",
    model=LitellmModel(model="openai/gpt-3.5-turbo", base_url="https://openrouter.ai/api/v1"),
)

science_tutor_agent = Agent(
    name="Science Tutor",
    handoff_description="Specialist agent for science questions",
    instructions="Return just the answer",
    model=LitellmModel(model="openai/gpt-3.5-turbo", base_url="https://openrouter.ai/api/v1"),
)

chat_agent = Agent(
    name="Chat Agent",
    instructions="Handoff the task to correct Agent",
    model=LitellmModel(model="openai/gpt-3.5-turbo", base_url="https://openrouter.ai/api/v1"),
    handoffs=[math_tutor_agent, science_tutor_agent]
)

from agents import Runner

result = await Runner.run(chat_agent, "2+2?")
print(result.final_output)
print(result.context_wrapper.usage)

Example Output

4
Usage(
    requests=2,
    input_tokens=115,
    output_tokens=14,
    total_tokens=129,
    request_usage_entries=[
        RequestUsage(
            input_tokens=65,
            output_tokens=13,
            total_tokens=78,
            input_tokens_details=InputTokensDetails(cached_tokens=0),
            output_tokens_details=OutputTokensDetails(reasoning_tokens=0)
        ),
        RequestUsage(
            input_tokens=50,
            output_tokens=1,
            total_tokens=51,
            input_tokens_details=InputTokensDetails(cached_tokens=0),
            output_tokens_details=OutputTokensDetails(reasoning_tokens=0)
        )
    ]
)

There is no mapping between RequestUsage entries and the specific agent or model used for that request.

---

Proposed Feature

Enhance usage tracking by including both the agent’s name or identifier, and the model name, inside every RequestUsage entry. This will allow developers to understand which agent handled each request, and which model was used.

Expected Output Example

4
Usage(
    requests=2,
    input_tokens=115,
    output_tokens=14,
    total_tokens=129,
    request_usage_entries=[
        RequestUsage(
            agent_name="Chat Agent",
            model_name="openai/gpt-3.5-turbo",
            input_tokens=65,
            output_tokens=13,
            total_tokens=78,
            input_tokens_details=InputTokensDetails(cached_tokens=0),
            output_tokens_details=OutputTokensDetails(reasoning_tokens=0)
        ),
        RequestUsage(
            agent_name="Math Tutor",
            model_name="openai/gpt-3.5-turbo",
            input_tokens=50,
            output_tokens=1,
            total_tokens=51,
            input_tokens_details=InputTokensDetails(cached_tokens=0),
            output_tokens_details=OutputTokensDetails(reasoning_tokens=0)
        )
    ]
)

Example Code Snippet

If a developer calls:

result = await Runner.run(chat_agent, "2+2?")
print(result.context_wrapper.usage)

They will see usage statistics traced to both the agent and the model for each request, as demonstrated above.

---

Implementation Suggestions

• Extend the RequestUsage dataclass to include new fields: agent_name (or agent_id) and model_name.
• Populate these fields at the point each agent initiates a model request.
• Ensure backward compatibility by making these fields optional for existing systems.

---

Benefits

• Enables granular tracking of request volume, token consumption, and costs for each agent and model.
• Supports better debugging, optimization, and accountability in multi-agent/multi-model workflows.
• Facilitates reporting, cost distribution, and analytics at the agent and model level in production deployments.
• Helps integrate SDK telemetry with external monitoring or billing systems.

[seratch]

Thanks for sharing the idea. I don't expect we'll be able to add something like this in the short term, but your feedback is noted and appreciated.