haive.agents.conversation.base.agent
====================================

.. py:module:: haive.agents.conversation.base.agent

.. autoapi-nested-parse::

   Base conversation agent providing core multi-agent conversation functionality.

   This base class handles the orchestration of conversations between multiple agents,
   with support for different conversation modes and patterns. It implements the core
   graph-based state management system that all conversation types extend.

   The BaseConversationAgent provides:

   1. A common orchestration flow for all conversation types
   2. Agent compilation and execution management
   3. Message routing and processing
   4. Automatic state tracking via reducers
   5. Conversation initialization and conclusion
   6. Extension points for specialized conversation behaviors

   The conversation flow follows a standard pattern:
   initialize → select_speaker → execute_agent → process_response → check_end → conclude

   Each conversation type extends this base by implementing the abstract methods,
   particularly the `select_speaker` method that defines the conversation pattern.



Classes
-------

.. autoapisummary::

   haive.agents.conversation.base.agent.BaseConversationAgent


Module Contents
---------------

.. py:class:: BaseConversationAgent

   Bases: :py:obj:`haive.agents.base.agent.Agent`


   Base conversation agent that orchestrates multi-agent conversations.

   This abstract base class provides the core functionality for managing
   conversations between multiple agents, with hooks for customization.

   The BaseConversationAgent implements a graph-based conversation flow
   that all specialized conversation types extend and customize. It handles
   agent compilation, message routing, state tracking, and conversation
   lifecycle management.

   .. attribute:: participant_agents

      Mapping of participant names to agent instances or configs.

      :type: Dict[str, Union[SimpleAgent, AugLLMConfig]]

   .. attribute:: topic

      The conversation topic.

      :type: str

   .. attribute:: max_rounds

      Maximum number of conversation rounds.

      :type: int

   .. attribute:: mode

      Conversation mode identifier (e.g., "round_robin", "debate").

      :type: str

   .. attribute:: recursion_limit

      Maximum recursion depth for agent execution.

      :type: int

   .. attribute:: handle_errors

      Whether to handle agent execution errors gracefully.

      :type: bool

   .. attribute:: max_turns_safety

      Absolute maximum turns as a safety limit.

      :type: int

   .. note::

      This is an abstract base class. Concrete conversation types must implement
      at minimum the `select_speaker` method to define their conversation pattern.


   .. py:method:: build_graph()

      Build the conversation graph.



   .. py:method:: check_end(state)

      Check if conversation should end.



   .. py:method:: conclude_conversation(state)

      Create final conclusion for the conversation.



   .. py:method:: convert_persistence_boolean(values)
      :classmethod:


      Convert persistence=True to actual persistence configuration.



   .. py:method:: create(participants, **kwargs)
      :classmethod:


      Create a conversation with participants.



   .. py:method:: execute_agent(state)

      Execute the current speaker's agent.



   .. py:method:: get_conversation_state_schema()

      Get the state schema for this conversation type.

      Override in subclasses to provide custom state schemas.



   .. py:method:: get_input_fields()

      Define input fields.



   .. py:method:: get_output_fields()

      Define output fields.



   .. py:method:: initialize_conversation(state)

      Initialize the conversation.



   .. py:method:: process_response(state)

      Process the agent's response.

      Override in subclasses to add custom response processing.



   .. py:method:: run(input_data = None, **kwargs)

      Run the conversation by invoking the graph directly with proper state.

      Bypasses execution_mixin to ensure the correct state schema is used.



   .. py:method:: select_speaker(state)
      :abstractmethod:


      Select the next speaker in the conversation.

      This is the primary method that defines the conversation pattern and must
      be implemented by all conversation type subclasses. It determines which
      participant should speak next based on the current conversation state.

      The implementation of this method defines the fundamental behavior of each
      conversation type. For example:
      - Round-robin conversations select speakers in a fixed rotating order
      - Debate conversations select based on debate phase and structure
      - Directed conversations use a moderator to select the next speaker

      :param state: The current conversation state, containing speakers,
                    message history, and conversation metadata.
      :type state: Any

      :returns:

                A langgraph Command object with state updates. Must include either:
                    - update={"current_speaker": speaker_name} to continue conversation
                    - update={"current_speaker": None, "conversation_ended": True} to end
      :rtype: Command

      :raises NotImplementedError: If not implemented by a subclass.

      .. note::

         This is the core method that differentiates conversation types. Each
         subclass must implement this method to define its unique conversation pattern.



   .. py:method:: setup_agent()

      Set up the conversation orchestrator.

      This method performs critical initialization steps for the conversation agent:

      1. Configures the state schema for conversation tracking
      2. Creates a default orchestrator engine if none is provided
      3. Compiles all participant agents to ensure they're ready for execution
      4. Sets up persistence if persistence=True was passed

      This method is called automatically during the agent's lifecycle and
      should rarely need to be called directly.

      :returns: None