Portable AI agent definitions. AI agent frameworks each use a proprietary format for goals, model routing, tools, memory, and orchestration topology. AAIF is a vendor-neutral JSON Schema document format that captures all of that in a single file any conforming runtime can execute.
An agent you build in one tool is trapped there. Goals, tools, memory, guardrails, provider routing, and orchestration topology are all expressed differently per vendor — so there's no portability and no shared library of agents.
A single, vendor-neutral agent definition covering the full lifecycle of a production multi-agent system:
{
"agent_id": "...",
"agent": {
"goal": "...",
"model": { "provider": "anthropic", "preferred": "claude-opus-4-5", "fallbacks": [...] },
"orchestration": { "role": "orchestrator", "subagents": [...], "parallel_execution": true },
"context": [...],
"tools": [...],
"memory": [...],
"constraints": [...],
"runtime": { "timeout_seconds": 300 },
"telemetry": { "tracing": true },
"evaluation": { "judge_model": "gpt-4o", "metrics": [...] },
"compliance": { "safety_level": "strict", "data_residency": "EU" }
}
}Aligned with OpenAI/Anthropic/Gemini function-calling, Model Context Protocol (MCP), OpenTelemetry, and W3C PROV.
AAIF is an early-stage draft standard with no external adopters yet. "Run anywhere" is the design goal, not a claim about today — true cross-runtime portability depends on other platforms implementing it, which hasn't happened yet. The concrete near-term value is real and available now:
- a clean, versioned export/import format for your own agent library, so agents aren't trapped in one tool;
- dogfooding on a reference runtime (the first runtime to implement AAIF is listed as the reference in ADOPTERS.md);
- first-adopter credibility if you help shape the spec early.
Two known design trade-offs are documented rather than hidden: routing/handoff conditions can be natural-language hints (non-deterministic — prefer the structured forms in §V), and full Stateful conformance (live migration, streaming handoff) is large — most implementations should target Enterprise first.
| Area | v1 | v2 | v2.1 | v3 |
|---|---|---|---|---|
| LLM routing | Single model | Fallbacks + routing | ← | ← |
| Multi-agent | — | All topologies | ← | ← |
| Tool auth | — | env_var |
vault_ref (5 providers) |
← |
| Capability negotiation | — | — | required_capabilities[] |
← |
| Provider params | Standard fields | Standard fields | params.extended pass-through |
← |
| Agent state | — | — | — | agent-state.schema.json |
| Live migration | — | — | — | 7-step migration protocol |
| Streaming handoff | — | — | — | NDJSON wire format (§S) |
1. Sequential pipeline [A] → [B] → [C] → [D]
2. Parallel swarm [Orchestrator]─┬─[Worker A]─┐
(fan-out / fan-in) ├─[Worker B]─┤─[Synthesizer]
└─[Worker C]─┘
3. Dynamic routing [Router]─when:X──→[Specialist A]
─when:Y──→[Specialist B]
4. Mid-run handoff [Agent A]─condition──→[Agent B]
AAIF supports 16 providers out of the box: openai, anthropic, google, vertex_ai, mistral, cohere, groq, ollama, azure_openai, bedrock, huggingface, together, fireworks, deepseek, xai, openrouter. Anything else — GitHub Copilot, Cline-routed endpoints, self-hosted LiteLLM/vLLM gateways — uses provider: "custom" with provider_id + base_url (no enum churn). Set model.routing_strategy to cost, latency, quality, or round_robin for platform-level optimisation.
- Extend without forking. Open extension points (providers, capabilities, condition languages, vault providers, memory backends, tool protocols) live in community
registries/with IANA-style registration policies. Add an identifier by pull request; no schema version bump. The schema enums are just a recommended subset. See SPECIFICATION §X. - Verify conformance. Self-certify per level and direction against the public test suite and publish a machine-readable report at
/.well-known/aaif-conformance.json. See CONFORMANCE.md. - Prove portability. The reference
aaifpackage converts agents to and from OpenAI Assistants, with one-way exporters for LangGraph / CrewAI / AutoGen. - Cite it.
CITATION.cff+ a Zenodo DOI. - Report issues safely. SECURITY.md defines the threat model and disclosure process.
# validate, convert, import
PYTHONPATH=tools python -m aaif validate examples/invoice-chaser.json
PYTHONPATH=tools python -m aaif convert examples/invoice-chaser.json --target openai_assistant
PYTHONPATH=tools python -m aaif import my-assistant.json --source openai_assistant
python tools/validate.py
# test suites (also run in CI)
python tools/test_conformance.py # tests/conformance/ must-pass + must-reject corpus
python tools/test_registries.py # registries/ ↔ schema-enum consistency
python tools/test_roundtrip.py # OpenAI Assistants round-trip losslessness| Role | Benefit |
|---|---|
| Platform builders | Import/export agents across runtimes (LangGraph ↔ CrewAI ↔ AutoGen) without re-writing |
| Enterprise teams | Enforce compliance (data_residency, PII handling, audit log) declaratively |
| DevOps / MLOps | CI/CD gates using evaluation.test_cases[] and LLM-as-judge scoring |
| Developers | Share and reuse agents from a common library with full context |
| Open-source communities | Build a vendor-neutral ecosystem of production-grade agents |
| File | Description |
|---|---|
| SPECIFICATION.md | Full specification: terminology (RFC 2119), field dictionary, topology, conditions (§V), extension registries (§X), conformance (§Y), references (§Z) |
| WHITEPAPER.md | Publication essay — the case for a portable agent standard and readiness assessment |
| ABSTRACT.md | Structured abstract for registry submission, IETF I-D, and citation |
| CONFORMANCE.md | How to self-certify a platform and publish a conformance report |
| SECURITY.md | Threat model and vulnerability disclosure policy |
| CITATION.cff | Citation metadata (GitHub "Cite this repository" + Zenodo DOI) |
| registries/ | Community extension registries (providers, capabilities, condition langs, vaults, backends, protocols) |
| CHANGELOG.md | Version history and roadmap |
| ADOPTERS.md | Self-service adopter and implementation registry |
| schema/conformance-report.schema.json | JSON Schema — platform conformance self-certification report |
| schema/platform-manifest.schema.json | JSON Schema — platform capability manifest |
| schema/agent.schema.json | JSON Schema (draft 2020-12) — agent definition (sc_version 3.4.0) |
| schema/agent-state.schema.json | JSON Schema (draft 2020-12) — agent state checkpoint (sc_version 3.4.0) |
| context.jsonld | JSON-LD context mapping all AAIF terms to URIs (schema.org, PROV-O, Dublin Core, AAIF vocab) |
| examples/invoice-chaser.json | Worker agent: AR automation with MCP tool, Redis + Postgres memory, EU compliance |
| examples/research-summarizer.json | Worker agent: web research with multi-provider fallbacks, Qdrant vector memory, evaluation |
| examples/orchestrator-pipeline.json | Orchestrator: sequential 4-agent BI pipeline with human-in-the-loop |
| examples/code-review-swarm.json | Orchestrator: parallel 3-reviewer swarm with consensus + synthesizer |
| examples/invoice-chaser-checkpoint.json | Agent State: Invoice Chaser mid-run checkpoint in awaiting_approval status |
| tests/conformance/ | Normative test corpus: must-pass (valid/) and must-reject (invalid/) fixtures |
| tools/ | Reference aaif Python package, validator, and test suites (conformance, registries, round-trip) |
python tools/validate.pyimport json, jsonschema, requests
# 1. Load an AAIF definition
with open("examples/invoice-chaser.json") as f:
agent_def = json.load(f)
# 2. Validate against the schema
schema = json.load(open("schema/agent.schema.json"))
jsonschema.validate(agent_def, schema)
# 3. Extract what your platform needs
agent = agent_def["agent"]
primary_model = f"{agent['model']['provider']}/{agent['model']['preferred']}"
fallback_chain = [(f["provider"], f["model"]) for f in agent["model"].get("fallbacks", [])]
tools = agent.get("tools", [])
constraints = agent.get("constraints", [])
runtime_timeout = agent.get("runtime", {}).get("timeout_seconds", 120)| Level | Requirements |
|---|---|
| Core | Valid schema; name + goal present |
| Tooled | Core + ≥1 tool with parameters_schema |
| Portable | Tooled + constraints[] + resolvable endpoints |
| Multi-agent | Portable + orchestration.role + subagents or handoff |
| Observable | Portable + tracing enabled + ≥1 evaluation metric |
| Enterprise | Observable + compliance declared + audit log + signature |
| Stateful (advanced) | Enterprise + required_capabilities[] declared + state.checkpoint capability + Agent State checkpoints supported |
Pick a target, don't climb to the top. Most of AAIF's value lands at Portable → Enterprise (all expressible in
agent.schema.json). Stateful is a separate advanced tier covering v3 live state, migration, and streaming handoff — adopt it only when live pause/resume or cross-runtime migration is an actual requirement. See SPECIFICATION §M.
| Standard | What it adds |
|---|---|
| ACPM — SC-014 | Capability profiles: what an agent, platform, tool, or model offers — trust, cost, SLA, delegation |
| AREG — SC-013 | Agent registry: how to publish and discover AAIF agents |
Licensed CC BY 4.0 — part of Schema Commons.