LLM misinterprets "Plain text responses are not permitted" message as coming from the user

[hovi]

Description

Simple currently working usecase

I am running tool, my LLM responds with plaintext and gets user response:

Plain text responses are not permitted, please include your response in a tool call

Fix the errors and try again.

LLM retries, responds with the correct tool call and everything is fine.

Problem

The problem happens, when the LLM assumes, that this message is from "user" as the rest of chat history (like initial chat message), then it gets confused about the "user" wanting 2 conflicting things. It doesn't understand, that this is not a "real user message", but just a validator feedback.

When I customized the library and modified the feedback text to:

Validator feedback (not from the user):
Plain text responses are not permitted, please include your response in a tool call

Fix the errors and try again.

Suddenly LLM was able to figure out what is happening and my flow works correctly.

Example

Example output, where LLM gets confused and stack between sending plaintext responses and calling the same tool over and over again incorrectly:

<think> Okay, the user wants to connect to a human representative but hasn't provided their email or phone number. The assistant tried to ask for them, but the user's previous message was a tool call that failed because the required info was missing. Now, the user is reminding us to fix the errors and try again.

The problem is that the assistant can't make a tool call without the required info. So the assistant needs to prompt the user to provide their email or phone number. The user's current message is asking for plain text responses to be included in a tool call, but the assistant can't do that without the necessary info.

The assistant should respond by asking the user to provide their email or phone number so that it can proceed with connecting them. This way, the user's information is collected, and the tool call can be made once the required data is available.

The assistant should maintain a polite and helpful tone, ensuring the user understands that they need to provide the necessary details for the connection to happen. Once the user provides the info, the assistant can call the connect_to_human function with the available data. </think>

I'm sorry, but I can't connect you to a human representative right now because I don't have your email or phone number. Could you please provide those details so I can forward your request accordingly?

Solution

I want to be flexible and to use wording that aligns as much as possible with what my agent is trying to achieve and minimize anything confusing, therefore I need to be able to modify these texts (also think about i18n).

I think for now I need to make configurable just this line:

#messages.py
return f'{description}\n\nFix the errors and try again.'

But I may end up wanting to modify even specific tool validation messages in _agent_graph.py like "Plain text responses are not permitted, please include your response in a tool call" mentioned above.

Would be good to do this on per-tool basis rather than global or per-agent. Not sure how to approach this exactly as I am not that much familiar with the library yet. Happy to implement this and make PR, just need some direction to make sure I take the right approach and have good chances of doing it well and merging.

References

No response

[DouweM]

@hovi Can you please share what model you're using, and how you're configuring your agent's output type? Some minimal reproducible code would be useful. Models typically don't run into this error because if they're not allowed to use plain text response, we tell them they have to use a tool, so I'm curious why that's not happening here.

Note that typically when RetryPromptPart is sent to the model, it's as a tool response because the tool args were invalid, so the model will know it's not a user message. It's just when the model responds with invalid text output that we have no other option than to send it as a user message. I agree we could tweak the message to make it clear to the LLM to that it's not actually coming from the user.

I also agree it'd be good to let users customize built-in messages on a global or per-agent basis for i18n reasons. Can you please file a new issue for that, so we can focus on the specific issue you ran into here?

[hovi]

Hi @DouweM
This gist is fairly stable and fails 95% of the time after 5 retries, the model used is qwen3:1.7b, running locally. I included 2 sample run logs without and with patched RetryPromptPart that adds Validator feedback:\n prefix to the user message.
https://gist.github.com/hovi/085915b0974bc786c8f83c0bfef28789

For the context, this works fine most of the time on bigger models (qwen3:4b recovers after 1 retry most of the time), I am running my benchmarks on purpose on various LLMs, including relatively "dumb" ones like this one.
The goal is to find weak spots in the agent system that can be improved and clarified to minimize ambiguity and LLM confusion when tasks get more complex and this seems to be one of them.

Happy to create the issue, but I am not sure how do you want to separate and what stays in this issue. Are we talking about changing the original hard-coded value for the library or keeping it and adding possibility to customize it? Is the other issue supposed to be just i18n or also ability to customize?

[DouweM]

@hovi It seems like Qwen is not respecting the tool_choice = 'required' param, so it's depending exclusively on the prompt guidance.

Still, reading the model thoughts in your gist, I'm surprised by how long it takes it to realize there's a respond_to_user tool it should use, even with your updated "Validation feedback" message. Even when it manages to recover there are a ton of wasted tokens.

In any case, I agree it makes sense to add a clear indication this is not a user message if the RetryPromptPart was not coming from a tool call. Would you be up for submitting a PR that modifies RetryPromptPart.model_response() to include that prefix if tool_name is None?

Happy to create the issue, but I am not sure how do you want to separate and what stays in this issue. Are we talking about changing the original hard-coded value for the library or keeping it and adding possibility to customize it? Is the other issue supposed to be just i18n or also ability to customize?

In this issue, I'd like to fix RetryPromptPart specifically, in a second issue we can consider making all hard-coded strings customizable.

[lanyuer]

I've also encountered this issue several times, but I haven't compiled a dedicated set of reproduction cases yet.