Examples

Learn Hugin through working examples. Each example demonstrates specific features and patterns.

Getting Started

Example	Description	Key Concepts
basic_agent	Simplest agent setup	Config, Task, Templates, Tools

Start here to understand the basic structure.

Core Patterns

Example	Description	Key Concepts
tool_chaining	Deterministic tool pipelines	next_tool parameter
task_chaining	Sequential task execution	next_task parameter
task_sequences	Multi-stage pipelines	task_sequence, pass_result_as
self_reflection	Self-reflection via task chaining	task_sequence, chain_config, model switching
plan_execute_agent	Config-based state machines	State transitions, mode switching
human_interaction	Human-in-the-loop	AskHuman, approval workflows

Agent Patterns

Example	Description	Key Concepts
reflexion	Multi-agent reflection with critic	launch_agent, sub-agent feedback
heartbeat	Periodic monitoring agent	wait_for_ticks, sensor pattern

Advanced Features

Example	Description	Key Concepts
branching	Parallel exploration	Stack branching, isolation
simple_branching	Basic stack branching	create_branch tool, artifact output
artifacts	Long-term memory	save_insight, query_artifacts
custom_artifacts	Custom artifact types	@Artifact.register, UI components
artifact_feedback	Artifact rating and feedback	rate_artifact, feedback-driven ranking

Multi-Agent

Example	Description	Key Concepts
sub_agent	Parent-child hierarchy	Agent delegation
parallel_agents	Concurrent execution	Session management
agent_messaging	Agent-to-agent communication	Message passing
shared_state	Shared data with access control	Namespaces, permissions

Running Examples

# Clone the repository
git clone https://github.com/gimlelabs/gimle-hugin.git
cd gimle-hugin

# Install dependencies
uv sync --all-extras

# Run an example
uv run hugin run --task hello_world --task-path examples/basic_agent

# With parameters
uv run hugin run --task hello_world --task-path examples/basic_agent \
  --parameters '{"questions": "What is AI?"}'

# With monitoring
uv run hugin run --task hello_world --task-path examples/basic_agent \
  --storage-path ./data/demo

# In another terminal
uv run hugin monitor --storage-path ./data/demo

Demo Apps

More complex applications in the apps/ directory:

App	Description
data_analyst	SQL queries, data transformation, analysis
financial_newspaper	Multi-agent financial journalism workflow
rap_machine	Multi-agent rap battles (fun demo)
the_hugins	Autonomous 2D world simulation

Check them out in the repo, run them, see how they work and have fun extending them!

Running Apps

Apps can be run either via the dedicated app runner (hugin app) or directly with hugin run when the app is a standard agent directory.

# List available apps
uv run hugin apps

# Recommended: use the app runner (uses apps/<name>/run.py when present)
# Note: pass app-specific flags after `--`
uv run hugin app data_analyst

uv run hugin app financial_newspaper -- --symbols AAPL MSFT --incremental --monitor

uv run hugin app rap_machine -- --random-agents --monitor

uv run hugin app the_hugins -- --monitor

See the apps README for details on running these.