# Practical and Useful Patterns for OpenAI Agent SDK 🌍 Make your agent's token spending visible. Track usage at every level -- from total cost per tenant to per-step breakdown monitoring. The Usage API lets you capture total token consumption for an entire run and drill down into per-step breakdowns for tool calls, handoffs, and guardrails. 📌 Title: Usage 🔗 URL: 🧩 Overview The OpenAI Agent SDK's Usage feature tracks token consumption across agent runs. `result.context_wrapper.usage` gives you total tokens for the entire run, while `result.context_wrapper.usage.request_usage_entries` provides per-step breakdowns (tool calls, handoffs, guardrails). You can use RunHooks' `on_agent_end` for real-time logging, and enable usage reporting for third-party model adapters with `ModelSettings(include_usage=True)`. 🛠 How to Use Create an agent with `Agent(name="Assistant", instructions="Answer user questions.")` and run `result = await "Tell me about quantum computing")`. Access total, input, and output tokens via ` `result.context_wrapper.usage.input_tokens`, and `result.context_wrapper.usage.output_tokens`. Loop through `result.context_wrapper.usage.request_usage_entries` to see per-request breakdowns with `entry.input_tokens` and `entry.output_tokens`. 🏗 Practical Usage Patterns **Per-Tenant/User Cost Calculation** Record "how much each tenant spent" for billing and budget management in SaaS applications. In a `handle_request(tenant_id, user_id, message)` function, run `result = await message)`, compute cost with `calculate_cost(model="gpt-4.1", input_tokens=result.context_wrapper.usage.input_tokens, output_tokens=result.context_wrapper.usage.output_tokens)`, and record it with `await billing_db.record(tenant_id=tenant_id, user_id=user_id, total_tokens= cost_usd=cost, timestamp= **Per-Step Monitoring** Use `request_usage_entries` to identify which tool calls or handoffs consume the most tokens. After `result = await "Generate a sales report")`, loop through `result.context_wrapper.usage.request_usage_entries` with `enumerate` to check each step's `entry.input_tokens` and `entry.output_tokens`. Flag steps where `entry.input_tokens > 5000` with a warning to identify token-heavy operations. **Real-time Logging with RunHooks** Use `on_agent_end` hook to log usage when each agent completes. Create a `UsageLoggingHooks` class extending `RunHooks` with an `on_agent_end(self, context: RunContextWrapper, agent: Agent, output)` method that reads `context.usage` and logs with `"agent_completed", agent_name= total_tokens= ...)`. Pass it via `await "question", hooks=UsageLoggingHooks())`. **Enabling Usage for Third-party Models** When using non-OpenAI model adapters, explicitly enable usage reporting. For third-party models, explicitly enable usage reporting with `Agent(name="ThirdPartyAgent", instructions="...", model=my_custom_model_adapter, model_settings=ModelSettings(include_usage=True))`. 💡 Use Cases 💰 Record per-tenant/user token consumption in a database to build usage-based billing 📊 Visualize per-step token consumption with request_usage_entries to identify cost optimization bottlenecks 🔔 Log usage via RunHooks on_agent_end for real-time dashboard monitoring 🔌 Enable ModelSettings(include_usage=True) for third-party models to ensure usage tracking coverage ⚠️ Caveats - ` includes retries and guardrail re-executions, so it may be higher than the visible step count suggests. - Third-party models may return zero usage without `include_usage=True`. Check your adapter's documentation. - Cost calculations depend on model pricing. Ensure you accurately reflect per-model input/output token rates. ✨ Track token usage at three levels -- total, per-step, and via hooks -- and you'll have cost management and quality monitoring fully covered. Start with result.context_wrapper.usage, then add step-level and hook-based tracking as needed! #OpenAIAgentSDK# #AIAgent#