@hanfani/core
July 15, 2026 · View on GitHub
Headless engine and types for the Hanfani agent framework.
Pure logic — no I/O, no server, no UI. It defines what a workflow and an agent are and enforces one rule:
The agent proposes, a human approves, the server acts.
defineAgent refuses any side effect that isn't behind a human-approval gate,
and providerConformanceChecks proves any model provider honors that at runtime.
Architecture
@hanfani/core is the shared contract between three layers — definitions and
pure logic live here; execution and rendering live in consuming apps.
defineAgent and defineWorkflow declare what agents and workflows are —
tools, approvals, effects, handoffs, and published input contracts. A provider
calls run() and emits a GATE_OPENED event when an approval tool fires; the
UI renders the proposed artifact and the human approves or rejects. On approve,
the server runs the bound effect; on reject, no side effects run.
providerConformanceChecks certifies that any provider adapter honors this
two-phase contract.
Install
pnpm add @hanfani/core
Quick look
import { defineAgent } from '@hanfani/core'
const reply = defineAgent({
id: 'reply',
name: 'Reply',
provider: 'claude',
instructions: 'Draft a reply for the human to approve.',
tools: ['saveDraft'],
approvals: ['saveDraft'], // saveDraft only fires after a human approves
renders: { saveDraft: 'DraftCard' },
})
Dependencies
Depends on @ag-ui/client
(event/message types) and zod (schemas),
both declared as regular dependencies.
Docs
An auto-generated API reference is available at jsdocs.io. Full guides are coming soon in the Hanfani framework docs.