Core Concepts
Understanding the fundamental building blocks of hatiOS — organizations, agents, sessions, traces, policies, and interventions.
Organizations
An Organization is the top-level entity. All agents, policies, users, and billing are scoped to an organization.
Agents
An Agent represents an autonomous AI system registered with hatiOS. Each agent gets a unique API key (hk_live_) for authentication.
| Status | Description |
|---|---|
| Active | Agent is operational and sending requests through the proxy |
| Paused | Agent is in intervention state, awaiting human input |
| Inactive | Agent is registered but not currently sending requests |
Sessions
A Session represents a single execution run of an agent — from initial goal to final output. Sessions contain ordered reasoning traces and may include interventions.
Reasoning Traces
A Trace is a single atomic step within a session. Each is SHA-256 hashed for immutability. Types: thought, tool_call, tool_result, llm_request, llm_response.
Policies
Policies are governance rules evaluated against every proxied request. Static Rules — JSONPath checks in <10ms. Semantic Rules — LLM-powered checks in ~100ms. Actions: block, warn, or require_approval.
Interventions
An Intervention is a human-in-the-loop event. The session enters INTERVENTION_REQUIRED state while a human reviews context and provides natural language guidance.