Skip to content
HICA Documentation

HICA

Highly Customizable Agent Library - Build AI agents you can trust, trace, and control—every step, every decision.
Get Started View on GitHub

What is HICA?

Section titled “What is HICA?”

HICA is a design principle put together in a framework for building customisable, deterministic AI agents. Unlike most frameworks, HICA gives you full control and visibility over every step of your agent’s reasoning, tool use, and state.

Agent Loop

How HICA Works

Section titled “How HICA Works”

HICA agents operate in a Thought → Action → Observation loop:

  1. Thought: The LLM decides what to do next (call a tool, ask for clarification, or finish).
  2. Action: The agent executes a tool (local or remote) or asks the user for input.
  3. Observation: The agent records the result and reasons about the next step.

All steps are recorded as Event objects in a Thread, which can be saved, resumed, and audited.

Agent Workflow

Core Features

Section titled “Core Features”

Total Control

Own every prompt, tool call, and context window. Customize prompts, context, and workflows for maximum control.

MCP First-Class Citizen

Use any tool you like - MCP tools or local. Seamlessly integrate remote MCP tools alongside local Python tools.

Human-in-the-Loop

Native clarifications workflow for trustable agent interactions. Agents can request approvals at any step.

Structured Tool Output

Tools return both human-readable content for display and clean, structured JSON for the LLM.

Observable & Auditable

Every action is recorded as an Event in a persistent Thread, providing complete traceability.

Stateful by Design

State is externalized and persisted outside the agent process for scalability and reliability.

Quick Start

Section titled “Quick Start”
from hica.tools import ToolRegistry
from hica.agent import Agent, AgentConfig
from hica.core import Thread, Event


# Register a tool
registry = ToolRegistry()


@registry.tool()
def add(a: int, b: int) -> int:
    "Add two numbers"
    return a + b


# Create an agent
agent = Agent(
    config=AgentConfig(model="gpt-4o-mini"),
    tool_registry=registry
)


# Run the agent
thread = Thread(events=[Event(type="user_input", data="What is 3 + 4?")])
async for _ in agent.agent_loop(thread):
    pass

Why Choose HICA?

Section titled “Why Choose HICA?”

Production-Ready

Designed for reliability, auditability, and extensibility—not just demos.

Unified Tooling

Mix and match local Python and remote MCP tools in a single registry.

Transparent

Every step is logged and persisted for debugging and compliance.

Open Source

Community-driven and vendor-neutral. Licensed under Apache 2.0.

Next Steps

Section titled “Next Steps”

Getting Started

Install HICA and build your first agent in minutes.