From 50013bd939f0f34e872d589f0e578d25b06ab050 Mon Sep 17 00:00:00 2001 From: Dean Schmigelski Date: Wed, 30 Jul 2025 16:40:28 -0400 Subject: [PATCH 1/3] docs(agent-loop): add troubleshooting to agent loop section --- docs/user-guide/concepts/agents/agent-loop.md | 14 ++++++++++++++ 1 file changed, 14 insertions(+) diff --git a/docs/user-guide/concepts/agents/agent-loop.md b/docs/user-guide/concepts/agents/agent-loop.md index 958beb3a..74a363fb 100644 --- a/docs/user-guide/concepts/agents/agent-loop.md +++ b/docs/user-guide/concepts/agents/agent-loop.md @@ -189,3 +189,17 @@ This recursive nature allows for complex workflows like: ### 7. Completion The loop completes when the model generates a final text response or an exception occurs that cannot be handled. At completion, metrics and traces are collected, conversation state is updated, and the final response is returned to the caller. + +## Troubleshooting + +### MaxTokensReachedException + +This exception indicates that the agent has reached an unrecoverable state because the `max_tokens` stop reason was returned from the model provider. When this occurs, the agent cannot continue processing and the loop terminates. + +**Common causes and solutions:** + +1. **Increase token limits**: If you have explicitly set a `max_tokens` limit in your model configuration, consider raising it to allow for longer responses. + +2. **Audit your tool specifications**: A frequent cause of this exception is tool specifications that prompt the model to return excessively large `toolUse` responses. Review your tools for large JSON schemas, tool specs with many fields or deeply nested structures can consume significant tokens. Also, consider long string requirements which may bloat the output (e.g., "provide a string that is 101k characters long"). + +3. **Optimize tool design**: Consider breaking down complex tools into smaller, more focused tools, or simplifying tool input/output schemas to reduce token consumption. From ff7291208948d27714697eb4e75b7c77d62e7ae7 Mon Sep 17 00:00:00 2001 From: Dean Schmigelski Date: Wed, 30 Jul 2025 16:55:25 -0400 Subject: [PATCH 2/3] fix: sync naming --- docs/user-guide/concepts/agents/agent-loop.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/user-guide/concepts/agents/agent-loop.md b/docs/user-guide/concepts/agents/agent-loop.md index 74a363fb..a019ef72 100644 --- a/docs/user-guide/concepts/agents/agent-loop.md +++ b/docs/user-guide/concepts/agents/agent-loop.md @@ -192,7 +192,7 @@ The loop completes when the model generates a final text response or an exceptio ## Troubleshooting -### MaxTokensReachedException +### EventLoopMaxTokensReachedException This exception indicates that the agent has reached an unrecoverable state because the `max_tokens` stop reason was returned from the model provider. When this occurs, the agent cannot continue processing and the loop terminates. From c3cab56a37f15240a1b455282cfc9ab6c90bb59a Mon Sep 17 00:00:00 2001 From: Dean Schmigelski Date: Thu, 31 Jul 2025 10:52:55 -0400 Subject: [PATCH 3/3] Update agent-loop.md --- docs/user-guide/concepts/agents/agent-loop.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/user-guide/concepts/agents/agent-loop.md b/docs/user-guide/concepts/agents/agent-loop.md index a019ef72..74a363fb 100644 --- a/docs/user-guide/concepts/agents/agent-loop.md +++ b/docs/user-guide/concepts/agents/agent-loop.md @@ -192,7 +192,7 @@ The loop completes when the model generates a final text response or an exceptio ## Troubleshooting -### EventLoopMaxTokensReachedException +### MaxTokensReachedException This exception indicates that the agent has reached an unrecoverable state because the `max_tokens` stop reason was returned from the model provider. When this occurs, the agent cannot continue processing and the loop terminates.