JSON Agents

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.

---

🌐 Overview

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.

---

🧩 Core Principles

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

---

✨ Key Features

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

---

📘 Specification

• 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

---

📂 Repository Layout

/
├── 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

---

🧪 Validators

Official 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/*.json

See validators/README.md for details.

---

🔗 Specification Family

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.

---

🧠 Quick Start Example

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.

---

🚀 Use Cases

• 🔄 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

---

🛠️ Framework Support

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 | ⚠️ = Partial support

---

📚 Documentation

| Document | Purpose | |----------|---------| | Specification | Complete normative specification | | Implementer's Guide | How to pars