API Reference

This reference covers the main classes and interfaces in Hugin.

Agent

The main entity that executes tasks.

from gimle.hugin.agent.agent import Agent

Creating Agents

# From task (recommended)
agent = Agent.create_from_task(config, task, session)

# Direct creation
agent = Agent(config=config, task=task, session=session)

Methods

Method	Description
step()	Execute one step. Returns True if more steps remain.
run()	Run to completion.
get_result()	Get the final result after completion.

Properties

Property	Description
stack	The interaction stack
config	Current configuration
task	Current task
session	Parent session
environment	Environment with registries

Session

Manages multiple agents and provides shared environment.

from gimle.hugin.agent.session import Session

Creating Sessions

session = Session(environment=env)

Methods

Method	Description
create_agent_from_task(config, task)	Create and add an agent
run()	Run all agents to completion
get_agent(name)	Get agent by name

Properties

Property	Description
agents	List of agents
environment	Shared environment
state	Session-wide shared state

Environment

Provides access to registries and storage.

from gimle.hugin.agent.environment import Environment

Loading

# From directory
env = Environment.load("./my_agent", storage=storage)

# With environment variables
env = Environment.load(
    "./my_agent",
    storage=storage,
    env_vars={"API_KEY": "xxx"}
)

Properties

Property	Description
config_registry	Agent configurations
task_registry	Task definitions
template_registry	Jinja2 templates
tool_registry	Available tools
storage	Storage backend
env_vars	Environment variables

Stack

Manages the interaction history.

from gimle.hugin.interaction.stack import Stack

Methods

Method	Description
push(interaction)	Add interaction to stack
get_context()	Get context for LLM call
create_branch(name)	Create a parallel branch
get_branch_context(branch_id)	Get branch-specific context
get_shared_state(namespace)	Get shared state
set_shared_state(namespace, state)	Set shared state

Storage

Interface for persisting agent state.

from gimle.hugin.storage.local import LocalStorage

LocalStorage

storage = LocalStorage(base_path="./storage")

File-based storage for development and single-machine deployments.

CLI Commands

run-agent

uv run run-agent --task <task_name> --task-path <path>

Option	Description
--task	Name of task to run (required)
--task-path	Path to agent directory (required)
--config	Config name (default: first in registry)
--max-steps	Maximum steps (default: 10)
--storage-path	Storage directory (default: ./storage)
--log-level	DEBUG, INFO, WARNING, ERROR (default: INFO)
--parameters	JSON parameters for task
--env-vars	JSON environment variables

monitor-agents

uv run monitor-agents --storage-path <path>

Option	Description
--storage-path	Path to agent storage (required)
--port	Server port (default: 8000)
--no-browser	Don't open browser automatically

hugin create

hugin create

Interactive wizard to create a new agent.

Development

Running Tests

uv run pytest                    # All tests
uv run pytest --cov              # With coverage
uv run pytest -m unit            # Unit tests only
uv run pytest -m integration     # Integration tests only

Code Quality

uv run pre-commit run --all-files   # All checks
uv run black .                       # Format
uv run isort .                       # Sort imports
uv run flake8 .                      # Lint
uv run mypy .                        # Type check