How to track session and event costs in the ADK

[camilopenalver]

The framework was created with the mission of making it easy to build agents and bring it closer to software development, but the documentation doesn’t explain how to track token usage or estimate costs. There’s also no clear explanation of what these values mean or how they’re being counted — are they counted per event or per session? How can we build a way to track the cost of a session?

I know some people mentioned in this discussion that LiteLLM allows cost tracking, but does that mean that if I want to use a Gemini model, I have to embed it with LiteLLM just because the ADK doesn’t make it easy to see costs? And if I embed it that way, do I lose the built-in Google Search tool?

[adk-bot]

Response from ADK Answering Agent (experimental, answer may be inaccurate)

TLDR: The ADK provides token counts for each event (turn) in the usage_metadata object. You can sum these counts to track session usage and calculate costs. For more advanced, automated tracking, you can integrate with third-party observability tools like AgentOps, or build your own ADK Plugin. Using a Gemini model via LiteLLM should not prevent you from using built-in tools like Google Search, as tool functionality is a feature of the underlying model.

---

Hello! Thanks for your question. It's a great point about making cost and usage tracking clearer. Here’s a breakdown of how you can approach this with the ADK.

How to Track Token Usage and Costs

The token counts you're seeing in the logs (prompt_token_count, candidates_token_count, total_token_count) are provided by the ADK for each individual event (i.e., per turn in the conversation). These are located in the usage_metadata attribute of the event object.

To track the total cost of a session, you can iterate through the events as they stream from the run_async method and sum the total_token_count for each. You can then multiply this total by the pricing rate of the specific model you are using to get the session cost.

Here’s a code example that demonstrates how to sum tokens for a session. [3]

async def main():
    # ... (agent setup)
    session_prompt_tokens = 0
    session_candidates_tokens = 0
    session_total_tokens = 0

    async for event in agent.run_async(prompt="...your prompt..."):
        if event.usage_metadata:
            turn_prompt = event.usage_metadata.prompt_token_count
            turn_candidates = event.usage_metadata.candidates_token_count
            turn_total = event.usage_metadata.total_token_count

            session_prompt_tokens += turn_prompt
            session_candidates_tokens += turn_candidates
            session_total_tokens += turn_total

            print(f"Turn tokens: {turn_total}")
    
    print(f"Session total tokens: {session_total_tokens}")

Advanced Monitoring

For more robust and automated cost monitoring, you have a couple of options:

1. ADK Plugins: You can create a custom ADK Plugin to collect and export metrics, such as token usage, to a monitoring system of your choice (like Google Cloud Monitoring or Prometheus). [2]
2. Third-Party Integrations: The ADK supports integration with observability platforms. For example, AgentOps is a tool that provides LLM cost and latency tracking out of the box. [1]

Using LiteLLM with Gemini and ADK Tools

You raised a valid concern about whether using LiteLLM to wrap a Gemini model would cause you to lose access to built-in ADK tools like Google Search.

ADK's ability to use tools is dependent on the underlying model's capability for function/tool calling. [4] While the most direct and recommended way to use Gemini is with the built-in integrations, using it via a compatibility layer like LiteLLM is also a valid approach. Since Gemini models natively support tool calling, and LiteLLM is designed to be a transparent proxy, the tool-calling functionality should still be available to the ADK. Therefore, you should not lose access to the Google Search tool.

I hope this helps clarify how to handle cost and token tracking in your ADK-powered applications!

---

[1] https://google.github.io/adk-docs/observability/agentops/
[2] https://google.github.io/adk-docs/plugins/
[3] https://github.com/google/adk-python/blob/main/contributing/samples/token_usage/main.py
[4] https://google.github.io/adk-docs/agents/models/

[camilopenalver]

What are cached tokens? What are candidate tokens? What are prompt tokens? What are output tokens? Are there no output tokens in the ADK? How can I estimate prices with these values?