AHIL — Agent Human Interface Language

Version: 1.0 File extension: .ahil.json MIME type: application/vnd.ahil+json

AHIL is an open JSON-based format for the exchange layer between AI agents and humans. It defines a typed, append-only log where agents surface findings upward and humans issue directives downward — both sides using the same schema, the same file, and the same rules.

AHIL is the coordination protocol used by the H.A.R.L.I.E. Collective and is embedded in every ADPL pipeline file as ahi.log[].

---

Design Goals

Goal	Description
Bidirectional	Agents and humans are both first-class participants. The same schema covers both directions.
Append-only	Nothing can be silently rewritten. Every action is recorded as a new entry, not an edit to an existing one.
Typed	Seven entry types with defined semantics, direction, and permitted status transitions.
Audit trail	Every recommendation acted on, every order issued, every override applied — all traceable from the log.
Schema-enforceable	A JSON Schema is provided. Entries can be validated before writing.
Embeddable	The log array format is identical whether used standalone (exchange.json) or embedded in an ADPL file (ahi.log[]).

---

Concepts

The Exchange Layer

The exchange layer is a shared JSON file that both agents and humans read from and write to. It is the single interface between the two sides — replacing direct calls, webhooks, and side-channel communication with a single structured log.

Agents    →  write observations, recommendations, alerts, acknowledgements
Humans    →  write orders, approvals, overrides
Both      →  read all pending entries addressed to them before acting

Directionality

AHIL uses a simple two-direction model:

↑  UP     — agents write upward to humans (or to other agents)
↓  DOWN   — humans write downward to agents
↔  ANY    — acknowledgements flow in either direction

Append-only Invariant

The log is append-only. Agents must never edit or delete an existing entry. If an order cannot be fulfilled, the agent appends an acknowledgement with "status": "rejected" — it does not modify the original entry.

---

File Structure

A standalone AHIL file (e.g. exchange.json) has this shape:

{
  "schema_version": "1.0",
  "description": "Optional human-readable description of this exchange layer.",
  "entries": [
    { ... },
    { ... }
  ]
}

When embedded in an ADPL file, only the entries array is used:

{
  "ahi": {
    "log": [
      { ... }
    ]
  }
}

---

Entry Schema

Every entry in the log — whether written by an agent or a human — uses the same schema:

{
  "id":      "agent-YYYYMMDD-NNN",
  "type":    "observation | recommendation | alert | order | approval | override | acknowledgement",
  "from":    "<agent-slug | human>",
  "to":      "<agent-slug | human | all>",
  "date":    "YYYY-MM-DD",
  "status":  "pending | noted | acknowledged | acted | rejected",
  "content": "Plain English message. Specific and actionable.",
  "context": { }
}

Fields

Field	Type	Required	Description
id	string	✅	Unique entry identifier. Convention: <from>-<YYYYMMDD>-<NNN> where NNN is a zero-padded sequence within that day for that sender.
type	string	✅	One of the seven entry types (see below).
from	string	✅	Sender identifier. Agent slug (e.g. "scout") or "human".
to	string	✅	Recipient. Agent slug, "human", or "all" for broadcast.
date	string	✅	ISO 8601 date the entry was written, e.g. "2026-03-17".
status	string	✅	Current lifecycle status (see Status Lifecycle below).
content	string	✅	The message body. Plain English. Must be specific enough to act on without additional context.
context	object	—	Optional structured metadata. Free-form key-value pairs relevant to this entry (e.g. priority, trigger_tool, suggested_slug).

---

Entry Types

Type	Direction	Written by	Purpose
observation	↑ up	Any agent	"I noticed this." No action implied. Informational only.
recommendation	↑ up	Any agent	"Based on my findings, I suggest this action." Addressed to a specific agent or human. Expects a response.
alert	↑ up	Any agent	Anomaly or urgent issue requiring immediate attention. Higher priority than a recommendation.
order	↓ down	Human	Directive to an agent. Priority change, focus area, constraint, explicit task assignment.
approval	↓ down	Human or higher-level agent	Confirms a pending recommendation should be acted on. References the original entry via context.ref.
override	↓ down	Human	Cancels or modifies a pending agent action. Takes precedence over any prior approval or recommendation.
acknowledgement	↔ any	Any agent	Records that an entry was received and acted on (or rejected). Always references the original via context.ref.

---

Status Lifecycle

Initial write:
  observation  → noted       (no further state change expected)
  alert        → noted       (may escalate to pending if action required)
  recommendation, order,
  approval, override         → pending

After receipt:
  pending → acknowledged     (recipient confirms receipt, action not yet taken)
  pending → acted            (recipient took the requested action)
  pending → rejected         (recipient cannot fulfill; reason in acknowledgement)

Acknowledgements:
  noted, acted, rejected     (terminal states — no further transitions)

---

Entry Type Reference

observation

A factual finding from an agent. No action is required from the recipient. Used to build a shared understanding of the environment.

{
  "id": "scout-20260317-001",
  "type": "observation",
  "from": "scout",
  "to": "all",
  "date": "2026-03-17",
  "status": "noted",
  "content": "Polars 1.39.2 released 2026-03-17. Adds scan_iceberg() identifier string support — Iceberg tables now scannable by slug without additional config. Trending strongly in the DE community.",
  "context": {
    "tool": "polars",
    "version": "1.39.2",
    "source": "pypi/github"
  }
}

recommendation

An agent's suggestion that another agent or human take a specific action. Must be addressed to a specific recipient (not "all"). Recipient is expected to acknowledge.

{
  "id": "scout-20260317-002",
  "type": "recommendation",
  "from": "scout",
  "to": "project_architect",
  "date": "2026-03-17",
  "status": "pending",
  "content": "Microsoft BitNet b1.58 (35k+ stars, trending +6k/week) enables 100B LLM inference on a single CPU. No case study covers CPU-native LLM inference for DSGVO-constrained DE teams. Recommend case study: Local LLM Inference Pipeline using BitNet + Airflow 3.1 + DuckDB.",
  "context": {
    "trigger_tool": "microsoft-bitnet",
    "suggested_slug": "local-llm-inference-pipeline",
    "suggested_title": "Local LLM Inference Pipeline — BitNet on CPU",
    "priority": "high"
  }
}

alert

Urgent finding requiring immediate attention. Agents may escalate a repeated observation or a quality/freshness failure to an alert when it crosses a defined threshold.

{
  "id": "monitor-20260317-001",
  "type": "alert",
  "from": "data_freshness_monitor",
  "to": "human",
  "date": "2026-03-17",
  "status": "pending",
  "content": "orders_mart table has not been refreshed in 52 hours. Last refresh: 2026-03-15T08:02Z. Daily schedule breach. Downstream dashboards are serving stale data.",
  "context": {
    "table": "orders_mart",
    "last_refreshed": "2026-03-15T08:02Z",
    "hours_stale": 52,
    "severity": "critical"
  }
}

order

A human directive to an agent. May be a new task, a priority change, a constraint, or a correction. The agent must acknowledge receipt and either act or reject with a reason.

{
  "id": "human-20260317-001",
  "type": "order",
  "from": "human",
  "to": "project_architect",
  "date": "2026-03-17",
  "status": "pending",
  "content": "Prioritise the BitNet inference case study over any other pending recommendations this cycle. It must be the first case built in the next run.",
  "context": {
    "priority": "high"
  }
}

approval

Confirmation that a pending recommendation should be acted on. References the original recommendation via context.ref.

{
  "id": "human-20260317-002",
  "type": "approval",
  "from": "human",
  "to": "project_architect",
  "date": "2026-03-17",
  "status": "noted",
  "content": "Approved: build the OpenViking agent context database case study as Case #021.",
  "context": {
    "ref": "scout-20260317-003",
    "priority": "medium"
  }
}

override

Cancels or modifies an in-flight agent action. Takes precedence over any prior approval or recommendation.

{
  "id": "human-20260317-003",
  "type": "override",
  "from": "human",
  "to": "publisher",
  "date": "2026-03-17",
  "status": "pending",
  "content": "Do not push to production today. Hold the release until the AHIL spec page is also included in the commit.",
  "context": {
    "ref": "publisher-20260317-001",
    "reason": "incomplete release"
  }
}

acknowledgement

A response to any entry that required action. Always references the original entry via context.ref. Terminal state.

{
  "id": "project_architect-20260317-001",
  "type": "acknowledgement",
  "from": "project_architect",
  "to": "scout",
  "date": "2026-03-17",
  "status": "acted",
  "content": "Created projects/local-llm-inference-pipeline/index.html as Case #020. Project card added to index.html. ADPL pipeline file to follow from adpl_translator.",
  "context": {
    "ref": "scout-20260317-002",
    "slug": "local-llm-inference-pipeline",
    "case_number": "020"
  }
}

---

Rules for All Participants

1. Read before you write. Always read all pending entries addressed to you (or "all") before starting your task.
2. Append only. Never edit or delete existing entries. Respond by adding new entries.
3. One entry per action. Do not combine multiple recommendations or observations into one entry.
4. Acknowledge when acting. When you act on a pending entry, append an acknowledgement referencing it via context.ref. Do not change the status of the original entry.
5. Reject explicitly. If you cannot fulfill a pending entry, append an acknowledgement with "status": "rejected" and explain why in content.
6. Unique IDs. Format: <from>-<YYYYMMDD>-<NNN>. NNN is a 3-digit sequence starting at 001, resetting per sender per day.
7. Plain English content. The content field must be specific enough for any participant to act on without consulting external context.

---

ID Convention

<sender>-<YYYYMMDD>-<sequence>

Examples:
  scout-20260317-001
  human-20260317-001
  project_architect-20260317-002
  data_freshness_monitor-20260317-001

Sequences are per-sender per-day. Two different senders may both have -001 on the same day.

---

Integration with ADPL

AHIL is embedded in every ADPL file as ahi.log[]. The embedded log captures the coordination history of the pipeline — the alerts that triggered changes, the human approvals that cleared blockers, the agent acknowledgements that confirm state.

{
  "adpl": "1.1",
  "pipeline": { ... },
  "ahi": {
    "log": [
      {
        "id": "setup-agent-20260317-001",
        "type": "observation",
        "from": "de_setup_agent",
        "to": "human",
        "date": "2026-03-17",
        "status": "noted",
        "content": "Pipeline initialised successfully. All 4 services healthy. dbt models built clean. 3 marts populated."
      }
    ]
  }
}

The embedded ahi.log[] uses the same schema as the standalone exchange file. Tools that process ADPL files can extract and append to this log without any format translation.

---

Integration with Pipeline CAD

The Pipeline CAD simulation mode (simulate.js) uses AHIL entries in real time:

• Agent nodes append observation, recommendation, and alert entries as the simulation progresses.
• Human Gate nodes pause the simulation and prompt the operator to write an order or approval entry before flow resumes.
• The accumulated ahi.log[] is exported into the .adpl file on save, providing the initial operating context for deployed agents.

---

Minimal Valid Example

{
  "schema_version": "1.0",
  "description": "Exchange layer for the Hello Pipeline.",
  "entries": [
    {
      "id": "de_setup_agent-20260317-001",
      "type": "observation",
      "from": "de_setup_agent",
      "to": "human",
      "date": "2026-03-17",
      "status": "noted",
      "content": "Pipeline Hello Pipeline initialised. PostgreSQL healthy. dbt orders_pipeline built 3 models clean.",
      "context": {
        "pipeline": "hello-pipeline",
        "services_ok": ["postgresql", "dbt"]
      }
    },
    {
      "id": "human-20260317-001",
      "type": "order",
      "from": "human",
      "to": "data_freshness_monitor",
      "date": "2026-03-17",
      "status": "pending",
      "content": "Run a freshness check now — the orders source may not have loaded today's data yet.",
      "context": {
        "priority": "high"
      }
    },
    {
      "id": "data_freshness_monitor-20260317-001",
      "type": "acknowledgement",
      "from": "data_freshness_monitor",
      "to": "human",
      "date": "2026-03-17",
      "status": "acted",
      "content": "Freshness check complete. orders source: last updated 2026-03-17T06:12Z — fresh. mart: last updated 2026-03-17T07:01Z — fresh.",
      "context": {
        "ref": "human-20260317-001"
      }
    }
  ]
}

---

Versioning

Version	Date	Notes
1.0	2026-03-18	Initial release

---

License

AHIL format specification is released under CC0 1.0 Universal — use freely, no attribution required.