Token Counting

Token counting helps you estimate context token count for an Agent run. Token counting can be used for features like token-based context compression and memory optimization.

What is counted

Context can include:

• Messages
  • Content of the message - Includes the system message, user message, and the assistant message content.
  • Tool call arguments and results
  • Optional reasoning content
  • Multimodal content blocks
• Tools
  • Tool definitions can be a meaningful part of the total token count, especially with large parameter schemas or long descriptions.
• Output schema
  • If you use an Output Schema, the schema is included in the token count.
• Multimodal attachments
  • Images, audio, video, and files attached to messages use metadata-based estimates; missing duration or size can contribute zero.

Optional dependencies (recommended)

For better local token-count estimates, install tokenizers alongside your model provider:

uv pip install -U agno openai tiktoken tokenizers
export OPENAI_API_KEY="your_openai_api_key"

• openai: model provider used in the example below.
• tiktoken: used when available for OpenAI-style tokenization.
• tokenizers: used for certain open-source tokenizers when available.
• If neither is available for the given model, we fall back to heuristic estimates.

Provider counting and network access

OpenAIResponses.count_tokens() and acount_tokens() first send the formatted messages and tool definitions to OpenAI's input-token counting endpoint, then add an output-schema estimate. They require provider credentials and network access. On failure, they fall back to the base model's estimation path. Claude also supports a provider token-count endpoint.

For explicit estimation, call agno.utils.tokens.count_tokens with a model ID. Local estimation may still download a tokenizer or fetch metadata for remote media URLs; it is not an unconditional offline guarantee. Supply known media metadata and manage caches when network access must be controlled.

Example: counting tokens

from pydantic import BaseModel

from agno.models.message import Message
from agno.models.openai import OpenAIResponses


class Answer(BaseModel):
    answer: str


model = OpenAIResponses(id="gpt-5.2")

messages = [
    Message(role="system", content="You are a concise assistant."),
    Message(role="user", content="Summarize context compression in 2 sentences."),
]

# Tool definitions can be passed as OpenAI-style tool dicts
tools = [
    {
        "type": "function",
        "function": {
            "name": "search_web",
            "description": "Search the web for a query.",
            "parameters": {
                "type": "object",
                "properties": {"query": {"type": "string"}},
                "required": ["query"],
            },
        },
    }
]

tokens = model.count_tokens(messages=messages, tools=tools, output_schema=Answer)
print(f"Estimated tokens: {tokens}")

Token counting in token-based context compression

When you set compress_token_limit, Agno checks the estimated token count during the run loop and triggers compression when the threshold is reached.

Because token counting can include message history, tool definitions, and the output schema/response format, it more closely matches the "true" request size than counting only message text.

Multimodal estimates

Agno estimates multimodal inputs from available metadata. These estimates are not upper bounds:

• Images: estimated via a tile-based approach (vision-style counting)
• Audio: estimated using tokens-per-second; absent duration contributes zero
• Video: estimated from duration, frame rate, and dimensions; absent duration contributes zero
• Files: estimated based on file type/size; absent size contributes zero

Notes

• Token counting is still in Beta. We do our best to provide an estimate but we do not claim it to be 100% accurate across all providers and models. Please be wary of using this token count for calculating costs.
• Provider counting can add request latency. A token count does not by itself establish billed cost; use the provider's usage data for billing.