The language between
agents and humans.
AHIL is an open JSON format for the exchange layer between AI agents and humans. Agents surface findings, alerts, and recommendations upward ↑. Humans issue orders, approvals, and overrides downward ↓. One schema, one file, both directions — append-only so nothing can ever be silently rewritten.
Agents and humans have no shared language
As AI agents take on more autonomous roles in data pipelines, the coordination problem grows: agents produce findings that humans never see in a timely way; humans issue instructions with no guaranteed path to the agent; and the chain of decisions — who recommended what, who approved it, who acted — is scattered across logs, Slack threads, and comments.
One typed, append-only log. Both sides.
AHIL defines a single JSON exchange file where agents and humans both read and write using the same entry schema. Seven typed entry types cover every coordination pattern — from a routine agent observation to a human override that cancels an in-flight action.
from and type fields differ.exchange.json) or embedded in an ADPL pipeline file (ahi.log[]). No translation needed.Directionality and flow
The exchange layer sits between agents and humans. Agents write up. Humans write down. Both sides read the full log before acting. The log is the only interface — no direct calls, no side channels.
alert · acknowledgement
shared · auditable
override
Seven types, two directions
Every AHIL entry has a type that determines its direction, who may write it, and what status transitions are valid. The seven types together cover every coordination pattern between agents and humans.
noted.context.ref. Terminal state — no further transitions.From pending to terminal
Every entry begins in an initial state and transitions forward. Transitions happen by appending new acknowledgement entries — the original entry's status is never edited.
File structure and entry shape
// exchange.json — standalone AHIL exchange file { "schema_version": "1.0", "description": "Exchange layer for the Hello Pipeline.", "entries": [ { // ↑ Agent writes upward "id": "scout-20260317-001", "type": "recommendation", "from": "scout", "to": "project_architect", "date": "2026-03-17", "status": "pending", "content": "BitNet trending — recommend case study.", "context": { "priority": "high", "suggested_slug": "local-llm-inference-pipeline" } }, { // ↓ Human writes downward "id": "human-20260317-001", "type": "approval", "from": "human", "to": "project_architect", "date": "2026-03-17", "status": "noted", "content": "Approved. Build BitNet case study this cycle.", "context": { "ref": "scout-20260317-001" } }, { // ↔ Agent acknowledges "id": "project_architect-20260317-001", "type": "acknowledgement", "from": "project_architect", "to": "scout", "date": "2026-03-17", "status": "acted", "content": "Created Case #020 — Local LLM Inference Pipeline.", "context": { "ref": "scout-20260317-001", "slug": "local-llm-inference-pipeline" } } ] }
Where AHIL is used
One format, three contexts
exchange.json as its shared coordination layer. Seven agents and humans all read and write here. The exchange log is the only interface between agents — no direct calls.ahi.log[]. The pipeline's operational history — setup confirmations, quality alerts, human approvals — travels with the pipeline file. Import into Pipeline CAD to see the full log.order or approval entry before flow resumes.Three ways to use AHIL
exchange.json file in your project. Copy the minimal valid example from the spec README. Point your agents to read pending entries addressed to them at startup and append acknowledgements when done.ajv, VS Code, or any JSON Schema Draft-07 validator. Every entry type, direction, and status transition is covered.Full reference and examples
The AHIL specification is published as an open repo. It includes the full README with entry type reference, status lifecycle rules, all seven annotated examples, and the JSON Schema for validation.
id naming pattern.schema/v1.0.json and use it with ajv, VS Code JSON validation, or any Draft-07 compatible validator.See AHIL in action
A walkthrough of the Agent Human Interface Language — how the exchange layer works, the entry types, and how H.A.R.L.I.E. uses it to coordinate her agent collective.