diff --git a/solutions/search/agent-builder/agent-builder-agents.md b/solutions/search/agent-builder/agent-builder-agents.md index 7c28d382fa..c563112dd8 100644 --- a/solutions/search/agent-builder/agent-builder-agents.md +++ b/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} diff --git a/solutions/search/agent-builder/chat.md b/solutions/search/agent-builder/chat.md index 3b00b1d8d3..b547c691b1 100644 --- a/solutions/search/agent-builder/chat.md +++ b/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 diff --git a/solutions/search/agent-builder/monitor-usage.md b/solutions/search/agent-builder/monitor-usage.md new file mode 100644 index 0000000000..7703f56bc2 --- /dev/null +++ b/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). diff --git a/solutions/search/agent-builder/tools.md b/solutions/search/agent-builder/tools.md index 52a8afce0e..d95e3af371 100644 --- a/solutions/search/agent-builder/tools.md +++ b/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. diff --git a/solutions/search/elastic-agent-builder.md b/solutions/search/elastic-agent-builder.md index 5b6c0915fa..07cd8f4f3b 100644 --- a/solutions/search/elastic-agent-builder.md +++ b/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. diff --git a/solutions/toc.yml b/solutions/toc.yml index 82f9883d84..205b3bee8f 100644 --- a/solutions/toc.yml +++ b/solutions/toc.yml @@ -77,6 +77,7 @@ toc: - 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