agents.base.agent

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

Agent	Enhanced Agent with engine-focused generics and full backward compatibility.
TypedInvokableEngine	InvokableEngine that's parameterized by the engine type.

Module Contents

class agents.base.agent.Agent

Bases: TypedInvokableEngine[EngineT], haive.agents.base.mixins.execution_mixin.ExecutionMixin, haive.agents.base.mixins.state_mixin.StateMixin, haive.agents.base.mixins.persistence_mixin.PersistenceMixin, haive.agents.base.serialization_mixin.SerializationMixin, haive.agents.base.agent_structured_output_mixin.StructuredOutputMixin, haive.agents.base.pre_post_agent_mixin.PrePostAgentMixin, 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

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]

add_hook(event, hook)

Add a hook function for an event.

Parameters:

• event (haive.agents.base.hooks.HookEvent)

• hook (haive.agents.base.hooks.HookFunction)

Return type:

None

after_arun(func)

Decorator to add an after_arun hook.

Parameters:

func (haive.agents.base.hooks.HookFunction)

Return type:

haive.agents.base.hooks.HookFunction

after_build_graph(func)

Decorator to add an after_build_graph hook.

Parameters:

func (haive.agents.base.hooks.HookFunction)

Return type:

haive.agents.base.hooks.HookFunction

after_grading(func)

Decorator to add an after_grading hook.

Parameters:

func (haive.agents.base.hooks.HookFunction)

Return type:

haive.agents.base.hooks.HookFunction

after_message_transform(func)

Decorator to add an after_message_transform hook.

Parameters:

func (haive.agents.base.hooks.HookFunction)

Return type:

haive.agents.base.hooks.HookFunction

after_reflection(func)

Decorator to add an after_reflection hook.

Parameters:

func (haive.agents.base.hooks.HookFunction)

Return type:

haive.agents.base.hooks.HookFunction

after_run(func)

Decorator to add an after_run hook.

Parameters:

func (haive.agents.base.hooks.HookFunction)

Return type:

haive.agents.base.hooks.HookFunction

after_setup(func)

Decorator to add an after_setup hook.

Parameters:

func (haive.agents.base.hooks.HookFunction)

Return type:

haive.agents.base.hooks.HookFunction

after_state_update(func)

Decorator to add an after_state_update hook.

Parameters:

func (haive.agents.base.hooks.HookFunction)

Return type:

haive.agents.base.hooks.HookFunction

after_structured_output(func)

Decorator to add an after_structured_output hook.

Parameters:

func (haive.agents.base.hooks.HookFunction)

Return type:

haive.agents.base.hooks.HookFunction

before_arun(func)

Decorator to add a before_arun hook.

Parameters:

func (haive.agents.base.hooks.HookFunction)

Return type:

haive.agents.base.hooks.HookFunction

before_build_graph(func)

Decorator to add a before_build_graph hook.

Parameters:

func (haive.agents.base.hooks.HookFunction)

Return type:

haive.agents.base.hooks.HookFunction

before_grading(func)

Decorator to add a before_grading hook.

Parameters:

func (haive.agents.base.hooks.HookFunction)

Return type:

haive.agents.base.hooks.HookFunction

before_message_transform(func)

Decorator to add a before_message_transform hook.

Parameters:

func (haive.agents.base.hooks.HookFunction)

Return type:

haive.agents.base.hooks.HookFunction

before_reflection(func)

Decorator to add a before_reflection hook.

Parameters:

func (haive.agents.base.hooks.HookFunction)

Return type:

haive.agents.base.hooks.HookFunction

before_run(func)

Decorator to add a before_run hook.

Parameters:

func (haive.agents.base.hooks.HookFunction)

Return type:

haive.agents.base.hooks.HookFunction

before_setup(func)

Decorator to add a before_setup hook.

Parameters:

func (haive.agents.base.hooks.HookFunction)

Return type:

haive.agents.base.hooks.HookFunction

before_state_update(func)

Decorator to add a before_state_update hook.

Parameters:

func (haive.agents.base.hooks.HookFunction)

Return type:

haive.agents.base.hooks.HookFunction

before_structured_output(func)

Decorator to add a before_structured_output hook.

Parameters:

func (haive.agents.base.hooks.HookFunction)

Return type:

haive.agents.base.hooks.HookFunction

abstractmethod build_graph()

Abstract method to build the agent’s graph.

Return type:

haive.core.graph.state_graph.base_graph2.BaseGraph

clear_hooks(event=None)

Clear hooks for an event or all events.

Parameters:

event (haive.agents.base.hooks.HookEvent | None)

Return type:

None

compile(**kwargs)

Compile the graph and cache the result.

Parameters:

**kwargs – Additional compilation arguments

Returns:

The compiled graph

Return type:

Any

complete_agent_setup()

STEP 2-5: Complete agent setup in proper order.

create_runnable(runnable_config=None)

Create and compile the runnable with proper schema kwargs.

This implements the abstract method from Engine base class.

Parameters:

runnable_config (dict[str, Any] | None)

Return type:

Any

async execute(input_data)

Execute the agent (bridges Workflow API with Agent API).

Parameters:

input_data (Any)

Return type:

Any

execute_hooks(event, **context_kwargs)

Execute all hooks for an event.

Parameters:

event (haive.agents.base.hooks.HookEvent)

Return type:

list[Any]

get_engine()

Get the main engine with proper typing.

Return type:

EngineT | None

get_input_fields()

Return input field definitions as field_name -> (type, default) pairs.

This implements the abstract method from Engine base class.

Return type:

dict[str, tuple[type, Any]]

get_output_fields()

Return output field definitions as field_name -> (type, default) pairs.

This implements the abstract method from Engine base class.

Return type:

dict[str, tuple[type, Any]]

classmethod normalize_engines_and_name(values)

STEP 1: Normalize engines dict and auto-generate name.

Parameters:

values (dict[str, Any])

Return type:

dict[str, Any]

on_error(func)

Decorator to add an on_error hook.

Parameters:

func (haive.agents.base.hooks.HookFunction)

Return type:

haive.agents.base.hooks.HookFunction

post_process(func)

Decorator to add a post_process hook.

Parameters:

func (haive.agents.base.hooks.HookFunction)

Return type:

haive.agents.base.hooks.HookFunction

pre_process(func)

Decorator to add a pre_process hook.

Parameters:

func (haive.agents.base.hooks.HookFunction)

Return type:

haive.agents.base.hooks.HookFunction

remove_hook(event, hook)

Remove a hook function.

Parameters:

• event (haive.agents.base.hooks.HookEvent)

• hook (haive.agents.base.hooks.HookFunction)

Return type:

None

set_engine(engine)

Set the main engine with proper typing.

Parameters:

engine (EngineT)

Return type:

None

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.

Return type:

None

class agents.base.agent.TypedInvokableEngine

Bases: haive.core.engine.base.InvokableEngine[pydantic.BaseModel, pydantic.BaseModel], Generic[EngineT]

InvokableEngine that’s parameterized by the engine type.