Autonomous Agent Interchange Format (AAIF)

Introduction The multi-agent LLM platform ecosystem, as of mid-2026, comprises more than a dozen actively developed frameworks: LangGraph, CrewAI, AutoGen, Open WebUI, Cline, Semantic Kernel, BeeAI, Haystack, DSPy, Agno, and the native agent APIs of OpenAI, Anthropic, and Google. Each framework has defined its own concept of an agent and its own storage format. An agent authored for LangGraph cannot be imported into CrewAI. A definition written for Open WebUI is unreadable by AutoGen. Every platform has solved the same problem in an incompatible way, and the developer is the primary victim of that incompatibility. This fragmentation has direct operational consequences. Agent definitions encode business logic: the instructions that shape an AI's persona, the constraints that prevent harmful actions, the tools the agent may call and the authentication credentials it uses, and the compliance rules it must follow. When that logic is locked inside a proprietary format, it cannot be audited independently, cannot be migrated without manual recreation, and cannot be shared across team boundaries that use different tooling. An agent definition is becoming a new kind of compliance artefact, with the same importance as a data processing agreement or terms-of-service document. It deserves the same portability. Analogous fragmentation problems have been solved before. Database connectors fragmented until ODBC. Email clients fragmented until SMTP and MIME. Calendar applications fragmented until iCalendar . Container deployments fragmented until the Open Container Initiative image format. In every case, the industry converged on a shared definition format because the cost of incompatibility became high enough that a neutral standard was the rational choice for all parties. The multi-agent LLM market is approaching that inflection point. This document specifies the Autonomous Agent Interchange Format (AAIF), a portable, vendor-neutral definition format for AI agents. AAIF standardises the declaration of an agent — its identity, capabilities, and constraints — not its execution loop, so that a definition created in one runtime can be imported and executed in any other conforming runtime.

Requirements Language The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in BCP 14 when, and only when, they appear in all capitals, as shown here.

Scope AAIF is in scope for: agent name, goal, and system instructions; LLM provider preferences and multi-provider fallback routing; tool catalogue with protocol and authentication declarations; memory backend configuration; multi-agent orchestration topology; runtime policy (timeout, retry, concurrency); telemetry endpoints; evaluation criteria and golden test cases; compliance controls (data residency, PII handling, human-in-the-loop approval, audit logging); and agent provenance including cryptographic signature. AAIF is out of scope for: the agent execution loop itself; billing and metering; provider-specific internal optimisations; and streaming response wire formats between an agent and an end user (as opposed to agent-to-agent state handoff, which is in scope for the Agent State schema described in ).

Terminology

AAIF document: A JSON (or CBOR, see ) instance conforming to one of the three AAIF schemas: agent definition, Agent State, or platform manifest.
Agent definition: The primary AAIF document type: the complete portable declaration of one agent, validated against agent.schema.json.
Producer: Software that emits AAIF documents (an exporter from a native agent framework).
Consumer: Software that imports an AAIF document and executes or enforces it (a runtime).
Conformance level: One of the seven cumulative conformance levels defined in that a Producer or Consumer claims.
Condition: The structured-or-string routing and gating type used in orchestration handoff conditions, subagent selection predicates, event filters, and human-in-the-loop triggers. See .
Capability: A dot-namespaced runtime feature string an agent may declare as required via agent.required_capabilities[] and a platform may advertise in its Platform Manifest. See .
Platform Manifest: A machine-readable AAIF document (platform-manifest.schema.json) published by a runtime that declares its supported capabilities, conformance level, and intake endpoint.

Design Principles AAIF is built on seven design principles:

Declare, don't bind. Model and tools are preferences; Consumers MAY substitute equivalent alternatives when the declared option is unavailable.
Provider-agnostic routing. The fallback chain and routing strategy express intent across any LLM provider without hard-coding one. The consumer implements the routing layer.
Tool-protocol agnostic. Function, MCP , HTTP, and OpenAPI tool protocols are supported in a unified tool object.
Safety first-class. Constraints and compliance fields are normative; Consumers MUST enforce them. Silent constraint stripping is a conformance violation.
Composable. Context schema references can point at other open standards; orchestration subagent references link to other AAIF definitions by UUID or URI.
Verifiable. The provenance.signature field allows Consumers to cryptographically verify an agent's origin before execution.
Observable by default. Telemetry and evaluation blocks are first-class fields, not optional afterthoughts. Observability is opt-out, not opt-in.

AAIF Document Structure An AAIF agent definition is a JSON object validated against the AAIF agent schema (JSON Schema draft 2020-12 ). The minimum conformant document requires only three fields: The full object model is organised as a tree with a root that carries document-level metadata, an agent block containing the operational declaration, and a provenance block:

Root and Identity Fields The sc_standard field MUST be the string "SC-006". This serves as the document type discriminator. The agent_id field is a UUID assigned once at agent creation. It MUST NOT change on import, export, or version bump. Consumers SHOULD use it as the canonical deduplication key. The status field reflects the agent definition's lifecycle: "draft" (under development), "active" (production-ready), or "deprecated" (retained for back-compat only). Consumers MAY refuse to execute "deprecated" agents.

LLM Provider Routing The agent.model block expresses routing intent rather than a hard binding to a specific model. A conforming Consumer MUST implement the following routing algorithm:

Attempt the primary route: model.provider and model.preferred.
If the primary provider is unavailable or rate-limited, walk model.fallbacks[] in declared order. Each fallback entry carries its own provider, model identifier, and an optional cost ceiling (max_cost_usd_per_1k_tokens).
Apply model.routing_strategy when multiple models are equally available: "cost" selects the cheapest model meeting min_context_tokens; "latency" selects the fastest by observed p50; "quality" selects the highest benchmark score by platform-defined ranking; "round_robin" distributes load evenly; "preferred_first" always tries the declared order before optimising.
Never route to a model whose context window is smaller than model.min_context_tokens.

The model.provider field enumerates 16 standard providers: openai, anthropic, google, vertex_ai, mistral, cohere, groq, ollama, azure_openai, bedrock, huggingface, together, fireworks, deepseek, xai, openrouter. For providers not in the enumeration (gateway proxies, self-hosted deployments, or new entrants), authors set model.provider to "custom" and supply model.provider_id (a stable string identifier, e.g. "copilot" or "litellm") and optionally model.base_url (an OpenAI-compatible API base URL). This keeps the standard open-ended without enum churn for each new gateway. The model.params.extended field is an open object that carries provider-specific parameters not covered by standard fields (e.g. extended thinking budget for Anthropic models). The Consumer forwards these verbatim to the provider API and MUST NOT validate their contents.

Orchestration Topology AAIF defines five agent roles and four topology patterns that cover the majority of multi-agent LLM architectures observed in production. The five roles are:

orchestrator — coordinates subagents and aggregates results.
worker — executes a specific task assigned by an orchestrator.
evaluator — scores or judges the output of other agents.
router — examines input and dispatches to appropriate specialists.
synthesizer — merges outputs from parallel workers into a single result.

The four topology patterns are:

Sequential pipeline: Each agent's output is the next agent's input. Declared via orchestration.pipeline[] (an ordered list of subagent aliases). Used when tasks have clear sequential dependency order.
Parallel swarm (fan-out/fan-in): An orchestrator fans out to multiple workers simultaneously; a synthesizer merges results. Enabled by setting orchestration.parallel_execution to true. An optional consensus mechanism (majority_vote, best_of_n, referee, first_success) governs how the synthesizer resolves disagreement.
Dynamic routing: A router agent examines the input and dispatches to the appropriate specialist. Each entry in orchestration.subagents[] carries a "when" Condition (see ) that governs selection.
Mid-run handoff: Any agent can delegate mid-run to another agent using orchestration.handoff[]. The handoff entry declares a Condition, a target agent reference, and flags controlling whether context and memory are passed to the receiving agent.

These patterns compose freely. A pipeline step can itself be a swarm; a swarm worker can trigger a handoff. The orchestration.max_iterations field provides a loop guard (default 10) that the Consumer MUST enforce.

Tool Definitions Each entry in agent.tools[] declares a tool in one of four protocols:

function: An in-process callable. The parameters_schema is forwarded as-is to the model's function-calling API (OpenAI, Anthropic, and Gemini formats are all compatible). No endpoint is required.
mcp: A Model Context Protocol server. The endpoint uses the form mcp://server-name/capability or a full WebSocket/stdio URI. The Consumer connects to the MCP server and exposes its tools to the LLM.
http: A raw REST endpoint. The Consumer constructs a request using parameters_schema as the request body schema.
openapi: An OpenAPI 3.x specification URL or local path. The Consumer parses the spec, exposes all or selected operations as tools, and handles authentication via the spec's securitySchemes combined with the AAIF auth block.

Every tool entry MAY carry a structured auth block. The auth.type field names the authentication mechanism (bearer, api_key, oauth2, aws_sigv4, basic, mtls, or none). Secrets MUST NOT appear inline in the AAIF document. The auth.env_var field names an environment variable whose value the Consumer resolves at runtime. The auth.vault_ref field (introduced in v2.1) provides a structured reference to a secret in an external vault — AWS Secrets Manager, HashiCorp Vault, Azure Key Vault, GCP Secret Manager, or 1Password — identified by provider, path, key, and optional version. When both env_var and vault_ref are declared, vault_ref takes precedence. Additional per-tool fields control cache_ttl_seconds (cache successful responses), timeout_seconds (per-call timeout), and rate_limit (requests_per_minute and tokens_per_minute).

Memory Configuration AAIF distinguishes four memory scopes reflecting fundamentally different retention and privacy requirements:

user — persists across sessions for a single user. MUST NOT be shared across user boundaries.
session — scoped to a single conversation session. MUST NOT outlive the session boundary.
task — scoped to a single agentic task execution.
long_term — persistent storage across users and sessions.

Each memory entry declares a backend from the standard vocabulary: in_memory, redis, postgres, sqlite, pinecone, weaviate, qdrant, chroma, or custom. Vector backends additionally declare an embedding_model, a retrieval_strategy (similarity, keyword, hybrid, or recency), and top_k (number of items to retrieve per query, default 5). A ttl_seconds field controls expiry; zero means never expire.

Runtime Configuration The agent.runtime block declares production safety controls. A Consumer MUST abort execution after runtime.timeout_seconds and return a structured error. A Consumer MUST NOT exceed runtime.concurrency simultaneous instances. The retry policy is controlled by max_retries and retry_backoff (fixed, linear, or exponential; default exponential). The runtime.async_execution flag enables a Consumer to return a job ID immediately and execute in the background. The runtime.queue field names a work queue for async execution.

Telemetry The agent.telemetry block declares OpenTelemetry configuration. A Consumer with telemetry.tracing set to true SHOULD emit the following spans per agent run:

aaif.agent.run (root) — with agent.id, agent.name, agent.version, model.provider, model.name attributes.
aaif.agent.tool_call (child) — with tool.name, tool.protocol, tool.endpoint.
aaif.agent.llm_call (child) — with llm.model, llm.provider, llm.input_tokens, llm.output_tokens.
aaif.agent.memory_read and aaif.agent.memory_write — with memory.scope, memory.backend.
aaif.agent.handoff — with target_agent.id, pass_context.

The telemetry.otlp_endpoint field specifies the OTLP collector endpoint. If omitted, the Consumer falls back to its platform default. W3C Trace Context propagation uses the header named in telemetry.trace_context_header (default "traceparent").

Evaluation The agent.evaluation block enables CI/CD quality gating. The judge_model field names the LLM used to evaluate agent outputs (recommended to be at least as capable as the agent model). The metrics[] array declares name and threshold pairs; standard metric names are: faithfulness, relevance, coherence, toxicity, hallucination_rate, task_completion, latency_ms, cost_usd_per_run, and tool_call_accuracy. The test_cases[] array provides golden test inputs with expected outputs and rubric criteria. A Consumer running CI evaluation SHOULD gate promotion to "status: active" on all threshold conditions being met.

Compliance Controls The agent.compliance block encodes legal and operational requirements that travel with the agent definition and cannot be silently dropped on import.

safety_level: One of: minimal, standard, strict, regulated. Governs Consumer behaviour on unsatisfied capabilities (see ) and constraint violations.
data_residency: One of: global, EU, US, UK, APAC, custom. A Consumer MUST route only to LLM providers with data centres in the declared region.
pii_handling: One of: none, detect, anonymize, encrypt, reject. Applied to memory items and tool outputs by the Consumer.
audit_log: Boolean. When true, the Consumer MUST maintain an append-only, tamper-evident log of all invocations.
human_in_the_loop: Object with enabled, trigger (a Condition), and timeout_seconds. When enabled is true, the Consumer MUST obtain human approval before executing any write tool call. The trigger Condition allows scoping the gate to specific actions.

Condition Expressions Several AAIF fields gate routing or execution: orchestration.subagents[].when, orchestration.handoff[].condition, events.triggers[].filter, and compliance.human_in_the_loop.trigger. Each accepts a Condition value in one of two forms. The structured form (RECOMMENDED) is an object naming an expression language and an expression string: Supported languages are:

jsonpath — JSONPath query ; truthy if the result is non-empty.
jmespath — JMESPath query; truthy if the result is truthy.
cel — Common Expression Language boolean expression.
jsonlogic — JsonLogic rule object evaluated against the payload.
always — constant true (omit expr).
never — constant false (omit expr).

The optional nl field is a human-readable description for logs and UIs. It is advisory; the structured expr is authoritative. The string form is also accepted for authoring convenience and backward compatibility. A bare string is a hint only — different runtimes interpret it differently (or via an LLM) — and MUST NOT be relied upon for portable, reproducible routing. Consumers SHOULD emit a portability warning when routing on a string condition. A Consumer that supports a declared lang MUST evaluate the structured form deterministically and MUST NOT fall back to LLM interpretation of nl. A Consumer that does not support a declared lang MUST treat the condition as unsatisfied and apply the same behaviour as an unsatisfied required_capability per the agent's safety_level.

Conformance Levels AAIF defines seven cumulative conformance levels. Conformance is self-certified against the public test suite (tests/conformance/ in the reference repository). There is no central certifying authority; credibility comes from the claim being machine-checkable against publicly available test fixtures.

Level	Requirements
Core	Validates against agent schema; agent.name and agent.goal present.
Tooled	Core + at least one tool with parameters_schema.
Portable	Tooled + constraints[] non-empty + resolvable tools[].endpoint.
Multi-agent	Portable + orchestration.role declared + at least one subagent reference or handoff rule.
Observable	Portable + telemetry.tracing true + at least one evaluation metric with threshold.
Enterprise	Observable + compliance.safety_level declared + compliance.audit_log true + provenance.signature present.
Stateful	Enterprise + required_capabilities[] includes state.checkpoint + Agent State checkpoints supported.

Conformance is per level and per direction. A Producer at level L exports AAIF documents that validate against the schema and satisfy the level-L predicates. A Consumer at level L imports and honours every construct required at that level, including the normative MUST statements for that level. The Stateful level is deliberately advanced. It introduces Agent State checkpoints, cross-platform migration, and streaming handoff (see ). Consumers SHOULD achieve Enterprise conformance before implementing Stateful. Enterprise conformance is independently meaningful and is not a prerequisite for Stateful. Conformance reports validate against schema/conformance-report.schema.json and are published at the well-known path /.well-known/aaif-conformance.json.

Capability Negotiation The agent.required_capabilities[] field declares what an agent requires from its executing runtime. A Consumer MUST check all declared capabilities before accepting an agent definition. Capabilities use a dot-namespaced string format: category.capability. Standard categories and example identifiers:

tool — tool.function, tool.mcp, tool.http, tool.openapi
memory — memory.vector, memory.redis, memory.postgres, memory.pinecone, memory.qdrant
orchestration — orchestration.parallel, orchestration.handoff, orchestration.pipeline, orchestration.consensus
telemetry — telemetry.otel
compliance — compliance.data_residency, compliance.hitl, compliance.audit_log
auth — auth.vault
io — io.streaming, io.async, io.batch
state — state.checkpoint, state.restore

The Consumer behaviour on an unsatisfied capability depends on the agent's compliance.safety_level:

minimal — log a warning and continue; the capability is silently skipped.
standard — import the agent with a warning; disable the dependent feature.
strict — MUST reject the import with a descriptive error listing unsatisfied capabilities.
regulated — MUST reject the import; the failure MUST be audit-logged.

Consumers SHOULD publish a machine-readable Platform Manifest at the well-known URL path /.well-known/aaif-manifest.json. The manifest advertises the platform's supported capabilities, conformance level, AAIF versions supported, and an intake endpoint (platform.intake_endpoint) for posting agent definitions. Orchestrators and CI/CD systems can fetch this manifest to perform capability negotiation before dispatching an agent.

Agent State and Checkpointing AAIF v3 introduces a companion schema, agent-state.schema.json, for capturing, serialising, and restoring the complete execution state of a running agent. This enables three primary use cases: pause and resume on the same platform, cross-platform live migration, and crash recovery without full conversation replay.

Agent State Document An Agent State document carries the following fields:

state_id — a UUID uniquely identifying this checkpoint.
agent_id — links to the originating agent definition.
run_id — groups all checkpoints for one execution run.
checkpoint_at — UTC timestamp of capture (ISO 8601).
status — one of: running, paused, awaiting_approval, awaiting_tool_result, completed, failed, migrating.
iteration — current agentic loop count; the Consumer MUST enforce max_iterations on restore.
pipeline_position — current_step, completed_steps[], remaining_steps[], current_subagent, parallel_slot.
conversation[] — full message history; truncate from the oldest end on restore if the model context window is smaller.
memory_snapshot[] — all in-scope memory items; vector embeddings are NOT serialised and are re-computed on restore.
pending_tool_calls[] — in-flight or queued tool calls; the Consumer re-issues or marks them timed-out on restore.
subagent_states[] — per-subagent summaries; active subagents export their own Agent State documents for deep migration.
variables — named task-scope key-value pairs.
approval_request — present when status is "awaiting_approval"; carries trigger description and timeout.
error — present when status is "failed"; carries code, message, step, retries_remaining.
provenance — source_platform, migration_token, and a SHA-256 hex checksum of the canonical JSON (excluding the checksum field).

Cross-Platform Migration Protocol A cross-platform migration follows seven steps:

Source platform captures Agent State (status "paused" or "migrating").
Source platform issues a short-lived migration_token (signed, expiry at most 15 minutes).
Agent State document is transferred to the receiving platform out-of-band (API, file, message queue).
Receiving platform verifies the SHA-256 checksum, the migration_token signature, and that agent_id matches a known agent definition.
Receiving platform imports the state: loads memory, restores conversation, resumes at pipeline_position.current_step.
Receiving platform re-issues pending_tool_calls still in-flight or marks them timed-out.
Execution resumes.

Streaming Handoff Wire Format For uninterrupted mid-generation migration, AAIF v3 defines a streaming handoff wire format: Each line is a newline-delimited JSON object with a "type" discriminator. Message types are: handoff_init, context_chunk, memory_item, pipeline_state, pending_tool, subagent_ref, handoff_complete, and handoff_error. The stream MUST be transmitted over TLS (HTTPS or WSS); plaintext streaming handoffs are non-conformant. The receiving Consumer MUST verify the migration_token in the handoff_init message before processing subsequent messages. If a handoff_error message is received, the Consumer MUST discard all accumulated state and MUST NOT resume execution. The SHA-256 checksum in handoff_complete MUST be verified against the reconstructed Agent State before execution resumes.

Binary Encoding AAIF documents are canonically JSON . For bandwidth-constrained transports (embedded runtimes, edge deployments, high-throughput agent mesh), implementations MAY encode AAIF documents as CBOR (Concise Binary Object Representation) . The logical structure, field names, enum values, and all constraints of the JSON schemas apply without modification to CBOR-encoded documents. The media type for CBOR-encoded AAIF documents is: Implementations MUST NOT use integer keys as a compression scheme; field names remain UTF-8 text strings so JSON round-trips are lossless. Any Consumer claiming AAIF conformance at Portable level or above that accepts CBOR-encoded definitions MUST also accept the equivalent JSON encoding and produce identical behaviour.

Extension Registries AAIF has several open extension points where new values arise regularly: LLM providers, runtime capabilities, condition languages, vault providers, memory backends, and tool protocols. Rather than requiring a schema version change for each new value, AAIF maintains community registries modelled on IANA's expert-review and specification-required registration policies. Each registry is a machine-readable JSON file validated against a registry meta-schema. The schema enum for each extension point is a convenience subset of the registry; registered values with status "standard" are conformant even if not yet reflected in the schema enum. Values in neither the enum nor the registry MUST use the documented escape hatch (model.provider "custom" with provider_id, or x- extension keys at the document root) rather than inventing unregistered bare enum values. The six registries, their extension points, and registration policies are:

Registry	Extension point	Policy
providers.json	model.provider	Specification Required
capabilities.json	required_capabilities[]	Expert Review
condition-languages.json	Condition lang	Specification Required
vault-providers.json	auth.vault_ref.provider	Specification Required
memory-backends.json	memory[].backend	Specification Required
tool-protocols.json	tools[].protocol	Standards Action

Registration policies follow IANA conventions: First Come First Served (unique identifier and one-line description), Specification Required (stable public specification or documentation URL), Expert Review (Editor sign-off confirming orthogonality and scope), and Standards Action (normative schema change in a new MINOR version).

Relationship to Prior Art Before drafting this section, the editors searched specifically for an existing standard defining a portable, vendor-neutral agent definition document — the thing AAIF itself is. No such standard was found. The frameworks and protocols discussed below each address an adjacent problem, but none of them defines the complete, importable agent record that AAIF defines. That absence is stated plainly here, rather than overstated or replaced with invented modesty about non-existent competitors.

Model Context Protocol (MCP): MCP standardises how an agent invokes external tools — the wire protocol for tool calls. It does not specify what an agent is, how it routes to an LLM, how it manages memory, or how it orchestrates subagents. AAIF explicitly incorporates MCP as one of its four supported tool protocols. The two specifications are complementary: MCP is the tool cable; AAIF is the agent blueprint. Separately, the MCP project's own published roadmap (dated 2026-03-05) lists "audit trails and observability" as an acknowledged, currently unsolved Enterprise Readiness gap. That is honest evidence that the agent ecosystem has more than one unsolved fragmentation problem; it is evidence of fragmentation generally, not specifically of the portable-agent-definition gap that AAIF addresses, and is cited here only for the former.
A2A Agent Card: The A2A Agent Card is a minimal discovery document advertising an agent's identity, capability tags, and endpoint URL. It is deliberately thin by design. An AAIF definition carries a superset of Agent Card information and can generate a conformant Agent Card. A2A addresses agent-to-agent runtime messaging; AAIF addresses portable agent definition.
OpenAI Assistants API: The Assistants API is expressive within the OpenAI platform but is bound to a specific vendor's runtime and API surface. AAIF can express the same concepts portably across providers. A bidirectional reference converter between OpenAI Assistants format and AAIF is provided in the tooling repository.
Agent Persistent State Profile (APS): draft-gaikwad-aps-profile-00 is an IETF individual draft (expired June 2026, not adopted by any working group) specifying a storage service class — an "AgentPersistentState" usage class with a versioned "PersistentStateLineOfService" schema, bound non-normatively to the SNIA Swordfish/Redfish storage-management standards, covering crash consistency, cryptographic erasure tied to identity, vector-index workloads, and Kubernetes/CSI integration. APS operates at the storage-infrastructure layer: it describes how a storage backend advertises itself as suitable for hosting agent state. AAIF's Agent State schema () operates at the document layer: it describes the portable application-level record — conversation history, memory snapshot, pipeline position, pending tool calls, subagent states — captured from a running agent for pause, resume, or migration between runtimes. The two are complementary, not competing: an AAIF Agent State document is the kind of payload that could be persisted on an APS-class volume. AAIF takes no position on, and has no dependency on, the storage layer beneath a checkpoint.
OpenTelemetry GenAI Semantic Conventions and OpenInference: AAIF's telemetry block () intentionally does not define its own span or event semantics. Two real, overlapping conventions already exist: the OpenTelemetry GenAI semantic conventions (gen_ai.* span attributes and an invoke_agent to chat/execute_tool span tree; experimental as of March 2026 but already emitted or instrumented by LangChain, CrewAI, AutoGen, and AG2, and consumed natively by Datadog, Honeycomb, and New Relic), and OpenInference (Arize AI's OTel-based convention with ten span kinds: LLM, EMBEDDING, RETRIEVER, RERANKER, TOOL, CHAIN, AGENT, GUARDRAIL, EVALUATOR, PROMPT). AAIF defers span-attribute semantics to whichever of these the executing runtime already speaks, rather than standardising a third, competing vocabulary. Agent observability and audit-event vocabularies more broadly are out of scope for this document; see the external prior-art note referenced from the Schema Commons repository for that adjacent discussion.

Security Considerations Consumers MUST treat imported tools[].endpoint values as untrusted input and apply capability gating before activating any tool. An AAIF document from an unknown source could declare a tool endpoint pointing to an attacker-controlled server. Secrets MUST NOT appear inline in AAIF documents. The auth.env_var and auth.vault_ref fields name where the Consumer resolves the secret; they carry a reference, not the credential itself. Tools that carry inline credential values in any field violate this specification and MUST be rejected. The constraints[] array MUST be enforced by the Consumer. A Consumer that silently drops a constraint is in violation of this specification and may permit harmful agent behaviour. Consumers MUST be alert to prompt injection in context[type=url] values fetched at runtime. Content retrieved from declared URLs SHOULD be sanitised or sandboxed before injection into the agent's context window. The compliance.data_residency field MUST be respected. Routing an agent to a provider whose data centres are outside the declared region violates the compliance contract and may have legal consequences. Agent State documents contain conversation history and memory contents, which may include personally identifiable information (PII). The same pii_handling policy declared in the agent definition MUST be applied to Agent State documents at rest and in transit. Agent State documents MUST be transmitted over an encrypted channel. The migration_token in Agent State documents and streaming handoffs MUST be a signed, short-lived token with an expiry of at most 15 minutes. The receiving Consumer MUST verify the token signature before accepting the state. The SHA-256 checksum MUST be verified before restoring state; a mismatch indicates tampering or corruption and the import MUST be rejected. The provenance.signature field carries a Base64-encoded Ed25519 signature over the canonical JSON of the agent definition. Consumers receiving agents from untrusted or third-party sources SHOULD verify this signature before execution. The stack_trace field in Agent State error blocks SHOULD be stripped before exporting a checkpoint to an external platform to avoid disclosing implementation details.

IANA Considerations

Media Type Registration This document requests registration of the following media type with IANA.

Type name: application
Subtype name: x-aaif-handoff+ndjson
Required parameters: None.
Optional parameters: None.
Encoding considerations: UTF-8 newline-delimited JSON (NDJSON); each line is a JSON object.
Security considerations: See of this document. The stream MUST be transmitted over TLS.
Interoperability considerations: Recipients MUST verify the migration_token and SHA-256 checksum before processing.
Published specification: This document.
Applications that use this media type: AAIF-conforming runtimes performing live agent state handoff during cross-platform migration of running AI agents.
Fragment identifier considerations: None.
Restrictions on usage: None.
Author: Bob van Bussel, bob@observalytics.com
Change controller: Observalytics SL (https://github.com/Observalytics-SL)

Future Registry Considerations AAIF currently maintains six community extension registries (providers, capabilities, condition languages, vault providers, memory backends, and tool protocols) as described in . These registries are currently operated by the Schema Commons project. A future revision of this document or an accompanying document may request that IANA operate one or more of these registries under the appropriate IANA registration policies (Specification Required or Expert Review as indicated per registry).