> For the complete documentation index, see [llms.txt](https://docs.maiagent.ai/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.maiagent.ai/maiagent-user-guide/en/build/agent/custom-max-tokens.md). # Response Length and Agent Execution Limits Set the maximum length of each Agent response (maximum output tokens), the tool call limit in Agent mode (maximum iterations, default 20), and the execution timeout; learn what users see when the tool The Agent's Advanced Settings include two groups of limits: * **Response length**: Maximum Output Tokens limits how much the AI can write in each response. The explanation starts with [Feature Introduction](#feature-introduction) below. * **Agent execution limits**: Maximum Iterations (the tool call limit, default 20) and Execution Timeout (Seconds) limit how many rounds of tool calls an Agent in Agent mode can make per message and how long it can run. To find out "how many tool calls are allowed" or understand the message "The tool usage limit for this turn has been reached," go directly to [Agent Execution Limits](#agent-iteration-timeout-relationship). ### Feature Introduction The custom output token limit lets you precisely control the maximum length of each Agent response. Adjust this setting for different use cases to produce brief summaries or detailed explanations while effectively controlling token costs. {% hint style="info" %} **About Tokens** Tokens are the basic units AI models use to process text. In general: * Chinese: 1 character is approximately 1.5-2 tokens * English: 1 word is approximately 1-1.5 tokens * Punctuation also counts toward the token total {% endhint %} *** ### Configure the Output Token Limit #### Navigate to the Settings Page 1. Click "AI Assistants" in the left menu 2. In the list, click "Edit" to the right of the Agent you want to configure 3. In the left navigation of the "Settings" tab, click "Advanced Settings" under "Management & Advanced" #### Adjust the Token Limit 1. **Select a token limit mode** * "Use Model Maximum": Apply the maximum output tokens supported by the selected model (default) * "Custom Amount": Specify your own limit 2. **Enter a custom value (when "Custom Amount" is selected)** * Enter the desired value in the numeric input field * The allowed range depends on the selected model. The interface displays the model's allowed range in real time (for example, "Range: 512 - 64000 tokens" in the image below) 3. **Save the settings** * Click the "Save" button * Settings take effect immediately; there is no need to restart the Agent
Advanced Settings: Maximum Output Tokens

The "Maximum Output Tokens" section: select "Custom Amount" and enter a limit; the range allowed by the current model appears below

{% hint style="warning" %} **Notes** * Setting the limit too low may truncate responses and affect completeness * Setting the limit too high increases token costs * Adjust it to your actual needs and test to find the best balance {% endhint %} *** ### Recommended Settings The following token limits are recommended for different use cases:
Use CaseRecommended TokensDescription
Brief Q&A256 - 512Suitable for quick answers, such as FAQ bots
Approximately 100-200 Chinese characters
General Customer Service512 - 1024Balances detail and cost
Approximately 200-400 Chinese characters
Professional Consultation1024 - 2048Provides detailed explanations and solutions
Approximately 400-800 Chinese characters
Content Generation2048 - 4096Generates long articles or reports
Approximately 800-1600 Chinese characters
Code Generation1024 - 2048Produces complete code snippets
Including comments and explanations
*** ### Use Case Examples #### Scenario 1: FAQ Quick Response Bot **Requirement**: Provide brief, clear answers to frequently asked customer questions without lengthy explanations **Configuration**: * Output token limit: 256-512 * System prompt: "Answer questions briefly and clearly in no more than 3 sentences" * Expected result: Fast responses with lower token consumption **Example conversation**: ``` User: What are your business hours? AI: Our business hours are Monday to Friday, 9:00 AM to 6:00 PM, Saturday, 10:00 AM to 5:00 PM, and we are closed on Sundays. ``` #### Scenario 2: Detailed Technical Support **Requirement**: Provide detailed step-by-step instructions for users experiencing technical issues **Configuration**: * Output token limit: 1024-2048 * System prompt: "Provide detailed step-by-step instructions that users can follow" * Expected result: Complete troubleshooting guidance **Example conversation**: ``` User: What should I do if the software won't start? AI: Follow these steps to troubleshoot: 1. Check system requirements - Operating system: Windows 10 or later - Memory: At least 4GB - Disk space: At least 2GB 2. Reinstall the software - Uninstall the existing version (Control Panel > Programs) - Download the latest version [link] - Run the installer as an administrator 3. Check firewall settings - Add the software to the exception list - Allow the software to access the network If these steps do not resolve the issue, please provide a screenshot of the error message so we can assist further. ``` #### Scenario 3: Content Summary Generation **Requirement**: Extract key points from long articles **Configuration**: * Output token limit: 512-768 * System prompt: "Organize the key points into 3-5 items, with no more than 2 sentences per item" * Expected result: Concise summaries that are easy to understand quickly *** ### Relationship with Other Settings #### System Prompt Even with a high token limit, the system prompt can still constrain response length: ``` Good example: "Answer concisely unless the user requests a detailed explanation" Poor example: "Answer every question in as much detail as possible" (may lead to excessively long responses) ``` #### Model Selection Different models support different maximum output token counts. When you change the model used by the Agent, the customizable range changes accordingly. The range hint in the interface shows the lower and upper limits for the currently selected model. Selecting "Use Model Maximum" automatically applies that model's maximum. *** ### Agent Execution Limits: Tool Call Rounds and Execution Timeout {% hint style="info" %} This section applies only to Agents whose **response mode is set to "Agent Mode"**. This section does not appear in Advanced Settings for Agents using other response modes. {% endhint %} An Agent in Agent mode decides which tools to call and how many rounds of reasoning it needs to answer a question. To prevent it from running indefinitely, Agent Workflow Settings in Advanced Settings provide two independent "brakes": * **Maximum Iterations** (tool call limit): The maximum number of "think → call tools → receive results" rounds the Agent can perform when answering a message. The range is 1–100, with a default of 20. A round can call multiple tools at once, so the limit is counted in rounds and resets when the user sends the next message. When Enable Tool Search is enabled (the default), rounds used solely to search for available tools do not count toward the limit * **Execution Timeout (Seconds)**: The maximum time an Agent can run while answering one message. The range is 30–1200 seconds, with a default of 600 seconds #### What Happens When the Tool Call Limit Is Reached After the last round is used, the Agent stops calling tools, prepares a response using the information already obtained, and adds the following line at the end: > This response has reached the tool usage limit for this turn and may be incomplete. Send a follow-up message to continue. If the Agent has not written any content at that point, the response will be "I reached the tool usage limit for this turn before completing the task. Please try again or narrow the scope of your question." Both cases mean the configured limit has taken effect, rather than a system error. The user can send another message asking the Agent to continue, and administrators can increase Maximum Iterations (also check the timeout, as explained below). #### How Do the Two Settings Interact? **These settings are independent, with no conversion formula; whichever threshold is reached first determines the outcome.** If the timeout is reached first, the conversation is forcibly interrupted. If the iteration limit is reached first, the Agent generates a summary response, and this is not treated as an error.
Execution timeout warning

Example of the yellow warning triggered by a 100-second timeout ÷ 20 iterations (a budget of only 5 seconds per iteration)

#### Custom Timeout Message "Custom Timeout Message" at the bottom of Agent Workflow Settings determines the text users see when execution is interrupted by a timeout. The on-screen description says, "Shown to users only when the Agent workflow times out. Leave blank to use the system default message." You can enter a message such as "The system is busy. Please try again later," or suggest asking a smaller question. The iteration limit notice has fixed wording and is not affected by this field. ### Other Switches in Advanced Settings The same Advanced Settings tab includes several other switches related to response length and cost. The defaults are generally sufficient: | Location | Switch | On-screen Description and Usage | | ---------------------------- | ---------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | Knowledge Base Settings | Force Full Retrieval Scope | When enabled, ignores the model's automatically chosen retrieval count and always returns the full number of results configured in "Maximum Retrieval Chunks"; suitable for knowledge bases with long tables or other content that requires more chunks to display in full. Increases input tokens per response | | Conversation Memory Settings | Tool Result Truncation, Maximum Characters per Tool Result | Automatically truncates oversized tool results (such as web search results or code execution output) to prevent memory growth; results exceeding the limit retain content from both the beginning and the end. Enable it when tools frequently return entire HTML pages or large amounts of data | | After Persistent Memory | Enable Claude Streaming Auto-retry | Automatically aborts stalled Claude streaming calls (when the first chunk does not arrive or transmission is interrupted) and retries once in non-streaming mode. Each retry incurs another charge for the same prompt; enable it only when Claude responses frequently stall | | At the Bottom | Enable Automatic Evaluation | When enabled, uses an LLM to automatically score the quality of each conversation in AI Assistant Monitoring. This consumes the organization's usage quota. See [Automatic Evaluation and Agent Monitoring](/maiagent-user-guide/en/build/agent-ops/evaluations.md) | For Vector Memory, Cross-conversation Search, and the Embedding/Reranker models in Conversation Memory Settings, see [Cross-conversation Search](/maiagent-user-guide/en/build/agent/cross-conversation-search.md#other-memory-settings). *** ### Cost Optimization Recommendations #### Calculate Token Consumption Token consumption for a conversation includes: * **Input tokens**: User question + conversation history + system prompt * **Output tokens**: AI response (constrained by this setting) **Example calculation**: ``` Input: User question 50 tokens + conversation history 200 tokens + system prompt 100 tokens = 350 tokens Output: AI response (limit set to 512 tokens) Total: 350 + 512 = 862 tokens (maximum) ``` #### Optimization Strategies 1. **Adjust for the use case** * Use a low token limit for simple questions * Increase the limit only for complex questions 2. **Avoid unnecessarily long responses** * Explicitly request concise answers in the system prompt * Use multi-turn conversations instead of one long response 3. **Review usage regularly** * Go to the Agent's "Usage Analysis" → "Usage Statistics" to review token usage and conversation character count trends * Adjust settings to optimize costs {% hint style="info" %} For detailed cost calculations and optimization recommendations, see [Usage Calculation](/maiagent-user-guide/en/others/usage.md). {% endhint %} *** ### Frequently Asked Questions #### Q: Will AI Responses Be Forcibly Truncated After Setting a Token Limit? **A**: Yes. When an AI-generated response reaches the token limit, it stops at that point, which may leave a sentence incomplete. We recommend: * Set an appropriate limit (not too low) * Ask the model in the system prompt to "end naturally before reaching the character limit" #### Q: How Can I Find Out How Many Tokens My Agent Uses on Average? **A**: Open the Agent's "Usage Analysis" tab and switch to "Usage Statistics". The Token Usage chart lists token counts for each model used by this Agent and total token usage by date. See [Usage Analysis](/maiagent-user-guide/en/build/agent/usage.md) for a description of the chart. #### Q: Does a Higher Token Limit Slow Down Responses? **A**: It has a slight effect. Longer responses take more time to generate, but the difference is usually small (within a few seconds). The main factors remain: * Model selection * Network connection speed * Server load #### Q: Do Different Languages Need Different Token Limits? **A**: Moderate adjustments are recommended: * **Chinese**: The same character count consumes more tokens, so you can raise the limit slightly * **English**: More token-efficient, so a lower limit can be used * **Multilingual environments**: A higher limit is recommended for flexibility #### Q: Does the Token Limit Affect Knowledge Base Retrieval Results? **A**: It does not directly affect retrieval, but it affects how the results are presented: * **High token limit**: Can cite more knowledge base snippets * **Low token limit**: Cites only the most relevant snippets #### Q: How Many Rounds of Tool Calls Can an Agent Make When Answering One Message? **A**: This is determined by Maximum Iterations, which defaults to 20 rounds and can be increased to 100 rounds. It resets for each user message. When the limit is exhausted, the response ends with "This response has reached the tool usage limit for this turn and may be incomplete. Send a follow-up message to continue." This means the limit has taken effect, rather than a malfunction. See [What Happens When the Tool Call Limit Is Reached](#when-tool-limit-reached). #### Q: If I Increase Maximum Iterations, Must I Also Increase the Execution Timeout? **A**: This is strongly recommended, but the system does not require it. The settings are independent: you can save a higher iteration limit without changing the timeout, but execution may be forcibly interrupted by the timeout before reaching your configured iteration limit. Adjust both settings so that "Execution Timeout ÷ Maximum Iterations ≥ 15 seconds" to avoid triggering the yellow warning. #### Q: How Do a Timeout and Exhausted Iterations Differ for the User? **A**: They differ significantly. When the iteration limit is reached first, the Agent summarizes the information it has gathered into a response, and the conversation ends normally. When the execution timeout is triggered first, the conversation is forcibly interrupted and marked as an error. The user sees only any content generated before the timeout (if any), plus the timeout message, without a prepared summary response. Credits already consumed are not refunded. *** ### Testing and Adjustment #### Testing Process 1. **Set an initial value** * Start with a recommended value (such as 1024) 2. **Run test conversations** * Enter typical user questions * Observe response length and completeness 3. **Evaluate the results** * Is the response complete? * Does it contain unnecessary detail? * Is token consumption reasonable? 4. **Adjust gradually** * Too long → lower the token limit * Too short/truncated → raise the token limit 5. **Monitor continuously** * Review usage regularly * Fine-tune according to actual needs #### Test Examples ``` Test 1: Token limit 256 User: Please introduce your company AI: We are a company focused on AI technology, providing enterprise chatbot solutions. [Response truncated] Evaluation: Too short; increase the limit Test 2: Token limit 1024 User: Please introduce your company AI: We are a company focused on AI technology...[Complete, detailed introduction]...Contact us to learn more. Evaluation: Appropriate; use this setting ``` *** ### Related Features {% hint style="info" %} **Additional Features** * [Create an Agent](/maiagent-user-guide/en/build/agent/setup.md) * [System Prompt Design Guide](/maiagent-user-guide/en/build/agent/system-prompt.md) * [Usage Calculation](/maiagent-user-guide/en/others/usage.md) * [Usage Analysis](/maiagent-user-guide/en/build/agent/usage.md) {% endhint %} --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation by asking a question. Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters: ``` GET https://docs.maiagent.ai/maiagent-user-guide/en/build/agent/custom-max-tokens.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.