AIR Schema Reference

The Agent Intelligence Record (AIR) defines eight portable schemas organized into three layers. This document describes every field in every schema.

Bundle manifest — air.json

Present in every AIR bundle. Ties all components together and establishes provenance.

Field	Type	Required	Description
air_version	string	yes	AIR spec version used at export. Currently "1.1"
spec	URI	yes	Canonical spec URL: https://agentpk.io/specs/air/v1.1
agent_id	string	no	Agent identifier from the issuing platform
certificate_id	string|null	no	Cryptographic certificate ID (e.g. Nomotic nmc-...)
issuing_platform	string	yes	Platform that produced this bundle (e.g. "nomotic", "agentpk")
issuing_platform_version	string	yes	Version of the issuing platform
export_timestamp	ISO 8601	yes	When this bundle was exported
components	array	yes	Names of components present. See valid values below
component_hashes	object	no	SHA-256 hash of each component file (sha256:<hex>)
export_sig	string|null	no	Ed25519 signature over canonical air.json with export_sig set to null
redaction_profile	string	no	minimal, standard, or strict. Default: standard
intelligence_license	object	no	License terms governing downstream use
layer_summary	object	no	Which of the three layers are present

Valid component names: audit · fingerprint · trust · org_context · compliance_state · domain_model · interaction_patterns · knowledge_state

intelligence_license fields:

Field	Type	Description
default	string	License applying to all components not individually listed
components	object	Per-component license overrides (component name → license string)
permitted_uses	array	Allowed uses: e.g. ["rehydration", "governance"]
prohibited_uses	array	Prohibited uses: e.g. ["fine-tuning", "benchmarking", "re-export"]

---

Layer 1 — Governance Record

fingerprint.json — Behavioral Fingerprint

Statistical description of the agent’s action patterns built from governance history.

Field	Type	Required	Description
air_version	string	yes
agent_id	string	yes
total_observations	integer	yes	Total governance evaluations that built this fingerprint
confidence	float 0–1	yes	Fingerprint confidence. Increases with observation count
action_distribution	object	no	Proportion of each action type. Values sum to 1.0
target_distribution	object	no	Proportion of accesses to each target. Values sum to 1.0
temporal_profile	object	no	Time-of-day and frequency patterns
outcome_distribution	object	no	Distribution of ALLOW / DENY / ESCALATE verdicts
drift_baseline_jsd	float 0–1	no	Jensen-Shannon Divergence baseline at export time

temporal_profile fields:

Field	Type	Description
peak_hours	array[int]	Hours of day (0–23) with highest activity
burst_threshold	float	Actions per minute that constitute a burst
avg_actions_per_hour	float	Average action rate

Rehydration note: Receiving platforms MUST apply a confidence decay factor of 0.85 to imported confidence: imported_confidence = original_confidence × 0.85.

---

trust.json — Trust Trajectory

Time-series of trust score changes with labeled events.

Field	Type	Required	Description
air_version	string	yes
current_score	float 0–1	yes	Trust score at export time
trajectory	array	yes	Ordered list of trust events
trajectory_label	string	no	Summary label for the overall trajectory shape

Trajectory event fields:

Field	Type	Required	Description
ts	ISO 8601	yes	When this event occurred
score	float 0–1	yes	Trust score after this event
event	string	yes	Event type. See valid values below
note	string	no	Human-readable explanation

Valid event types: initial · drift_detected · drift_resolved · elevated_trust · trust_reduced · air_import · policy_change · manual_adjustment

Valid trajectory labels: rising · declining · stable · volatile · recovered_stable

Rehydration note: The imported current_score becomes the starting score on the receiving platform, capped at that platform’s trust ceiling for new agents until native observations accumulate.

---

audit.json — Audit Trail Manifest

Manifest for the audit.jsonl hash-chained transaction history.

Field	Type	Required	Description
air_version	string	yes
record_count	integer	yes	Number of records in the audit file
chain_tail	sha256	yes	Hash of the final record. MUST be present in every export
audit_format	string	no	jsonl, jsonl.gz, zstd, or parquet. Default: jsonl
chain_head	sha256	no	Hash of the first record
export_sig	string|null	no	Signature over the audit trail
redaction_profile	string	no	minimal, standard, or strict
date_range	object	no	from and to ISO 8601 timestamps
summary_only	boolean	no	If true, audit.jsonl contains statistical buckets. chain_tail must still be present

Audit record format (each line in audit.jsonl):

Field	Type	Description
seq	integer	Sequence number
ts	ISO 8601	Record timestamp
action	string	Action that was evaluated
verdict	string	ALLOW, DENY, or ESCALATE
hash	sha256	Hash of this record with hash set to null
prev_hash	sha256	Hash of previous record. First record: "genesis"

Redaction profiles:

Profile	Retains	Removes
minimal	All structured fields	Free-text justification fields
standard	Statistical shape, verdicts, timestamps	PII identifiers, entity references
strict	Verdict, timestamp, hash only	All content fields

---

Layer 2 — Institutional Context

org_context.json — Organizational Context

Vocabulary, values, and escalation rules the organization defined.

Field	Type	Required	Description
air_version	string	yes
org_id	string	yes	Organization identifier
values	array[string]	no	Organizational values guiding agent behavior
vocabulary	object	no	Preferred terms and prohibited terms
domain_anchors	array[string]	no	Domain context strings (e.g. regulatory frameworks, industry terms)
escalation_patterns	array	no	Defined escalation rules

vocabulary fields:

Field	Type	Description
preferred	object	Term substitutions: {"client": "member"}
prohibited	array[string]	Terms the agent must not use

Escalation pattern fields:

Field	Type	Required	Description
trigger	string	yes	Condition that triggers escalation
action	string	yes	What to do when triggered
priority	string	no	low, medium, high, or critical

---

compliance_state.json — Compliance State

Regulatory posture and active compliance frameworks at export time.

Field	Type	Required	Description
air_version	string	yes
snapshot_timestamp	ISO 8601	yes	When this snapshot was taken
active_frameworks	array	no	Regulatory frameworks in effect
policy_snapshots	array	no	Governance policy versions active at export
data_classifications	array	no	Data classes the agent was authorized to access
audit_retention_policy	object	no	Retention and legal hold settings

Active framework fields:

Field	Type	Required	Description
name	string	yes	Framework name: HIPAA, PCI-DSS, SOC2, GDPR, CCPA, ISO-27001, NIST-AI-RMF
version	string	no	Framework version
status	string	yes	active, pending, suspended, or historical
effective_from	ISO 8601	no	When this framework became active
policy_version	string	no	Internal policy version implementing this framework
notes	string	no

Data classification fields:

Field	Type	Description
classification	string	PHI, PII, PCI, confidential, or public
access_level	string	read, write, or admin
authorized_from	ISO 8601	When access was granted

---

Layer 3 — Operational Intelligence

domain_model.json — Domain Model

The agent’s learned understanding of its domain — not configured, but discovered through operational experience.

Field	Type	Required	Description
air_version	string	yes
snapshot_timestamp	ISO 8601	yes
domain	string	yes	Primary domain: e.g. "fraud-detection", "healthcare-prior-auth"
entities	array	no	Key entities the agent learned to recognize
learned_thresholds	array	no	Parameters calibrated through experience beyond defaults
edge_cases	array	no	Unusual scenarios encountered and learned resolutions
terminology	object	no	Domain terms learned in context

Entity fields:

Field	Type	Required	Description
id	string	yes
name	string	yes
description	string	no
confidence	float 0–1	yes	How confident the agent is in this entity model
observation_count	integer	no	How many times this entity was encountered
attributes	array[string]	no	Known attributes of this entity

Learned threshold fields:

Field	Type	Required	Description
parameter	string	yes	Parameter name
learned_value	any	yes	Value calibrated through experience
default_value	any	yes	Original configured value
confidence	float 0–1	yes
sample_size	integer	no	Observations used for calibration
rationale	string	no	Why this calibration was learned

Edge case fields:

Field	Type	Required	Description
id	string	yes
description	string	yes	What the edge case is
resolution	string	yes	How the agent learned to handle it
frequency	integer	no	Times this edge case was encountered
first_observed	ISO 8601	no
confidence	float 0–1	yes

---

interaction_patterns.json — Interaction Patterns

Learned patterns about the humans and systems this agent works with.

Field	Type	Required	Description
air_version	string	yes
snapshot_timestamp	ISO 8601	yes
total_interactions	integer	no	Total interactions this pattern set was built from
request_patterns	array	no	Common request types and learned handling
ambiguity_resolutions	array	no	How the agent learned to resolve ambiguous situations
communication_preferences	object	no	Learned style preferences for this context
system_integrations	array	no	External systems and learned integration behavior

Request pattern fields:

Field	Type	Required	Description
pattern_id	string	yes
description	string	yes
frequency	integer	yes	How often this pattern occurs
typical_resolution	string	no	How the agent typically handles it
avg_confidence	float 0–1	no	Average confidence on this pattern
escalation_rate	float 0–1	no	How often this pattern leads to escalation

Ambiguity resolution fields:

Field	Type	Required	Description
scenario	string	yes	Description of the ambiguous situation
learned_resolution	string	yes	What the agent learned to do
confidence	float 0–1	yes
sample_count	integer	no
override_rate	float 0–1	no	How often humans overrode this resolution

Communication preference fields:

Field	Type	Description
verbosity	string	minimal, standard, or detailed
escalation_preference	string	conservative, balanced, or aggressive
confirmation_threshold	float 0–1	Confidence below which the agent asks for confirmation

---

knowledge_state.json — Knowledge State

Distilled insights from operational history with explicit provenance.

Field	Type	Required	Description
air_version	string	yes
snapshot_timestamp	ISO 8601	yes
distillation_method	string	yes	nomotic-v1, manual, or external
summary_count	integer	no	Total number of insights
key_insights	array	no	Individual insights
embeddings	object	no	Vector embedding metadata if present
cid_root	string|null	no	IPFS CID for externally stored embeddings

Insight fields:

Field	Type	Required	Description
id	string	yes	Unique insight identifier
domain	string	yes	Domain this insight applies to
content	string	yes	The insight
confidence	float 0–1	yes	How confident the distillation system is
insight_source	string	yes	governance_derived, experience_derived, human_annotated, or hybrid
source_record_count	integer	no	Number of records this insight was derived from
created	ISO 8601	no	When this insight was first captured
last_validated	ISO 8601	no	When this insight was last confirmed

insight_source values:

Value	Meaning
governance_derived	Derived from governance verdicts, scores, and behavioral patterns
experience_derived	Derived from operational experience not captured in governance data
human_annotated	Explicitly added or validated by a human
hybrid	Derived from a combination of the above

Receiving platforms SHOULD weight governance_derived insights as more verifiable than experience_derived insights, since the former have an auditable evidence chain.

Embeddings fields:

Field	Type	Description
provider	string	Embedding provider: openai, anthropic, cohere, local, none
model	string	Model identifier
dimension	integer	Vector dimension
version	string	Model version
entry_count	integer	Number of embedded entries
storage	string	inline or cid

---

Conformant Consumer Requirements

A platform importing an AIR bundle MUST:

1. Verify all component hashes before import. Reject if any mismatch.
2. Verify the export signature if present. Reject unless operator explicitly overrides with --trust-unsigned.
3. Apply the redaction profile. Never re-introduce data the redaction profile removed.
4. Honor intelligence_license. Bound by license terms for all downstream use including fine-tuning, benchmarking, and re-export.
5. Not backfill. Do not make inferences about time periods before date_range.from.
6. Record active frameworks from compliance_state before applying governance to the imported agent.
7. Tag insight_source — weight governance_derived insights as more verifiable than experience_derived when seeding the agent’s knowledge base.
8. Degrade gracefully using the fallback hierarchy:
   1. Full rehydration — all components present and verified
   2. Governance warm-start — Layer 1 only
   3. Context cold-start — Layer 2 only
   4. Bare cold-start — no components verified; log warning

---

Versioning

Minor versions (1.0 → 1.1) add optional fields and new components. Existing consumers must ignore unrecognized fields.

Major versions (1.x → 2.0) may introduce breaking changes and require explicit migration.

The air_version field in every component file records the spec version used at export time.