agents.simple¶

SimpleAgent Package - Foundation Conversational AI Agents.

This package provides the SimpleAgent, the foundational conversational AI agent in the Haive framework. SimpleAgent is designed for basic conversation, structured output generation, and serves as the building block for more complex agent patterns.

The SimpleAgent is optimized for: - Fast Performance: Ultra-optimized lazy loading achieves sub-3 second import times - Conversation: Natural language dialog with context preservation - Structured Output: Pydantic model-based response formatting - Extensibility: Clean foundation for building specialized agents - State Management: Automatic conversation history and state persistence

Core Architecture:

SimpleAgent is built on the base Agent class and provides these key capabilities:

Conversation Management:

Automatic message history tracking and context preservation
Conversation-aware prompting with chat templates
Memory integration for long-term context retention
Multi-turn dialog support with state continuity

Structured Output Generation:

Pydantic model integration for type-safe responses
JSON schema validation and error handling
Complex data structure generation (lists, nested objects)
Automatic response parsing and validation

Configuration Flexibility:

Dynamic temperature and model parameter adjustment
System message customization for role-playing
Tool integration support through engine configuration
Provider switching (OpenAI, Azure, Anthropic, etc.)

Performance Optimization:

Lazy loading import system for fast startup
Efficient state serialization and persistence
Minimal memory footprint for high-throughput scenarios
Cached graph compilation for repeated executions

Agent Capabilities:

Basic Conversation:

Natural language processing and generation
Context-aware responses with conversation history
Personality and role customization through system messages
Multi-language support through underlying LLM capabilities

Structured Data Generation:

Type-safe output generation using Pydantic models
Complex nested data structure creation
Validation and error handling for malformed outputs
Integration with existing data processing pipelines

State and Memory Management:

Automatic conversation state persistence
Cross-session context preservation
Memory integration for long-term knowledge retention
State migration and version management

Integration Patterns:

Drop-in replacement for basic chatbot functionality
Foundation for building specialized agent types
Multi-agent workflow component integration
API endpoint agent for web service integration

Examples

Basic conversational agent with automatic context management:

from haive.agents.simple import SimpleAgent
from haive.core.engine.aug_llm import AugLLMConfig

# Create basic conversational agent
agent = SimpleAgent(
    name="assistant",
    engine=AugLLMConfig(
        temperature=0.7,
        system_message="You are a helpful AI assistant."
    )
)

# Multi-turn conversation with automatic context
response1 = await agent.arun("Hello, my name is Alice.")
# -> "Hello Alice! It's nice to meet you. How can I help you today?"

response2 = await agent.arun("What's my name?")
# -> "Your name is Alice, as you mentioned in your previous message."

response3 = await agent.arun("Tell me about Python programming.")
# -> Detailed response about Python, remembering context about Alice

Structured output generation with Pydantic models:

from haive.agents.simple import SimpleAgent
from haive.core.engine.aug_llm import AugLLMConfig
from pydantic import BaseModel, Field
from typing import List

# Define output structure
class AnalysisResult(BaseModel):
    sentiment: str = Field(description="positive, negative, or neutral")
    confidence: float = Field(ge=0.0, le=1.0, description="Confidence score")
    key_topics: List[str] = Field(description="Main topics identified")
    summary: str = Field(max_length=200, description="Brief summary")

# Create agent with structured output
analyzer = SimpleAgent(
    name="sentiment_analyzer",
    engine=AugLLMConfig(
        temperature=0.3,  # Lower for consistency
        structured_output_model=AnalysisResult,
        system_message="You are an expert text analyst."
    )
)

# Generate structured output
text = "I absolutely love this new framework! It's intuitive and powerful."
result = await analyzer.arun(f"Analyze this text: {text}")

# result is automatically validated AnalysisResult instance
print(f"Sentiment: {result.sentiment}")  # "positive"
print(f"Confidence: {result.confidence}")  # 0.95
print(f"Topics: {result.key_topics}")  # ["framework", "user experience"]

Role-playing agent with personality customization:

from haive.agents.simple import SimpleAgent
from haive.core.engine.aug_llm import AugLLMConfig

# Create specialized role-playing agent
chef_agent = SimpleAgent(
    name="chef_assistant",
    engine=AugLLMConfig(
        temperature=0.8,  # Higher for creativity
        system_message='''
        You are Chef Auguste, a passionate French chef with 20 years of experience.
        You speak with enthusiasm about cooking and often share personal anecdotes
        from your kitchen. You prefer fresh, seasonal ingredients and traditional
        French techniques, but you're always excited to try fusion approaches.
        '''.strip()
    )
)

# Interact with role-playing personality
response = await chef_agent.arun("How do I make a perfect omelet?")
# -> Response in Chef Auguste's voice with personal cooking stories

Multi-agent integration as building blocks:

from haive.agents.simple import SimpleAgent
from haive.agents.multi import MultiAgent
from haive.core.engine.aug_llm import AugLLMConfig

# Create specialized SimpleAgents for different tasks
researcher = SimpleAgent(
    name="researcher",
    engine=AugLLMConfig(
        temperature=0.4,
        system_message="You are a thorough researcher who gathers comprehensive information."
    )
)

writer = SimpleAgent(
    name="writer",
    engine=AugLLMConfig(
        temperature=0.8,
        system_message="You are a skilled writer who creates engaging, well-structured content."
    )
)

editor = SimpleAgent(
    name="editor",
    engine=AugLLMConfig(
        temperature=0.3,
        system_message="You are a meticulous editor who improves clarity and correctness."
    )
)

# Compose into workflow
content_pipeline = MultiAgent(
    name="content_creation",
    agents=[researcher, writer, editor],
    execution_mode="sequential"
)

# Execute coordinated workflow
result = await content_pipeline.arun("Create an article about renewable energy")

Agent-as-tool pattern for complex systems:

from haive.agents.simple import SimpleAgent
from haive.agents.react import ReactAgent

# Create specialized SimpleAgents
calculator_agent = SimpleAgent(
    name="calculator",
    engine=AugLLMConfig(
        system_message="You are a precise calculator that solves math problems step by step."
    )
)

translator_agent = SimpleAgent(
    name="translator",
    engine=AugLLMConfig(
        system_message="You are an expert translator fluent in many languages."
    )
)

# Convert SimpleAgents to tools
calc_tool = calculator_agent.as_tool(
    name="math_calculator",
    description="Solve mathematical problems and equations"
)

translate_tool = translator_agent.as_tool(
    name="language_translator",
    description="Translate text between different languages"
)

# Use in coordinator agent
coordinator = ReactAgent(
    name="assistant",
    engine=AugLLMConfig(tools=[calc_tool, translate_tool])
)

# Coordinator can now use SimpleAgents as tools
result = await coordinator.arun(
    "Calculate 15% tip on $127.50 and translate the result to Spanish"
)

Performance Characteristics:

Import Performance:

Lazy loading system: Sub-3 second import times
On-demand class instantiation: Only load when accessed
Minimal memory footprint: ~1MB base memory usage
Cached globals: Subsequent access is immediate

Execution Performance:

Simple conversation: 100-500ms depending on LLM provider
Structured output: 200-800ms including validation
Context preservation: <10ms state management overhead
Multi-turn dialog: Efficient history management

Scalability:

Concurrent conversations: 100+ simultaneous agents per process
Memory efficiency: Optimized state serialization
Throughput: 1000+ messages per minute with clustering
State persistence: Handles millions of conversation records

Integration Patterns:

Standalone Usage:

Chatbot applications with persistent context
API endpoints for conversational interfaces
Content generation and analysis services
Role-playing and character simulation

Multi-Agent Building Blocks:

Specialized components in complex workflows
Task-specific agents in coordination patterns
Modular functionality in hierarchical systems
Reusable components across different applications

Tool Integration:

Convert SimpleAgent to tool for use in ReactAgent
Chain multiple SimpleAgents for complex processing
Integration with external APIs and services
Data processing and transformation pipelines

Best Practices:

Agent Design:

Keep SimpleAgent focused on conversation and structured output
Use clear, specific system messages for consistent behavior
Design Pydantic models with clear field descriptions
Test conversation flows with multiple turns

Performance Optimization:

Use appropriate temperature settings for task type
Cache frequently used agents to avoid recompilation
Implement proper error handling for structured output
Monitor memory usage in long-running conversations

Integration Guidelines:

Use SimpleAgent as foundation for specialized agent types
Compose with other agents through MultiAgent patterns
Convert to tools when needed for ReactAgent integration
Implement proper state management for persistent applications

Version History:

v3.0 (Current):

Enhanced hook system with pre/post processing
Improved structured output integration
Agent-as-tool pattern implementation
Performance optimizations and lazy loading

v2.0:

State management and persistence improvements
Multi-turn conversation optimization
Enhanced error handling and validation

v1.0:

Initial SimpleAgent implementation
Basic conversation and structured output
Foundation agent patterns

agents.simple¶

Submodules¶