Agents

An Agent is the central entity in Hugin. It combines a configuration (how it behaves), a task (what it does), and a stack (its history of interactions).

Creating Agents

The standard way to create agents is from tasks:

from gimle.hugin.agent.environment import Environment
from gimle.hugin.agent.session import Session
from gimle.hugin.storage.local import LocalStorage

# Load environment from a directory
storage = LocalStorage(base_path="./storage")
env = Environment.load("./my_agent", storage=storage)
session = Session(environment=env)

# Create agent from task
config = env.config_registry.get("my_config")
task = env.task_registry.get("my_task")
session.create_agent_from_task(config, task)

# Run to completion
agent = session.agents[0]
while agent.step():
    pass

Or run a full session:

session.run()  # Runs all agents to completion

Agent Configuration

Agents are configured via YAML files:

# configs/analyst.yaml
name: analyst
description: Data analysis agent
system_template: analyst_system
llm_model: haiku-latest
tools:
  - builtins.finish:finish
  - builtins.save_insight:save_insight
  - query_database:query_database

Configuration Options

Field	Description
name	Unique identifier
description	Human-readable description
system_template	Name of the template for system prompt
llm_model	Model to use (e.g., haiku-latest, gpt-4o, llama3.2)
tools	List of available tools (format: module:tool_name)

Agent Lifecycle

1. Task Definition - Agent receives initial task prompt
2. Ask Oracle - Agent consults the LLM with current context
3. Oracle Response - LLM returns text or tool calls
4. Tool Call - Agent executes requested tools
5. Tool Result - Results are added to the stack
6. Repeat until task completion or finish tool is called

Multi-Agent Sessions

Multiple agents can run in a session with shared environment:

session = Session(environment=env)

# Create multiple agents
session.create_agent_from_task(config1, task1)
session.create_agent_from_task(config2, task2)

# Run all agents
session.run()

Shared State

Agents can share state via namespaces:

# In a tool, access shared state
shared = stack.get_shared_state("my_namespace")
shared["key"] = "value"
stack.set_shared_state("my_namespace", shared)

See Stacks & Interactions for more on state management.

State Machines

Agents can have dynamic behavior via state machines:

# configs/plan_execute.yaml
name: plan_execute
state_machine:
  initial: planning
  states:
    planning:
      tools: [create_plan, review_plan]
      transitions:
        - on_tool: approve_plan
          to: executing
    executing:
      tools: [execute_step, finish]

This enables agents to change their available tools and behavior based on their current state.