Tutorials¶

Learn HAP (Haive Agent Protocol) through step-by-step tutorials.

Note

📋 Beta Status: These tutorials are currently in beta. Content and examples may change as HAP evolves. Please report any issues or suggestions!

Tutorial Series:

Tutorial Overview¶

This tutorial series will take you from HAP basics to advanced workflow patterns:

Beginner Tutorials:

Understanding HAP - What is HAP and how it works
Tutorial 2: First Workflow - Coming Soon - Create your first agent workflow
Tutorial 3: Multi-Agent Patterns - Coming Soon - Multi-agent coordination

Intermediate Tutorials:

Tutorial 4: Context Management - Coming Soon - Managing state and context
Tutorial 5: Error Handling - Coming Soon - Robust error handling patterns
Tutorial 6: Advanced Features - Coming Soon - Protocol integration and optimization

Learning Path:

        graph TD
    A[Understanding HAP] --> B[First Workflow]
    B --> C[Multi-Agent Patterns]
    C --> D[Context Management]
    D --> E[Error Handling]
    E --> F[Advanced Features]

    style A fill:#e1f5fe
    style B fill:#f3e5f5
    style C fill:#e8f5e8
    style D fill:#fff3e0
    style E fill:#fce4ec
    style F fill:#f1f8e9

Prerequisites¶

Before starting the tutorials:

Knowledge: * Basic Python programming * Understanding of async/await * Familiarity with AI/LLM concepts

Setup: * HAP installed (see Installation) * LLM API access (OpenAI, Anthropic, etc.) * Code editor with Python support

Tutorial Format¶

Each tutorial includes:

📚 Concepts: Core ideas and theory
💻 Code Examples: Working, runnable code
🔧 Hands-on Exercises: Practice activities
🎯 Key Takeaways: Summary of learning points
➡️ Next Steps: Links to related tutorials

Quick Start Path¶

For the Impatient (30 minutes):

Quick Overview (Understanding HAP - 5 min)
Basic Workflow (Tutorial 2: First Workflow - Coming Soon - 15 min)
Multi-Agent Example (Tutorial 3: Multi-Agent Patterns - Coming Soon - 10 min)

Complete Learning (3-4 hours):

Work through all tutorials in sequence with exercises.

Reference Learning (As needed):

Jump to specific tutorials based on your needs.

Code Examples Repository¶

All tutorial code is available in the examples/tutorials/ directory:

haive-hap/
├── examples/
│   └── tutorials/
│       ├── 01_basic_concepts/
│       │   ├── simple_agent.py
│       │   └── graph_basics.py
│       ├── 02_first_workflow/
│       │   ├── hello_hap.py
│       │   └── agent_with_tools.py
│       ├── 03_multi_agent/
│       │   ├── sequential_flow.py
│       │   ├── parallel_processing.py
│       │   └── conditional_routing.py
│       ├── 04_context/
│       │   ├── state_management.py
│       │   └── context_flow.py
│       ├── 05_error_handling/
│       │   ├── graceful_failures.py
│       │   └── retry_patterns.py
│       └── 06_advanced/
│           ├── protocol_integration.py
│           └── performance_optimization.py

Running Tutorial Examples¶

Setup:

# Navigate to tutorial examples
cd haive-hap/examples/tutorials

# Set up environment
export OPENAI_API_KEY="your-api-key"

# Install dependencies
poetry install

Run Examples:

# Run tutorial 1 examples
poetry run python 01_basic_concepts/simple_agent.py

# Run with debug output
poetry run python 02_first_workflow/hello_hap.py --debug

# Run specific tutorial
poetry run python 03_multi_agent/sequential_flow.py

Interactive Learning¶

Jupyter Notebooks:

Some tutorials include interactive Jupyter notebooks:

# Install Jupyter
poetry add jupyter

# Start notebook server
poetry run jupyter notebook examples/tutorials/

# Open tutorial notebooks
# 01_Understanding_HAP.ipynb
# 02_Building_Workflows.ipynb

Interactive Shell:

Experiment with HAP in an interactive Python shell:

# Start interactive session
poetry run python

# Import HAP components
>>> from haive.hap.models import HAPGraph
>>> from haive.hap.server.runtime import HAPRuntime
>>>
>>> # Create and experiment with HAP objects
>>> graph = HAPGraph()
>>> graph.add_entrypoint_node("test", "haive.agents.simple:SimpleAgent")
>>> print(graph.nodes)

Tutorial Difficulty Levels¶

🟢 Beginner - New to HAP: * Tutorial 1: Understanding HAP * Tutorial 2: First Workflow

🟡 Intermediate - Basic HAP experience: * Tutorial 3: Multi-Agent Patterns * Tutorial 4: Context Management * Tutorial 5: Error Handling

🔴 Advanced - Production HAP usage: * Tutorial 6: Advanced Features * Custom protocol integration * Performance optimization

Common Tutorial Patterns¶

Each tutorial follows this structure:

Learning Objectives - What you’ll achieve
Background - Context and theory
Step-by-Step Guide - Hands-on implementation
Code Walkthrough - Detailed explanation
Exercises - Practice activities
Troubleshooting - Common issues and solutions
Summary - Key takeaways
Next Steps - Where to go next

Tutorial Code Style:

"""Tutorial X: Topic Name

Learning objectives:
- Objective 1
- Objective 2
- Objective 3

Prerequisites:
- Prerequisite 1
- Prerequisite 2
"""

import asyncio
from haive.hap.models import HAPGraph
from haive.hap.server.runtime import HAPRuntime


async def main():
    """Main tutorial function with clear steps."""
    print("🚀 Starting Tutorial X: Topic Name")

    # Step 1: Setup
    print("\n📝 Step 1: Setting up components")
    # ... implementation

    # Step 2: Build
    print("\n🔧 Step 2: Building the workflow")
    # ... implementation

    # Step 3: Execute
    print("\n▶️ Step 3: Running the workflow")
    # ... implementation

    print("\n✅ Tutorial X complete!")
    return result


if __name__ == "__main__":
    asyncio.run(main())

Getting Help¶

During Tutorials:

Code Issues: Check the troubleshooting section in each tutorial
Concept Questions: Refer to the Overview and HAP Models documentation
API Reference: Use API Reference for detailed API docs
Examples: Look at additional examples in examples/ directory

Community Support:

GitHub Discussions: Ask questions and share insights
Issue Tracker: Report bugs or request clarifications
Discord/Slack: Real-time community help

Self-Help Tips:

# Enable debug logging for better error messages
import logging
logging.basicConfig(level=logging.DEBUG)

# Use Python help() function
from haive.hap.models import HAPGraph
help(HAPGraph.add_agent_node)

# Check object attributes
graph = HAPGraph()
print(dir(graph))  # See all available methods

Tutorial Completion¶

Track Your Progress:

[ ] Tutorial 1: Understanding HAP
[ ] Tutorial 2: First Workflow
[ ] Tutorial 3: Multi-Agent Patterns
[ ] Tutorial 4: Context Management
[ ] Tutorial 5: Error Handling
[ ] Tutorial 6: Advanced Features

Certificate of Completion:

After completing all tutorials, you’ll have learned:

Core HAP concepts and architecture
Single and multi-agent workflow patterns
Context and state management
Error handling and resilience
Advanced features and optimization
Production deployment considerations

Next Learning Paths:

Agent Development: Learn to build custom agents
Tool Integration: Connect external tools and APIs
Production Deployment: Scale HAP for production use
Protocol Extension: Build custom HAP protocol features

Ready to start? Begin with Understanding HAP!