Add token usage and counting to Agent Builder

solutions/search/agent-builder/agent-builder-agents.md

@@ -18,6 +18,10 @@ An agent parses user requests to define a goal and then runs tools in a loop to
 
 When you ask a question to an agent, it analyzes your request to define a specific goal. It selects the most appropriate tools and determines the right arguments to use. The agent evaluates the information returned after each action and decides whether to use additional tools or formulate a response. This iterative process of tool selection, execution, and analysis continues until the agent can provide a complete answer.
 
+:::{note}
+This iterative process consumes tokens. To understand how usage is calculated, refer to [Token usage in Elastic Agent Builder](monitor-usage.md).
+:::
+
 {{agent-builder}} includes a default agent (named `Elastic AI Agent`) with access to all built-in tools. You can create specialized agents with custom instructions and selected tools to address specific use cases or workflows.
 
 :::{note}

solutions/search/agent-builder/chat.md

@@ -35,6 +35,10 @@ This takes you to the chat GUI:
 
 Use the text input area to chat with an agent in real time. By default, you chat with the built-in Elastic AI Agent.
 
+:::{note}
+Conversations with agents consume tokens. To understand how usage is calculated, refer to [Token usage in Elastic Agent Builder](monitor-usage.md).
+:::
+
 :::{image} images/agent-builder-chat-input.png
 :alt: Text input area for chatting with agents
 :width: 850px

solutions/search/agent-builder/monitor-usage.md

@@ -0,0 +1,24 @@
+---
+navigation_title: "Monitor usage"
+applies_to:
+  stack: preview 9.2
+  serverless:
+    elasticsearch: preview
+    observability: unavailable
+    security: unavailable
+---
+
+# Token usage in Elastic Agent Builder
+
+When using {{agent-builder}}, total token usage typically exceeds the visible conversation text. Because {{agent-builder}} utilizes an agentic framework, a single user request often triggers multiple model calls (rounds) to process reasoning steps, run tools, and interpret results.
+
+Token counts include:
+
+* **Input Tokens:** These accumulate throughout the session. They include the user's current query, the conversation history from previous rounds, system prompts, and the results returned from any tools used during execution.
+* **Output Tokens:** These include the final response visible to the user, as well as all internal reasoning steps, tool calls, and intermediate results generated by the model.
+
+:::{note}
+Each conversation round includes all previous rounds as context. This means token usage at each step depends on the entire conversation size, not just the current message.
+:::
+
+For more information on billing and token costs, refer to [Elastic pricing](https://www.elastic.co/pricing).

solutions/search/agent-builder/tools.md

@@ -34,6 +34,10 @@ Tools enable agents to work with {{es}} data. When an agent receives a natural l
 
 Each tool is an atomic operation with a defined signature - accepting typed parameters and returning structured results in a format the agent can parse, transform, and incorporate into its response generation.
 
+:::{note}
+Tool execution and result processing consume tokens. To understand how usage is calculated, refer to [Token usage in Elastic Agent Builder](monitor-usage.md).
+:::
+
 ## Built-in tools
 
 {{agent-builder}} ships with a comprehensive set of built-in tools that provide core capabilities for working with your {{es}} data. These tools are ready to use. They cannot be modified or deleted.

solutions/search/elastic-agent-builder.md

@@ -72,6 +72,12 @@ Configure security roles and API keys to control who can use agents, which tools
 
 [**Learn more about permissions and access control**](agent-builder/permissions.md)
 
+## Monitor usage
+
+Understand how tokens are calculated and accumulated during agent execution to predict the impact on your usage and costs.
+
+[**Learn more about token usage**](agent-builder/monitor-usage.md)
+
 ## Limitations and known issues
 
 {{agent-builder}} is in technical preview.

solutions/toc.yml

@@ -1,3 +1,3 @@
 project: "Solutions and use cases"
 toc:
   - file: index.md
@@ -77,6 +77,7 @@
               - file: search/agent-builder/kibana-api.md
               - file: search/agent-builder/a2a-server.md
               - file: search/agent-builder/mcp-server.md
+          - file: search/agent-builder/monitor-usage.md
           - file: search/agent-builder/permissions.md
           - file: search/agent-builder/limitations-known-issues.md
       - file: search/rag.md