Agent: Added UsagePerRequest, Example: Added an example for custom cost component.

[alifarooq9]

Summary

This pull request introduces a robust framework for granular usage tracking within the core agent and adds a new, standalone example to demonstrate a practical application: real-time cost calculation.

The changes are split into two main parts:

1. Agent: Core infrastructure for logging usage on a per-API-request basis.
2. Example: A new application demonstrating how to use this usage data to build a dynamic cost-tracking component.

---

Core Agent Changes

These changes provide the foundational capabilities for usage tracking.

• feat: usagePerRequest Table

  • A new usagePerRequest table has been created to log usage metrics for each individual step or API call an agent makes. This provides highly granular data for monitoring and analysis.

• feat: Expose IDs in onStepFinish

  • The onStepFinish callback now exposes messageId, threadId, and userId. This allows developers to easily correlate usage data with specific user interactions and conversation threads.

• chore: Added Helper Functions

  • A set of helper functions has been added to make querying and managing data in the usagePerRequest table more convenient.

---

New Example: Real-time Cost Component

To showcase the power of the new usage tracking features, a comprehensive new example has been added. This example is self-contained and demonstrates how to:

• Create a Dynamic Pricing Table:

  • It implements a pricing table that periodically fetches and caches the latest model prices from an external source (models.dev) every 5 minutes, ensuring cost calculations are always up-to-date.

• Build a Custom Cost Component:

  • It includes a custom UI component (Cost) that consumes data pricing tables. This component calculates and displays the cost of agent operations in real-time for the end-user.

[pkg-pr-new]

Open in StackBlitz

npm i https://pkg.pr.new/get-convex/agent/@convex-dev/agent@164

npm i https://pkg.pr.new/get-convex/agent/@convex-dev/agent-playground@164

commit: d1cd947

[ianmacartney]

Were you aware of the existing usageHandler?
https://docs.convex.dev/agents/usage-tracking
Example usage: https://github.com/get-convex/agent/blob/main/example/convex/usage_tracking/usageHandler.ts#L13-L26
I'm not sure how this approach compares, except putting some of the example tables into a cost component, which could be a great standalone component for calculating usage pricing - especially with all the intricacies of pricing, I'm sure folks would love to delegate that to a dedicated component (provided it's flexible enough)

[ianmacartney]

@alifarooq9 curious if you saw my message & what you think?

[alifarooq9]

@alifarooq9 curious if you saw my message & what you think?

Yea, I think you're are correct on this. A dedicated component would be a better for this