Autonomous Agent Interchange Format (AAIF)

Status of This Memo

This Internet-Draft is submitted in full conformance with the provisions of BCP 78 and BCP 79.¶

Internet-Drafts are working documents of the Internet Engineering Task Force (IETF). Note that other groups may also distribute working documents as Internet-Drafts. The list of current Internet-Drafts is at https://datatracker.ietf.org/drafts/current/.¶

Internet-Drafts are draft documents valid for a maximum of six months and may be updated, replaced, or obsoleted by other documents at any time. It is inappropriate to use Internet-Drafts as reference material or to cite them other than as "work in progress."¶

This Internet-Draft will expire on 27 December 2026.¶

Copyright Notice

Copyright (c) 2026 IETF Trust and the persons identified as the document authors. All rights reserved.¶

This document is subject to BCP 78 and the IETF Trust's Legal Provisions Relating to IETF Documents (https://trustee.ietf.org/license-info) in effect on the date of publication of this document. Please review these documents carefully, as they describe your rights and restrictions with respect to this document.¶

Table of Contents

1. 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 [RFC5545]. 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.¶

2. Terminology

AAIF document

A JSON (or CBOR, see Section 9) 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 Section 6 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 Section 5.¶

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 Section 7.¶

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.¶

3. Design Principles

AAIF is built on seven design principles:¶

1. Declare, don't bind. Model and tools are preferences; Consumers MAY substitute equivalent alternatives when the declared option is unavailable.¶
2. 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.¶
3. Tool-protocol agnostic. Function, MCP [MCP], HTTP, and OpenAPI tool protocols are supported in a unified tool object.¶
4. Safety first-class. Constraints and compliance fields are normative; Consumers MUST enforce them. Silent constraint stripping is a conformance violation.¶
5. Composable. Context schema references can point at other open standards; orchestration subagent references link to other AAIF definitions by UUID or URI.¶
6. Verifiable. The provenance.signature field allows Consumers to cryptographically verify an agent's origin before execution.¶
7. Observable by default. Telemetry and evaluation blocks are first-class fields, not optional afterthoughts. Observability is opt-out, not opt-in.¶

4. AAIF Document Structure

An AAIF agent definition is a JSON object validated against the AAIF agent schema (JSON Schema draft 2020-12 [JSON-SCHEMA]). The minimum conformant document requires only three fields:¶

{
  "sc_standard": "SC-006",
  "agent": {
    "name": "Example Agent",
    "goal": "Assist users with their enquiries."
  }
}

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:¶

AgentDefinition (root)
  sc_standard     "SC-006"  (required)
  sc_version      string (semver, default "3.4.0")
  agent_id        string (UUID, stable across import/export)
  status          draft | active | deprecated
  tags[]          string[]
  agent
    name / version / description / goal / instructions / skills[]
    required_capabilities[]   (capability negotiation, Section 7)
    model
      provider / preferred / provider_id / base_url
      fallbacks[]             (ordered multi-provider fallback chain)
      routing_strategy        cost | latency | quality | round_robin
      min_context_tokens      (routing guard)
      params / params.extended / response_format
    orchestration
      role      orchestrator | worker | evaluator | router | synthesizer
      subagents[] / handoff[] / pipeline[]
      parallel_execution / max_iterations / consensus
    context[]               (RAG sources: text / file / url / dataset)
    tools[]                 (Section 5.3)
    memory[]                (Section 5.4)
    constraints[]           (hard guardrails, enforced by runtime)
    io                      (input/output schemas, streaming, mode)
    events                  (triggers and lifecycle hooks)
    runtime                 (timeout, retries, concurrency, queue)
    telemetry               (OTEL tracing, metrics, OTLP endpoint)
    evaluation              (LLM-as-judge, metrics, test cases)
    compliance              (safety_level, data_residency, PII, audit)
  provenance
    authored_by / source_platform / created_at / updated_at
    license / sc_refs[] / signature

5. 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:¶

{
  "lang": "jsonpath",
  "expr": "$.task.type",
  "nl": "task type is code_review"
}

Supported languages are:¶

• jsonpath — JSONPath query [RFC9535]; 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.¶

6. 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.¶

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 Section 8). 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.¶

7. 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.¶

8. 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.¶

Content-Type: application/x-aaif-handoff+ndjson

9. Binary Encoding

AAIF documents are canonically JSON [RFC8259]. For bandwidth-constrained transports (embedded runtimes, edge deployments, high-throughput agent mesh), implementations MAY encode AAIF documents as CBOR (Concise Binary Object Representation) [RFC8949]. 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:¶

application/cbor; profile="https://schemacommons.org/SC-006/cbor"

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.¶

10. 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:¶

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).¶

11. 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 [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 [MCP-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 [A2A] 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 [APS] 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 (Section 8) 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 (Section 4.7) intentionally does not define its own span or event semantics. Two real, overlapping conventions already exist: the OpenTelemetry GenAI semantic conventions [OTEL-GENAI] (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 [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.¶

12. 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.¶

13. IANA Considerations

Author's Address