haive.agents.base.agent ======================= .. py:module:: haive.agents.base.agent .. autoapi-nested-parse:: Enhanced Agent hierarchy with engine-focused generics and backward compatibility. This module provides the enhanced agent architecture: - Workflow: Pure orchestration without LLM - Agent: Workflow + Engine (generic on engine type) - MultiAgent: Agent + multi-agent coordination Key features: - Engine-centric generics: Agent[EngineT] - Full backward compatibility with existing code - Clear separation of concerns: orchestration vs LLM vs coordination - Type safety when needed, flexibility when desired Classes ------- .. autoapisummary:: haive.agents.base.agent.Agent haive.agents.base.agent.TypedInvokableEngine Module Contents --------------- .. py:class:: Agent Bases: :py:obj:`TypedInvokableEngine`\ [\ :py:obj:`EngineT`\ ], :py:obj:`haive.agents.base.mixins.execution_mixin.ExecutionMixin`, :py:obj:`haive.agents.base.mixins.state_mixin.StateMixin`, :py:obj:`haive.agents.base.mixins.persistence_mixin.PersistenceMixin`, :py:obj:`haive.agents.base.serialization_mixin.SerializationMixin`, :py:obj:`haive.agents.base.agent_structured_output_mixin.StructuredOutputMixin`, :py:obj:`haive.agents.base.pre_post_agent_mixin.PrePostAgentMixin`, :py:obj:`abc.ABC` Enhanced Agent with engine-focused generics and full backward compatibility. Agent = Workflow + Engine. The engine type is the primary generic parameter, enabling type-safe engine-specific functionality while maintaining full backward compatibility. Generic Parameters: EngineT: Type of engine (defaults to InvokableEngine for backward compatibility) Key Benefits: - Engine-specific type safety: Agent[AugLLMConfig] vs Agent[ReactEngine] - Backward compatible: existing Agent() calls work unchanged - Engine-specific methods: BaseRAGAgent[RetrieverEngine] gets retriever methods - Flexible composition: Any engine type can be used .. rubric:: Examples # Backward compatible - works unchanged agent = SimpleAgent(name="test") # Engine-specific typing aug_agent: SimpleAgent[AugLLMConfig] = SimpleAgent(engine=aug_config) rag_agent: BaseRAGAgent[RetrieverEngine] = BaseRAGAgent(engine=retriever_engine) # Mixed usage - all compatible agents = [agent, aug_agent, rag_agent] .. py:method:: add_hook(event, hook) Add a hook function for an event. .. py:method:: after_arun(func) Decorator to add an after_arun hook. .. py:method:: after_build_graph(func) Decorator to add an after_build_graph hook. .. py:method:: after_grading(func) Decorator to add an after_grading hook. .. py:method:: after_message_transform(func) Decorator to add an after_message_transform hook. .. py:method:: after_reflection(func) Decorator to add an after_reflection hook. .. py:method:: after_run(func) Decorator to add an after_run hook. .. py:method:: after_setup(func) Decorator to add an after_setup hook. .. py:method:: after_state_update(func) Decorator to add an after_state_update hook. .. py:method:: after_structured_output(func) Decorator to add an after_structured_output hook. .. py:method:: before_arun(func) Decorator to add a before_arun hook. .. py:method:: before_build_graph(func) Decorator to add a before_build_graph hook. .. py:method:: before_grading(func) Decorator to add a before_grading hook. .. py:method:: before_message_transform(func) Decorator to add a before_message_transform hook. .. py:method:: before_reflection(func) Decorator to add a before_reflection hook. .. py:method:: before_run(func) Decorator to add a before_run hook. .. py:method:: before_setup(func) Decorator to add a before_setup hook. .. py:method:: before_state_update(func) Decorator to add a before_state_update hook. .. py:method:: before_structured_output(func) Decorator to add a before_structured_output hook. .. py:method:: build_graph() :abstractmethod: Abstract method to build the agent's graph. .. py:method:: clear_hooks(event = None) Clear hooks for an event or all events. .. py:method:: compile(**kwargs) Compile the graph and cache the result. :param \*\*kwargs: Additional compilation arguments :returns: The compiled graph .. py:method:: complete_agent_setup() STEP 2-5: Complete agent setup in proper order. .. py:method:: create_runnable(runnable_config = None) Create and compile the runnable with proper schema kwargs. This implements the abstract method from Engine base class. .. py:method:: execute(input_data) :async: Execute the agent (bridges Workflow API with Agent API). .. py:method:: execute_hooks(event, **context_kwargs) Execute all hooks for an event. .. py:method:: get_engine() Get the main engine with proper typing. .. py:method:: get_input_fields() Return input field definitions as field_name -> (type, default) pairs. This implements the abstract method from Engine base class. .. py:method:: get_output_fields() Return output field definitions as field_name -> (type, default) pairs. This implements the abstract method from Engine base class. .. py:method:: normalize_engines_and_name(values) :classmethod: STEP 1: Normalize engines dict and auto-generate name. .. py:method:: on_error(func) Decorator to add an on_error hook. .. py:method:: post_process(func) Decorator to add a post_process hook. .. py:method:: pre_process(func) Decorator to add a pre_process hook. .. py:method:: remove_hook(event, hook) Remove a hook function. .. py:method:: set_engine(engine) Set the main engine with proper typing. .. py:method:: setup_agent() Hook for subclasses to perform field syncing and custom setup. This method is called BEFORE schema generation and graph building, allowing subclasses to sync fields to engines properly. Override this method in subclasses for custom setup logic. .. py:class:: TypedInvokableEngine Bases: :py:obj:`haive.core.engine.base.InvokableEngine`\ [\ :py:obj:`pydantic.BaseModel`\ , :py:obj:`pydantic.BaseModel`\ ], :py:obj:`Generic`\ [\ :py:obj:`EngineT`\ ] InvokableEngine that's parameterized by the engine type.