A Universal JSON Specification for AI Agents
Warning
Draft Specification - Work in Progress
This specification is currently in draft status and under active development. While the v1.0.0 release represents a complete and functional specification, it has not yet been formally adopted by any standards body or reached community consensus.
- The specification may change based on community feedback and implementation experience
- Breaking changes are possible before final standardization
- Early implementers should expect potential revisions
- Contributions, feedback, and discussion are welcomed and encouraged
See CONTRIBUTING.md for how to participate in the specification's development.
JSON Agents defines an open, JSON-native specification for describing AI agents, their capabilities, tools, runtimes, and governance in a single portable manifest called the Portable Agent Manifest (PAM).
It enables frameworks, SDKs, and orchestrators to interoperate seamlessly — sharing agent definitions that are:
- Human-readable: Clear JSON structure with comprehensive documentation
- Machine-validated: Enforced through JSON Schema 2020-12
- Framework-agnostic: Works with LangChain, OpenAI, AutoGen, MCP, and more
- Future-proof: Extensible design with
x-*namespaces and formal extension system
JSON Agents is based entirely on established JSON standards (RFC 8259, ECMA-404, ISO 21778) and includes formal specifications for URI schemes and policy expressions.
| Principle | Description |
|---|---|
| JSON-Native | Derived from RFC 8259, ECMA-404, and ISO 21778. |
| Schema-Validated | Enforced through JSON Schema 2020-12. |
| Profile-Based | Modular profiles for core, exec, gov, and graph. |
| Governance-Aware | Security, policies, and observability included by design. |
| Extensible | extensions and x-* namespaces for safe innovation. |
| Framework-Neutral | Compatible with any agent runtime or framework. |
| Formally Specified | Complete URI scheme (ajson://) and policy expression language definitions. |
- 🎯 7 Standard Capabilities: Summarization, routing, retrieval, QA, classification, extraction, and generation — all with formal schemas
- 🔗 URI Scheme: Formal
ajson://URI scheme with resolution mechanism and registry architecture - 📜 Policy Language: Complete expression language for declarative access control and governance
- 🔄 Framework Mappings: Direct conversion paths for LangChain, OpenAI, AutoGen, MCP, and others
- 🌐 Multi-Agent Graphs: Define orchestration topologies with conditional routing
- 🔒 Security First: Built-in sandboxing, policies, and cryptographic signature support
- 📊 Observability: Structured logging, metrics, and distributed tracing integration
- Main Specification:
json-agents.md— Complete PAM specification (888 lines) - Draft Format:
draft-jsonagents-spec-00.md— IETF-style draft - Canonical Schema:
schema/json-agents.json— JSON Schema 2020-12 validator
Key Sections:
- Section 16: URI Scheme Definition —
ajson://syntax and resolution - Appendix B: Policy Expression Language — Grammar and operators
/
├── README.md # This file
├── json-agents.md # Complete specification (888 lines)
├── draft-jsonagents-spec-00.md # IETF-style draft
├── CHANGELOG.md # Version history
├── CONTRIBUTING.md # Contribution guidelines
├── schema/
│ ├── json-agents.json # Core manifest schema
│ ├── message-envelope.json # Inter-agent message format
│ ├── capabilities/ # 7 capability schemas
│ │ ├── summarization.json
│ │ ├── routing.json
│ │ ├── retrieval.json
│ │ ├── qa.json # Question answering
│ │ ├── classification.json # Classification
│ │ ├── extraction.json # Entity extraction
│ │ └── generation.json # Content generation
│ └── extensions/ # Extension schemas
│ ├── audit.json
│ └── memory.json
├── examples/
│ ├── core.json # Minimal core profile
│ ├── core-exec.json # With runtime
│ ├── core-exec-gov.json # With governance
│ └── core-exec-gov-graph.json # Complete multi-agent
├── registry/
│ ├── capabilities.json # Canonical capability registry
│ ├── tool-types.json # Standard tool types
│ ├── profiles.json # Profile definitions
│ └── extensions.json # Extension registry
├── validators/ # Official validators
│ ├── python/ # Python validator (v1.0.0) ✅
│ │ ├── jsonagents/ # Package source
│ │ ├── tests/ # 47 tests (100% passing)
│ │ └── README.md # Documentation
│ └── README.md # Validator overview
└── docs/
├── index.md # Documentation index
├── implementers-guide.md # Implementation guide
├── mapping-frameworks.md # Framework conversions
└── extensions.md # Extension developmentOfficial validators ensure manifests comply with the specification:
| Language | Status | Version | Test Coverage | Location |
|---|---|---|---|---|
| Python | ✅ Production Ready | v1.0.0 | 47/47 (100%) | validators/python/ |
| JavaScript/TypeScript | 🔜 Coming Soon | - | - | - |
| Go | 🔜 Coming Soon | - | - | - |
Quick validation:
cd validators/python/
pip3 install -r requirements.txt
python3 -m jsonagents.cli validate ../../examples/*.jsonSee validators/README.md for details.
JSON Agents uses a modular profile system for progressive enhancement:
| Profile | Required | Description | Use Case |
|---|---|---|---|
| Core | ✅ Yes | Agent identity, tools, capabilities, and context | All manifests |
| Exec | ❌ No | Runtime metadata, language, entrypoint, resources | Deployable agents |
| Gov | ❌ No | Security, policies, observability, audit trails | Enterprise/regulated |
| Graph | ❌ No | Multi-agent topology and message routing | Orchestration |
Each profile is independently implementable, allowing minimal or full-featured agents.
A minimal agent with all four profiles:
{
"manifest_version": "1.0",
"profiles": ["core", "exec", "gov", "graph"],
"agent": {
"id": "ajson://example.com/agents/router-hub",
"name": "Router Hub",
"version": "1.0.0"
},
"capabilities": [
{ "id": "routing", "description": "Route messages by intent" }
],
"runtime": {
"type": "node",
"entrypoint": "dist/router.js"
},
"security": {
"sandbox": "process"
},
"policies": [
{
"id": "deny-external",
"effect": "deny",
"action": "tool.call",
"where": "tool.endpoint !~ 'internal.corp'"
}
],
"graph": {
"nodes": [
{ "id": "router", "ref": "ajson://example.com/agents/router-hub" },
{ "id": "faq", "ref": "ajson://example.com/agents/faq" }
],
"edges": [
{
"from": "router",
"to": "faq",
"condition": "message.intent == 'faq'"
}
]
}
}See examples/ for complete working examples.
- 🔄 Framework Interoperability: Convert between LangChain, OpenAI, AutoGen, and custom frameworks
- 📦 Agent Registries: Build discoverable catalogs of reusable agents
- 🏗️ Multi-Agent Systems: Orchestrate complex workflows with conditional routing
- 🔐 Enterprise Governance: Enforce security policies and audit trails
- 📊 Agent Marketplaces: Standardized format for distributing and monetizing agents
- 🧪 Testing & Validation: Schema-based validation for CI/CD pipelines
JSON Agents provides bidirectional conversion with major frameworks:
| Framework | Import | Export | Documentation |
|---|---|---|---|
| LangChain | ✅ | ✅ | Mapping Guide |
| OpenAI | ✅ | ✅ | Mapping Guide |
| AutoGen | ✅ | ✅ | Mapping Guide |
| MCP | ✅ | Mapping Guide | |
| Hugging Face | Mapping Guide | ||
| CrewAI | Mapping Guide |
✅ = Fully documented |
| Document | Purpose |
|---|---|
| Specification | Complete normative specification |
| Implementer's Guide | How to parse, validate, and use manifests |
| Framework Mappings | Convert to/from other agent formats |
| Extensions Guide | Create custom extensions with x-* |
| Examples | Working manifest examples |
| Changelog | Version history and roadmap |
Coming Soon:
ajvschema validator- Reference implementations (Node.js, Python)
- Framework converters
- Web-based manifest editor
Manual Validation:
# Install ajv-cli
npm install -g ajv-cli
# Validate manifest
ajv validate -s schema/json-agents.json -d examples/core.jsonRecent Additions (Unreleased):
- ✨ URI Scheme Definition: Formal
ajson://specification with resolution mechanism - 📜 Policy Expression Language: Complete grammar for
whereclauses - 🎯 Complete Capability Suite: All 7 capabilities now have formal schemas
- ✅ qa.json (Question Answering)
- ✅ classification.json (Classification)
- ✅ extraction.json (Entity Extraction)
- ✅ generation.json (Content Generation)
See CHANGELOG.md for details.
- 💬 Discussions: GitHub Discussions (coming soon)
- 🐛 Issues: GitHub Issues
- 📧 Contact: [email protected]
- 📖 Contributing: See CONTRIBUTING.md
v1.0 (Current):
- ✅ Core, Exec, Gov, Graph profiles
- ✅ 7 capability schemas
- ✅ URI scheme specification
- ✅ Policy expression language
- ✅ Framework mapping guide
v1.1 (Planned):
- 🔨 Reference validator implementations
- 🔨 Framework converter tools
- 🔨 Additional capability schemas
- 🔨 Community extensions
- 🔨 Public registry service
Future:
- Real-time profile for streaming agents
- Evaluation profile for testing/benchmarking
- Enhanced policy expression functions
- Formal IETF/W3C standardization path
JSON Agents is released under the Apache 2.0 License.
See LICENSE for details.
We welcome contributions! Whether you're:
- 🐛 Reporting bugs or issues
- 💡 Proposing new features
- 📝 Improving documentation
- 🔧 Building tools and validators
- 🌍 Creating framework integrations
See CONTRIBUTING.md for guidelines.
Code of Conduct: This project follows the Contributor Covenant 2.0.
| Aspect | Status |
|---|---|
| Specification | 🟢 v1.0.0 Complete |
| Schema Coverage | 🟢 7/7 Capabilities (100%) |
| Documentation | 🟢 Comprehensive |
| Tooling | 🟡 In Development |
| Community | 🟡 Growing |
| Standards Track | 🟡 Draft |
JSON Agents is designed to be:
- Simple: Easy to read and write by humans
- Complete: Covers all aspects of agent definition
- Flexible: Modular profiles for different use cases
- Safe: Built-in security and governance
- Interoperable: Works with existing frameworks
- Extensible: Room for innovation without breaking changes
- Standard: Based on established JSON specifications
JSON Agents is built on solid foundations:
- ✅ RFC 8259 — JSON Data Interchange Format
- ✅ RFC 3986 — URI Generic Syntax
- ✅ RFC 2119 — Requirement Levels
- ✅ ECMA-404 — JSON Data Interchange Syntax
- ✅ ISO/IEC 21778:2017 — JSON Standard
- ✅ JSON Schema 2020-12 — Validation
- Model Context Protocol (MCP) — Tool/context protocol
- OpenAI Agents — Agent API format
- LangChain — Agent framework
- AutoGen — Multi-agent framework
- 📄 888 lines of specification
- 🎯 7 capability schemas (100% complete)
- 📋 4 profiles (core, exec, gov, graph)
- 🔧 6 tool types (http, function, plugin, system, mcp, custom)
- 🌐 4 examples covering all profile combinations
- 📚 8 documentation files
JSON Agents draws inspiration from:
- JSON Schema and JSON-LD communities
- OpenAPI and AsyncAPI specifications
- Agent framework developers (LangChain, AutoGen, CrewAI)
- Model Context Protocol contributors
- The broader open-source AI community
Version identifiers follow Semantic Versioning 2.0. The default branch represents the latest stable version of the specification.
© 2025 JSON Agents. All rights reserved.