fix: ensure lite agents course-correct on validation errors

* fix: ensure lite agents course-correct on validation errors

* chore: update cassettes and test expectations

* fix: ensure multiple guardrails propogate

Author: greysonlalonde

lib/crewai/src/crewai/lite_agent.py

@@ -1,6 +1,7 @@
 import asyncio
 from collections.abc import Callable
 import inspect
+import json
 from typing import (
     Any,
     Literal,
@@ -58,7 +59,11 @@
     process_llm_response,
     render_text_description_and_args,
 )
-from crewai.utilities.converter import generate_model_description
+from crewai.utilities.converter import (
+    Converter,
+    ConverterError,
+    generate_model_description,
+)
 from crewai.utilities.guardrail import process_guardrail
 from crewai.utilities.guardrail_types import GuardrailCallable, GuardrailType
 from crewai.utilities.i18n import I18N, get_i18n
@@ -241,14 +246,20 @@ def _original_role(self) -> str:
         """Return the original role for compatibility with tool interfaces."""
         return self.role
 
-    def kickoff(self, messages: str | list[LLMMessage]) -> LiteAgentOutput:
+    def kickoff(
+        self,
+        messages: str | list[LLMMessage],
+        response_format: type[BaseModel] | None = None,
+    ) -> LiteAgentOutput:
         """
         Execute the agent with the given messages.
 
         Args:
             messages: Either a string query or a list of message dictionaries.
                      If a string is provided, it will be converted to a user message.
                      If a list is provided, each dict should have 'role' and 'content' keys.
+            response_format: Optional Pydantic model for structured output. If provided,
+                           overrides self.response_format for this execution.
 
         Returns:
             LiteAgentOutput: The result of the agent execution.
@@ -269,9 +280,13 @@ def kickoff(self, messages: str | list[LLMMessage]) -> LiteAgentOutput:
             self.tools_results = []
 
             # Format messages for the LLM
-            self._messages = self._format_messages(messages)
+            self._messages = self._format_messages(
+                messages, response_format=response_format
+            )
 
-            return self._execute_core(agent_info=agent_info)
+            return self._execute_core(
+                agent_info=agent_info, response_format=response_format
+            )
 
         except Exception as e:
             self._printer.print(
@@ -289,7 +304,9 @@ def kickoff(self, messages: str | list[LLMMessage]) -> LiteAgentOutput:
             )
             raise e
 
-    def _execute_core(self, agent_info: dict[str, Any]) -> LiteAgentOutput:
+    def _execute_core(
+        self, agent_info: dict[str, Any], response_format: type[BaseModel] | None = None
+    ) -> LiteAgentOutput:
         # Emit event for agent execution start
         crewai_event_bus.emit(
             self,
@@ -303,15 +320,29 @@ def _execute_core(self, agent_info: dict[str, Any]) -> LiteAgentOutput:
         # Execute the agent using invoke loop
         agent_finish = self._invoke_loop()
         formatted_result: BaseModel | None = None
-        if self.response_format:
+
+        active_response_format = response_format or self.response_format
+        if active_response_format:
             try:
-                # Cast to BaseModel to ensure type safety
-                result = self.response_format.model_validate_json(agent_finish.output)
+                model_schema = generate_model_description(active_response_format)
+                schema = json.dumps(model_schema, indent=2)
+                instructions = self.i18n.slice("formatted_task_instructions").format(
+                    output_format=schema
+                )
+
+                converter = Converter(
+                    llm=self.llm,
+                    text=agent_finish.output,
+                    model=active_response_format,
+                    instructions=instructions,
+                )
+
+                result = converter.to_pydantic()
                 if isinstance(result, BaseModel):
                     formatted_result = result
-            except Exception as e:
+            except ConverterError as e:
                 self._printer.print(
-                    content=f"Failed to parse output into response format: {e!s}",
+                    content=f"Failed to parse output into response format after retries: {e.message}",
                     color="yellow",
                 )
 
@@ -400,8 +431,14 @@ async def kickoff_async(self, messages: str | list[LLMMessage]) -> LiteAgentOutp
         """
         return await asyncio.to_thread(self.kickoff, messages)
 
-    def _get_default_system_prompt(self) -> str:
-        """Get the default system prompt for the agent."""
+    def _get_default_system_prompt(
+        self, response_format: type[BaseModel] | None = None
+    ) -> str:
+        """Get the default system prompt for the agent.
+
+        Args:
+            response_format: Optional response format to use instead of self.response_format
+        """
         base_prompt = ""
         if self._parsed_tools:
             # Use the prompt template for agents with tools
@@ -422,21 +459,31 @@ def _get_default_system_prompt(self) -> str:
                 goal=self.goal,
             )
 
-        # Add response format instructions if specified
-        if self.response_format:
-            schema = generate_model_description(self.response_format)
+        active_response_format = response_format or self.response_format
+        if active_response_format:
+            model_description = generate_model_description(active_response_format)
+            schema_json = json.dumps(model_description, indent=2)
             base_prompt += self.i18n.slice("lite_agent_response_format").format(
-                response_format=schema
+                response_format=schema_json
             )
 
         return base_prompt
 
-    def _format_messages(self, messages: str | list[LLMMessage]) -> list[LLMMessage]:
-        """Format messages for the LLM."""
+    def _format_messages(
+        self,
+        messages: str | list[LLMMessage],
+        response_format: type[BaseModel] | None = None,
+    ) -> list[LLMMessage]:
+        """Format messages for the LLM.
+
+        Args:
+            messages: Input messages to format
+            response_format: Optional response format to use instead of self.response_format
+        """
         if isinstance(messages, str):
             messages = [{"role": "user", "content": messages}]
 
-        system_prompt = self._get_default_system_prompt()
+        system_prompt = self._get_default_system_prompt(response_format=response_format)
 
         # Add system message at the beginning
         formatted_messages: list[LLMMessage] = [
@@ -506,6 +553,10 @@ def _invoke_loop(self) -> AgentFinish:
 
                 self._append_message(formatted_answer.text, role="assistant")
             except OutputParserError as e:  # noqa: PERF203
+                self._printer.print(
+                    content="Failed to parse LLM output. Retrying...",
+                    color="yellow",
+                )
                 formatted_answer = handle_output_parser_exception(
                     e=e,
                     messages=self._messages,

lib/crewai/src/crewai/task.py

@@ -525,7 +525,11 @@ def _execute_core(
                 tools=tools,
             )
 
-            pydantic_output, json_output = self._export_output(result)
+            if not self._guardrails and not self._guardrail:
+                pydantic_output, json_output = self._export_output(result)
+            else:
+                pydantic_output, json_output = None, None
+
             task_output = TaskOutput(
                 name=self.name or self.description,
                 description=self.description,

lib/crewai/src/crewai/translations/en.json

@@ -22,12 +22,12 @@
     "summarize_instruction": "Summarize the following text, make sure to include all the important information: {group}",
     "summary": "This is a summary of our conversation so far:\n{merged_summary}",
     "manager_request": "Your best answer to your coworker asking you this, accounting for the context shared.",
-    "formatted_task_instructions": "Ensure your final answer contains only the content in the following format: {output_format}\n\nEnsure the final output does not include any code block markers like ```json or ```python.",
+    "formatted_task_instructions": "Ensure your final answer strictly adheres to the following OpenAPI schema: {output_format}\n\nDo not include the OpenAPI schema in the final output. Ensure the final output does not include any code block markers like ```json or ```python.",
     "conversation_history_instruction": "You are a member of a crew collaborating to achieve a common goal. Your task is a specific action that contributes to this larger objective. For additional context, please review the conversation history between you and the user that led to the initiation of this crew. Use any relevant information or feedback from the conversation to inform your task execution and ensure your response aligns with both the immediate task and the crew's overall goals.",
     "feedback_instructions": "User feedback: {feedback}\nInstructions: Use this feedback to enhance the next output iteration.\nNote: Do not respond or add commentary.",
     "lite_agent_system_prompt_with_tools": "You are {role}. {backstory}\nYour personal goal is: {goal}\n\nYou ONLY have access to the following tools, and should NEVER make up tools that are not listed here:\n\n{tools}\n\nIMPORTANT: Use the following format in your response:\n\n```\nThought: you should always think about what to do\nAction: the action to take, only one name of [{tool_names}], just the name, exactly as it's written.\nAction Input: the input to the action, just a simple JSON object, enclosed in curly braces, using \" to wrap keys and values.\nObservation: the result of the action\n```\n\nOnce all necessary information is gathered, return the following format:\n\n```\nThought: I now know the final answer\nFinal Answer: the final answer to the original input question\n```",
     "lite_agent_system_prompt_without_tools": "You are {role}. {backstory}\nYour personal goal is: {goal}\n\nTo give my best complete final answer to the task respond using the exact following format:\n\nThought: I now can give a great answer\nFinal Answer: Your final answer must be the great and the most complete as possible, it must be outcome described.\n\nI MUST use these formats, my job depends on it!",
-    "lite_agent_response_format": "\nIMPORTANT: Your final answer MUST contain all the information requested in the following format: {response_format}\n\nIMPORTANT: Ensure the final output does not include any code block markers like ```json or ```python.",
+    "lite_agent_response_format": "Ensure your final answer strictly adheres to the following OpenAPI schema: {response_format}\n\nDo not include the OpenAPI schema in the final output. Ensure the final output does not include any code block markers like ```json or ```python.",
     "knowledge_search_query": "The original query is: {task_prompt}.",
     "knowledge_search_query_system_prompt": "Your goal is to rewrite the user query so that it is optimized for retrieval from a vector database. Consider how the query will be used to find relevant documents, and aim to make it more specific and context-aware. \n\n Do not include any other text than the rewritten query, especially any preamble or postamble and only add expected output format if its relevant to the rewritten query. \n\n Focus on the key words of the intended task and to retrieve the most relevant information. \n\n There will be some extra context provided that might need to be removed such as expected_output formats structured_outputs and other instructions."
   },

lib/crewai/src/crewai/utilities/converter.py

@@ -10,9 +10,9 @@
 from typing_extensions import Unpack
 
 from crewai.agents.agent_builder.utilities.base_output_converter import OutputConverter
+from crewai.utilities.i18n import get_i18n
 from crewai.utilities.internal_instructor import InternalInstructor
 from crewai.utilities.printer import Printer
-from crewai.utilities.pydantic_schema_parser import PydanticSchemaParser
 
 
 if TYPE_CHECKING:
@@ -22,6 +22,7 @@
     from crewai.llms.base_llm import BaseLLM
 
 _JSON_PATTERN: Final[re.Pattern[str]] = re.compile(r"({.*})", re.DOTALL)
+_I18N = get_i18n()
 
 
 class ConverterError(Exception):
@@ -87,8 +88,7 @@ def to_pydantic(self, current_attempt: int = 1) -> BaseModel:
                             result = self.model.model_validate(result)
                         elif isinstance(result, str):
                             try:
-                                parsed = json.loads(result)
-                                result = self.model.model_validate(parsed)
+                                result = self.model.model_validate_json(result)
                             except Exception as parse_err:
                                 raise ConverterError(
                                     f"Failed to convert partial JSON result into Pydantic: {parse_err}"
@@ -172,6 +172,16 @@ def convert_to_model(
     model = output_pydantic or output_json
     if model is None:
         return result
+
+    if converter_cls:
+        return convert_with_instructions(
+            result=result,
+            model=model,
+            is_json_output=bool(output_json),
+            agent=agent,
+            converter_cls=converter_cls,
+        )
+
     try:
         escaped_result = json.dumps(json.loads(result, strict=False))
         return validate_model(
@@ -251,7 +261,7 @@ def handle_partial_json(
         except json.JSONDecodeError:
             pass
         except ValidationError:
-            pass
+            raise
         except Exception as e:
             Printer().print(
                 content=f"Unexpected error during partial JSON handling: {type(e).__name__}: {e}. Attempting alternative conversion method.",
@@ -335,25 +345,26 @@ def get_conversion_instructions(
     Returns:
 
     """
-    instructions = "Please convert the following text into valid JSON."
+    instructions = ""
     if (
         llm
         and not isinstance(llm, str)
         and hasattr(llm, "supports_function_calling")
         and llm.supports_function_calling()
     ):
-        model_schema = PydanticSchemaParser(model=model).get_schema()
-        instructions += (
-            f"\n\nOutput ONLY the valid JSON and nothing else.\n\n"
-            f"Use this format exactly:\n```json\n{model_schema}\n```"
+        schema_dict = generate_model_description(model)
+        schema = json.dumps(schema_dict, indent=2)
+        formatted_task_instructions = _I18N.slice("formatted_task_instructions").format(
+            output_format=schema
         )
+        instructions += formatted_task_instructions
     else:
         model_description = generate_model_description(model)
-        schema_json = json.dumps(model_description["json_schema"]["schema"], indent=2)
-        instructions += (
-            f"\n\nOutput ONLY the valid JSON and nothing else.\n\n"
-            f"Use this format exactly:\n```json\n{schema_json}\n```"
+        schema_json = json.dumps(model_description, indent=2)
+        formatted_task_instructions = _I18N.slice("formatted_task_instructions").format(
+            output_format=schema_json
         )
+        instructions += formatted_task_instructions
     return instructions
 
 

lib/crewai/tests/agents/test_lite_agent.py

@@ -382,8 +382,8 @@ def capture_guardrail_completed(source, event):
     assert not guardrail_events["completed"][0].success
     assert guardrail_events["completed"][1].success
     assert (
-        "Here are the top 10 best soccer players in the world, focusing exclusively on Brazilian players"
-        in result.raw
+        "top 10 best Brazilian soccer players" in result.raw or
+        "Brazilian players" in result.raw
     )