feat: enhance knowledge and guardrail event handling in Agent class (#3672)

* feat: enhance knowledge event handling in Agent class

- Updated the Agent class to include task context in knowledge retrieval events.
- Emitted new events for knowledge retrieval and query processes, capturing task and agent details.
- Refactored knowledge event classes to inherit from a base class for better structure and maintainability.
- Added tracing for knowledge events in the TraceCollectionListener to improve observability.

This change improves the tracking and management of knowledge queries and retrievals, facilitating better debugging and performance monitoring.

* refactor: remove task_id from knowledge event emissions in Agent class

- Removed the task_id parameter from various knowledge event emissions in the Agent class to streamline event handling.
- This change simplifies the event structure and focuses on the essential context of knowledge retrieval and query processes.

This refactor enhances the clarity of knowledge events and aligns with the recent improvements in event handling.

* surface association for guardrail events

* fix: improve LLM selection logic in converter

- Updated the logic for selecting the LLM in the convert_with_instructions function to handle cases where the agent may not have a function_calling_llm attribute.
- This change ensures that the converter can still function correctly by falling back to the standard LLM if necessary, enhancing robustness and preventing potential errors.

This fix improves the reliability of the conversion process when working with different agent configurations.

* fix test

* fix: enforce valid LLM instance requirement in converter

- Updated the convert_with_instructions function to ensure that a valid LLM instance is provided by the agent.
- If neither function_calling_llm nor the standard llm is available, a ValueError is raised, enhancing error handling and robustness.
- Improved error messaging for conversion failures to provide clearer feedback on issues encountered during the conversion process.

This change strengthens the reliability of the conversion process by ensuring that agents are properly configured with a valid LLM.

src/crewai/utilities/agent_utils.py

@@ -31,6 +31,7 @@ from crewai.utilities.types import LLMMessage
 
 if TYPE_CHECKING:
     from crewai.agent import Agent
+    from crewai.lite_agent import LiteAgent
     from crewai.task import Task
 
 
@@ -222,7 +223,7 @@ def get_llm_response(
     callbacks: list[Callable[..., Any]],
     printer: Printer,
     from_task: Task | None = None,
-    from_agent: Agent | None = None,
+    from_agent: Agent | LiteAgent | None = None,
 ) -> str:
     """Call the LLM and return the response, handling any invalid responses.
 

src/crewai/utilities/converter.py

@@ -14,6 +14,7 @@ from crewai.utilities.pydantic_schema_parser import PydanticSchemaParser
 
 if TYPE_CHECKING:
     from crewai.agent import Agent
+    from crewai.agents.agent_builder.base_agent import BaseAgent
     from crewai.llm import LLM
     from crewai.llms.base_llm import BaseLLM
 
@@ -143,7 +144,7 @@ def convert_to_model(
     result: str,
     output_pydantic: type[BaseModel] | None,
     output_json: type[BaseModel] | None,
-    agent: Agent | None = None,
+    agent: Agent | BaseAgent | None = None,
     converter_cls: type[Converter] | None = None,
 ) -> dict[str, Any] | BaseModel | str:
     """Convert a result string to a Pydantic model or JSON.
@@ -215,7 +216,7 @@ def handle_partial_json(
     result: str,
     model: type[BaseModel],
     is_json_output: bool,
-    agent: Agent | None,
+    agent: Agent | BaseAgent | None,
     converter_cls: type[Converter] | None = None,
 ) -> dict[str, Any] | BaseModel | str:
     """Handle partial JSON in a result string and convert to Pydantic model or dict.
@@ -260,7 +261,7 @@ def convert_with_instructions(
     result: str,
     model: type[BaseModel],
     is_json_output: bool,
-    agent: Agent | None,
+    agent: Agent | BaseAgent | None,
     converter_cls: type[Converter] | None = None,
 ) -> dict | BaseModel | str:
     """Convert a result string to a Pydantic model or JSON using instructions.
@@ -283,7 +284,12 @@ def convert_with_instructions(
     """
     if agent is None:
         raise TypeError("Agent must be provided if converter_cls is not specified.")
-    llm = agent.function_calling_llm or agent.llm
+
+    llm = getattr(agent, "function_calling_llm", None) or agent.llm
+
+    if llm is None:
+        raise ValueError("Agent must have a valid LLM instance for conversion")
+
     instructions = get_conversion_instructions(model=model, llm=llm)
     converter = create_converter(
         agent=agent,
@@ -299,7 +305,7 @@ def convert_with_instructions(
 
     if isinstance(exported_result, ConverterError):
         Printer().print(
-            content=f"{exported_result.message} Using raw output instead.",
+            content=f"Failed to convert result to model: {exported_result}",
             color="red",
         )
         return result
@@ -308,7 +314,7 @@ def convert_with_instructions(
 
 
 def get_conversion_instructions(
-    model: type[BaseModel], llm: BaseLLM | LLM | str
+    model: type[BaseModel], llm: BaseLLM | LLM | str | Any
 ) -> str:
     """Generate conversion instructions based on the model and LLM capabilities.
 
@@ -357,7 +363,7 @@ class CreateConverterKwargs(TypedDict, total=False):
 
 
 def create_converter(
-    agent: Agent | None = None,
+    agent: Agent | BaseAgent | None = None,
     converter_cls: type[Converter] | None = None,
     *args: Any,
     **kwargs: Unpack[CreateConverterKwargs],

src/crewai/utilities/guardrail.py

@@ -7,7 +7,9 @@ from pydantic import BaseModel, Field, field_validator
 from typing_extensions import Self
 
 if TYPE_CHECKING:
-    from crewai.lite_agent import LiteAgentOutput
+    from crewai.agents.agent_builder.base_agent import BaseAgent
+    from crewai.lite_agent import LiteAgent, LiteAgentOutput
+    from crewai.task import Task
     from crewai.tasks.task_output import TaskOutput
 
 
@@ -79,6 +81,8 @@ def process_guardrail(
     guardrail: Callable[[Any], tuple[bool, Any | str]],
     retry_count: int,
     event_source: Any | None = None,
+    from_agent: BaseAgent | LiteAgent | None = None,
+    from_task: Task | None = None,
 ) -> GuardrailResult:
     """Process the guardrail for the agent output.
 
@@ -95,14 +99,6 @@ def process_guardrail(
         TypeError: If output is not a TaskOutput or LiteAgentOutput
         ValueError: If guardrail is None
     """
-    from crewai.lite_agent import LiteAgentOutput
-    from crewai.tasks.task_output import TaskOutput
-
-    if not isinstance(output, (TaskOutput, LiteAgentOutput)):
-        raise TypeError("Output must be a TaskOutput or LiteAgentOutput")
-    if guardrail is None:
-        raise ValueError("Guardrail must not be None")
-
     from crewai.events.event_bus import crewai_event_bus
     from crewai.events.types.llm_guardrail_events import (
         LLMGuardrailCompletedEvent,
@@ -111,7 +107,12 @@ def process_guardrail(
 
     crewai_event_bus.emit(
         event_source,
-        LLMGuardrailStartedEvent(guardrail=guardrail, retry_count=retry_count),
+        LLMGuardrailStartedEvent(
+            guardrail=guardrail,
+            retry_count=retry_count,
+            from_agent=from_agent,
+            from_task=from_task,
+        ),
     )
 
     result = guardrail(output)
@@ -124,6 +125,8 @@ def process_guardrail(
             result=guardrail_result.result,
             error=guardrail_result.error,
             retry_count=retry_count,
+            from_agent=from_agent,
+            from_task=from_task,
         ),
     )
 

src/crewai/utilities/tool_utils.py

@@ -12,6 +12,7 @@ from crewai.utilities.i18n import I18N
 
 if TYPE_CHECKING:
     from crewai.agent import Agent
+    from crewai.agents.agent_builder.base_agent import BaseAgent
     from crewai.llm import LLM
     from crewai.llms.base_llm import BaseLLM
     from crewai.task import Task
@@ -25,7 +26,7 @@ def execute_tool_and_check_finality(
     agent_role: str | None = None,
     tools_handler: ToolsHandler | None = None,
     task: Task | None = None,
-    agent: Agent | None = None,
+    agent: Agent | BaseAgent | None = None,
     function_calling_llm: BaseLLM | LLM | None = None,
     fingerprint_context: dict[str, str] | None = None,
 ) -> ToolResult: