{"id":32902540,"url":"https://github.com/json-agents/standard","last_synced_at":"2025-11-14T18:01:07.650Z","repository":{"id":323439232,"uuid":"1092980340","full_name":"JSON-AGENTS/Standard","owner":"JSON-AGENTS","description":"JSON AGENTS -  A universal JSON-native standard for describing AI agents, their capabilities, tools, runtimes, and governance in a portable, framework-agnostic format. Based on RFC 8259, JSON Schema 2020-12.","archived":false,"fork":false,"pushed_at":"2025-11-10T05:24:43.000Z","size":142,"stargazers_count":3,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-11-10T07:13:14.891Z","etag":null,"topics":["agent-governance","agent-manifest","agent-orchestration","agent-specification","ai-agents","ai-framework","interoperability","json","json-schema","llm","portable-agents","rfc","standards"],"latest_commit_sha":null,"homepage":"","language":null,"has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/JSON-AGENTS.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2025-11-09T17:20:06.000Z","updated_at":"2025-11-10T07:00:35.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/JSON-AGENTS/Standard","commit_stats":null,"previous_names":["json-agents/json-agents-standard"],"tags_count":null,"template":false,"template_full_name":null,"purl":"pkg:github/JSON-AGENTS/Standard","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/JSON-AGENTS%2FStandard","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/JSON-AGENTS%2FStandard/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/JSON-AGENTS%2FStandard/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/JSON-AGENTS%2FStandard/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/JSON-AGENTS","download_url":"https://codeload.github.com/JSON-AGENTS/Standard/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/JSON-AGENTS%2FStandard/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":283690121,"owners_count":26877883,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","status":"online","status_checked_at":"2025-11-10T02:00:06.292Z","response_time":53,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["agent-governance","agent-manifest","agent-orchestration","agent-specification","ai-agents","ai-framework","interoperability","json","json-schema","llm","portable-agents","rfc","standards"],"created_at":"2025-11-10T14:00:56.648Z","updated_at":"2025-11-11T15:01:51.023Z","avatar_url":"https://github.com/JSON-AGENTS.png","language":null,"funding_links":[],"categories":[],"sub_categories":[],"readme":"# JSON Agents\n\n[![Version](https://img.shields.io/badge/version-1.0.0-blue.svg)](./CHANGELOG.md)\n[![License](https://img.shields.io/badge/license-Apache%202.0-green.svg)](./LICENSE)\n[![JSON Schema](https://img.shields.io/badge/JSON%20Schema-2020--12-purple.svg)](https://json-schema.org/draft/2020-12/json-schema-core.html)\n[![Standard](https://img.shields.io/badge/standard-RFC%208259-orange.svg)](https://datatracker.ietf.org/doc/html/rfc8259)\n[![Media Type](https://img.shields.io/badge/media%20type-application%2Fagents%2Bjson-teal.svg)](#)\n[![Status](https://img.shields.io/badge/status-draft-yellow.svg)](./json-agents.md)\n\n\u003e **A Universal JSON Specification for AI Agents**\n\n---\n\n\u003e [!WARNING]\n\u003e **Draft Specification - Work in Progress**\n\u003e \n\u003e 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.\n\u003e \n\u003e - The specification may change based on community feedback and implementation experience\n\u003e - Breaking changes are possible before final standardization\n\u003e - Early implementers should expect potential revisions\n\u003e - Contributions, feedback, and discussion are welcomed and encouraged\n\u003e \n\u003e See [CONTRIBUTING.md](./CONTRIBUTING.md) for how to participate in the specification's development.\n\n---\n\n### 🌐 Overview\n\n**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)**.\n\nIt enables frameworks, SDKs, and orchestrators to **interoperate seamlessly** — sharing agent definitions that are:\n- **Human-readable**: Clear JSON structure with comprehensive documentation\n- **Machine-validated**: Enforced through JSON Schema 2020-12\n- **Framework-agnostic**: Works with LangChain, OpenAI, AutoGen, MCP, and more\n- **Future-proof**: Extensible design with `x-*` namespaces and formal extension system\n\nJSON Agents is based entirely on established JSON standards (RFC 8259, ECMA-404, ISO 21778) and includes formal specifications for URI schemes and policy expressions.\n\n---\n\n### 🧩 Core Principles\n\n| Principle | Description |\n|------------|--------------|\n| **JSON-Native** | Derived from RFC 8259, ECMA-404, and ISO 21778. |\n| **Schema-Validated** | Enforced through JSON Schema 2020-12. |\n| **Profile-Based** | Modular profiles for `core`, `exec`, `gov`, and `graph`. |\n| **Governance-Aware** | Security, policies, and observability included by design. |\n| **Extensible** | `extensions` and `x-*` namespaces for safe innovation. |\n| **Framework-Neutral** | Compatible with any agent runtime or framework. |\n| **Formally Specified** | Complete URI scheme (`ajson://`) and policy expression language definitions. |\n\n---\n\n### ✨ Key Features\n\n- **🎯 7 Standard Capabilities**: Summarization, routing, retrieval, QA, classification, extraction, and generation — all with formal schemas\n- **🔗 URI Scheme**: Formal `ajson://` URI scheme with resolution mechanism and registry architecture\n- **📜 Policy Language**: Complete expression language for declarative access control and governance\n- **🔄 Framework Mappings**: Direct conversion paths for LangChain, OpenAI, AutoGen, MCP, and others\n- **🌐 Multi-Agent Graphs**: Define orchestration topologies with conditional routing\n- **🔒 Security First**: Built-in sandboxing, policies, and cryptographic signature support\n- **📊 Observability**: Structured logging, metrics, and distributed tracing integration\n\n---\n\n### 📘 Specification\n\n- **Main Specification:** [`json-agents.md`](./json-agents.md) — Complete PAM specification (888 lines)\n- **Draft Format:** [`draft-jsonagents-spec-00.md`](./draft-jsonagents-spec-00.md) — IETF-style draft\n- **Canonical Schema:** [`schema/json-agents.json`](./schema/json-agents.json) — JSON Schema 2020-12 validator\n\n**Key Sections:**\n- Section 16: [URI Scheme Definition](./json-agents.md#16-uri-scheme-definition) — `ajson://` syntax and resolution\n- Appendix B: [Policy Expression Language](./json-agents.md#appendix-b-policy-expression-language) — Grammar and operators\n\n---\n\n### 📂 Repository Layout\n\n```bash\n/\n├── README.md                      # This file\n├── json-agents.md                 # Complete specification (888 lines)\n├── draft-jsonagents-spec-00.md    # IETF-style draft\n├── CHANGELOG.md                   # Version history\n├── CONTRIBUTING.md                # Contribution guidelines\n├── schema/\n│   ├── json-agents.json           # Core manifest schema\n│   ├── message-envelope.json      # Inter-agent message format\n│   ├── capabilities/              # 7 capability schemas\n│   │   ├── summarization.json\n│   │   ├── routing.json\n│   │   ├── retrieval.json\n│   │   ├── qa.json                # Question answering\n│   │   ├── classification.json    # Classification\n│   │   ├── extraction.json        # Entity extraction\n│   │   └── generation.json        # Content generation\n│   └── extensions/                # Extension schemas\n│       ├── audit.json\n│       └── memory.json\n├── examples/\n│   ├── core.json                  # Minimal core profile\n│   ├── core-exec.json             # With runtime\n│   ├── core-exec-gov.json         # With governance\n│   └── core-exec-gov-graph.json   # Complete multi-agent\n├── registry/\n│   ├── capabilities.json          # Canonical capability registry\n│   ├── tool-types.json            # Standard tool types\n│   ├── profiles.json              # Profile definitions\n│   └── extensions.json            # Extension registry\n└── docs/\n    ├── index.md                   # Documentation index\n    ├── implementers-guide.md      # Implementation guide\n    ├── mapping-frameworks.md      # Framework conversions\n    └── extensions.md              # Extension development\n````\n\n---\n\n### 🔗 Specification Family\n\nJSON Agents uses a **modular profile system** for progressive enhancement:\n\n| Profile | Required | Description | Use Case |\n|---------|----------|-------------|----------|\n| **Core** | ✅ Yes | Agent identity, tools, capabilities, and context | All manifests |\n| **Exec** | ❌ No | Runtime metadata, language, entrypoint, resources | Deployable agents |\n| **Gov** | ❌ No | Security, policies, observability, audit trails | Enterprise/regulated |\n| **Graph** | ❌ No | Multi-agent topology and message routing | Orchestration |\n\nEach profile is independently implementable, allowing minimal or full-featured agents.\n\n---\n\n### 🧠 Quick Start Example\n\nA minimal agent with all four profiles:\n\n```json\n{\n  \"manifest_version\": \"1.0\",\n  \"profiles\": [\"core\", \"exec\", \"gov\", \"graph\"],\n  \"agent\": {\n    \"id\": \"ajson://example.com/agents/router-hub\",\n    \"name\": \"Router Hub\",\n    \"version\": \"1.0.0\"\n  },\n  \"capabilities\": [\n    { \"id\": \"routing\", \"description\": \"Route messages by intent\" }\n  ],\n  \"runtime\": { \n    \"type\": \"node\", \n    \"entrypoint\": \"dist/router.js\" \n  },\n  \"security\": { \n    \"sandbox\": \"process\" \n  },\n  \"policies\": [\n    {\n      \"id\": \"deny-external\",\n      \"effect\": \"deny\",\n      \"action\": \"tool.call\",\n      \"where\": \"tool.endpoint !~ 'internal.corp'\"\n    }\n  ],\n  \"graph\": {\n    \"nodes\": [\n      { \"id\": \"router\", \"ref\": \"ajson://example.com/agents/router-hub\" },\n      { \"id\": \"faq\", \"ref\": \"ajson://example.com/agents/faq\" }\n    ],\n    \"edges\": [\n      { \n        \"from\": \"router\", \n        \"to\": \"faq\", \n        \"condition\": \"message.intent == 'faq'\" \n      }\n    ]\n  }\n}\n```\n\n**See [`examples/`](./examples/) for complete working examples.**\n\n---\n\n### 🚀 Use Cases\n\n- **🔄 Framework Interoperability**: Convert between LangChain, OpenAI, AutoGen, and custom frameworks\n- **📦 Agent Registries**: Build discoverable catalogs of reusable agents\n- **🏗️ Multi-Agent Systems**: Orchestrate complex workflows with conditional routing\n- **🔐 Enterprise Governance**: Enforce security policies and audit trails\n- **📊 Agent Marketplaces**: Standardized format for distributing and monetizing agents\n- **🧪 Testing \u0026 Validation**: Schema-based validation for CI/CD pipelines\n\n---\n\n### 🛠️ Framework Support\n\nJSON Agents provides bidirectional conversion with major frameworks:\n\n| Framework | Import | Export | Documentation |\n|-----------|--------|--------|---------------|\n| **LangChain** | ✅ | ✅ | [Mapping Guide](./docs/mapping-frameworks.md#langchain) |\n| **OpenAI** | ✅ | ✅ | [Mapping Guide](./docs/mapping-frameworks.md#openai) |\n| **AutoGen** | ✅ | ✅ | [Mapping Guide](./docs/mapping-frameworks.md#autogen) |\n| **MCP** | ✅ | ⚠️ | [Mapping Guide](./docs/mapping-frameworks.md#mcp) |\n| **Hugging Face** | ⚠️ | ⚠️ | [Mapping Guide](./docs/mapping-frameworks.md#hugging-face) |\n| **CrewAI** | ⚠️ | ⚠️ | [Mapping Guide](./docs/mapping-frameworks.md#crewai) |\n\n✅ = Fully documented | ⚠️ = Partial support\n\n---\n\n### 📚 Documentation\n\n| Document | Purpose |\n|----------|---------|\n| [**Specification**](./json-agents.md) | Complete normative specification |\n| [**Implementer's Guide**](./docs/implementers-guide.md) | How to parse, validate, and use manifests |\n| [**Framework Mappings**](./docs/mapping-frameworks.md) | Convert to/from other agent formats |\n| [**Extensions Guide**](./docs/extensions.md) | Create custom extensions with `x-*` |\n| [**Examples**](./examples/) | Working manifest examples |\n| [**Changelog**](./CHANGELOG.md) | Version history and roadmap |\n\n---\n\n### 🔧 Tools \u0026 Validation\n\n**Coming Soon:**\n- `ajv` schema validator\n- Reference implementations (Node.js, Python)\n- Framework converters\n- Web-based manifest editor\n\n**Manual Validation:**\n```bash\n# Install ajv-cli\nnpm install -g ajv-cli\n\n# Validate manifest\najv validate -s schema/json-agents.json -d examples/core.json\n```\n\n---\n\n### 🌟 What's New in v1.0\n\n**Recent Additions** (Unreleased):\n- ✨ **URI Scheme Definition**: Formal `ajson://` specification with resolution mechanism\n- 📜 **Policy Expression Language**: Complete grammar for `where` clauses\n- 🎯 **Complete Capability Suite**: All 7 capabilities now have formal schemas\n  - ✅ qa.json (Question Answering)\n  - ✅ classification.json (Classification)\n  - ✅ extraction.json (Entity Extraction)\n  - ✅ generation.json (Content Generation)\n\nSee [CHANGELOG.md](./CHANGELOG.md) for details.\n\n---\n\n### 🤝 Community \u0026 Support\n\n- **💬 Discussions**: [GitHub Discussions](https://github.com/Agents-Json/Standard/discussions) (coming soon)\n- **🐛 Issues**: [GitHub Issues](https://github.com/Agents-Json/Standard/issues)\n- **📧 Contact**: spec@agentsjson.org\n- **📖 Contributing**: See [CONTRIBUTING.md](./CONTRIBUTING.md)\n\n---\n\n### 🎯 Roadmap\n\n**v1.0 (Current)**:\n- ✅ Core, Exec, Gov, Graph profiles\n- ✅ 7 capability schemas\n- ✅ URI scheme specification\n- ✅ Policy expression language\n- ✅ Framework mapping guide\n\n**v1.1 (Planned)**:\n- 🔨 Reference validator implementations\n- 🔨 Framework converter tools\n- 🔨 Additional capability schemas\n- 🔨 Community extensions\n- 🔨 Public registry service\n\n**Future**:\n- Real-time profile for streaming agents\n- Evaluation profile for testing/benchmarking\n- Enhanced policy expression functions\n- Formal IETF/W3C standardization path\n\n---\n\n### ⚖️ License\n\nJSON Agents is released under the **Apache 2.0 License**.\nSee [`LICENSE`](./LICENSE) for details.\n\n---\n\n### 🧭 Contributing\n\nWe welcome contributions! Whether you're:\n- 🐛 Reporting bugs or issues\n- 💡 Proposing new features\n- 📝 Improving documentation\n- 🔧 Building tools and validators\n- 🌍 Creating framework integrations\n\nSee [`CONTRIBUTING.md`](./CONTRIBUTING.md) for guidelines.\n\n**Code of Conduct**: This project follows the [Contributor Covenant 2.0](./CODE_OF_CONDUCT.md).\n\n---\n\n### 📊 Project Status\n\n| Aspect | Status |\n|--------|--------|\n| **Specification** | 🟢 v1.0.0 Complete |\n| **Schema Coverage** | 🟢 7/7 Capabilities (100%) |\n| **Documentation** | 🟢 Comprehensive |\n| **Tooling** | 🟡 In Development |\n| **Community** | 🟡 Growing |\n| **Standards Track** | 🟡 Draft |\n\n---\n\n### 🏆 Design Goals\n\nJSON Agents is designed to be:\n\n1. **Simple**: Easy to read and write by humans\n2. **Complete**: Covers all aspects of agent definition\n3. **Flexible**: Modular profiles for different use cases\n4. **Safe**: Built-in security and governance\n5. **Interoperable**: Works with existing frameworks\n6. **Extensible**: Room for innovation without breaking changes\n7. **Standard**: Based on established JSON specifications\n\n---\n\n### 🧱 Standards Compliance\n\nJSON Agents is built on solid foundations:\n\n- ✅ [RFC 8259](https://datatracker.ietf.org/doc/html/rfc8259) — JSON Data Interchange Format\n- ✅ [RFC 3986](https://datatracker.ietf.org/doc/html/rfc3986) — URI Generic Syntax\n- ✅ [RFC 2119](https://datatracker.ietf.org/doc/html/rfc2119) — Requirement Levels\n- ✅ [ECMA-404](https://www.ecma-international.org/publications-and-standards/standards/ecma-404/) — JSON Data Interchange Syntax\n- ✅ [ISO/IEC 21778:2017](https://www.iso.org/standard/71616.html) — JSON Standard\n- ✅ [JSON Schema 2020-12](https://json-schema.org/draft/2020-12/json-schema-core.html) — Validation\n\n---\n\n### 🔗 Related Projects\n\n- [Model Context Protocol (MCP)](https://github.com/modelcontextprotocol) — Tool/context protocol\n- [OpenAI Agents](https://platform.openai.com/docs/agents) — Agent API format\n- [LangChain](https://github.com/langchain-ai/langchain) — Agent framework\n- [AutoGen](https://github.com/microsoft/autogen) — Multi-agent framework\n\n---\n\n### 📈 Quick Stats\n\n- 📄 **888 lines** of specification\n- 🎯 **7 capability schemas** (100% complete)\n- 📋 **4 profiles** (core, exec, gov, graph)\n- 🔧 **6 tool types** (http, function, plugin, system, mcp, custom)\n- 🌐 **4 examples** covering all profile combinations\n- 📚 **8 documentation files**\n\n---\n\n### 🙏 Acknowledgments\n\nJSON Agents draws inspiration from:\n- JSON Schema and JSON-LD communities\n- OpenAPI and AsyncAPI specifications\n- Agent framework developers (LangChain, AutoGen, CrewAI)\n- Model Context Protocol contributors\n- The broader open-source AI community\n\n---\n\n### 🧱 Versioning\n\nVersion identifiers follow [Semantic Versioning 2.0](https://semver.org/).\nThe default branch represents the **latest stable version** of the specification.\n\n---\n\n© 2025 JSON Agents. All rights reserved.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjson-agents%2Fstandard","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fjson-agents%2Fstandard","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjson-agents%2Fstandard/lists"}