agents.conversation.base.agent

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

BaseConversationAgent

Base conversation agent that orchestrates multi-agent conversations.

Module Contents

class agents.conversation.base.agent.BaseConversationAgent

Bases: 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.

participant_agents

Mapping of participant names to agent instances or configs.

Type:

Dict[str, Union[SimpleAgent, AugLLMConfig]]

topic

The conversation topic.

Type:

str

max_rounds

Maximum number of conversation rounds.

Type:

int

mode

Conversation mode identifier (e.g., “round_robin”, “debate”).

Type:

str

recursion_limit

Maximum recursion depth for agent execution.

Type:

int

handle_errors

Whether to handle agent execution errors gracefully.

Type:

bool

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.

build_graph()

Build the conversation graph.

Return type:

haive.core.graph.state_graph.base_graph2.BaseGraph

check_end(state)

Check if conversation should end.

Parameters:

state (Any)

Return type:

langgraph.types.Command

conclude_conversation(state)

Create final conclusion for the conversation.

Parameters:

state (Any)

Return type:

langgraph.types.Command

classmethod convert_persistence_boolean(values)

Convert persistence=True to actual persistence configuration.

Parameters:

values (dict[str, Any])

Return type:

dict[str, Any]

classmethod create(participants, **kwargs)

Create a conversation with participants.

Parameters:

participants (dict[str, haive.agents.simple.agent.SimpleAgent | haive.core.engine.aug_llm.AugLLMConfig])

Return type:

BaseConversationAgent

execute_agent(state)

Execute the current speaker’s agent.

Parameters:

state (Any)

Return type:

langgraph.types.Command

get_conversation_state_schema()

Get the state schema for this conversation type.

Override in subclasses to provide custom state schemas.

Return type:

type

get_input_fields()

Define input fields.

Return type:

dict[str, tuple[type, Any]]

get_output_fields()

Define output fields.

Return type:

dict[str, tuple[type, Any]]

initialize_conversation(state)

Initialize the conversation.

Parameters:

state (Any)

Return type:

langgraph.types.Command

process_response(state)

Process the agent’s response.

Override in subclasses to add custom response processing.

Parameters:

state (Any)

Return type:

langgraph.types.Command

abstractmethod select_speaker(state)

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

Parameters:

state (Any) – The current conversation state, containing speakers, message history, and conversation metadata.

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

Return type:

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.

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

Return type:

None