JSON Agents

A Universal JSON Specification for AI Agents

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.

• 🎯 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 development

Official validators ensure manifests comply with the specification:

Quick validation:

cd validators/python/
pip3 install -r requirements.txt
python3 -m jsonagents.cli validate ../../examples/*.json

See validators/README.md for details.

JSON Agents uses a modular profile system for progressive enhancement:

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:

✅ = Fully documented | ⚠️ = Partial support

Coming Soon:

• ajv schema 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.json

Recent Additions (Unreleased):

• ✨ URI Scheme Definition: Formal ajson:// specification with resolution mechanism
• 📜 Policy Expression Language: Complete grammar for where clauses
• 🎯 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: spec@agentsjson.org
• 📖 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.

JSON Agents is designed to be:

1. Simple: Easy to read and write by humans
2. Complete: Covers all aspects of agent definition
3. Flexible: Modular profiles for different use cases
4. Safe: Built-in security and governance
5. Interoperable: Works with existing frameworks
6. Extensible: Room for innovation without breaking changes
7. 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.