Introducing AI Registry for Agents spec – A Standard for AI Agent Artifacts

Today, we’re releasing AI Registry for Agents (ARA), an open specification that improves collaboration in agentic AI development. Similar to how package.json standardized Node.js packages, ARA defines a common format for AI development artifacts that work across tools, registries, and teams.

You’ve built the perfect agent configuration. Your prompts are tuned, your tools are integrated, and it works beautifully. Now your teammate asks, “Can I use that?” You send them a zip file. They’re using a different AI assistant. It doesn’t work. You spend an hour explaining how to adapt it. Sound familiar?

We lived this firsthand. As Technical Account Managers helping customers on their cloud journeys, Martin-Zack and Zoran started building AI agents to automate repetitive tasks. When they compared notes with peers Jerome and Mladen, they discovered everyone was solving the same problem independently—crafting agent configurations, MCP servers, and prompt templates with no straightforward way to share them. Artifacts lived in Slack threads, personal repos, and zip files with cryptic READMEs.
To address this, we built a standardized format and internal registry that lets teams publish and discover AI Agent artifacts. Within months, over 3,000 Amazon builders were using it—sharing configurations across teams and tools without the adaptation headaches. What used to take hours now took seconds.

That experience taught us something: the AI development ecosystem doesn’t have a tooling problem—it has a distribution problem. Every tool uses its own format for packages. Agent configurations that work in one assistant won’t work in another. MCP servers get published to npm, PyPI, GitHub MCP Registry or git repositories with no standardized way to discover them. Prompts live in documentation sites, Slack messages, and personal notes. Teams waste hours recreating artifacts that already exist because there’s no standard way to share them.

This fragmentation isn’t just inconvenient—it’s holding back the entire AI development community. We can’t build on each other’s work when every tool speaks a different language.

What is ARA?

ARA is an open specification, not an implementation, that separates concerns: the package format describes artifacts, while the registry API defines how they’re distributed.
The specification is built on four core tenets:

Community-Driven Discovery Over Centralized Curation: Usage patterns surface valuable artifacts, not editorial gatekeeping
Platform Agnostic Over Tool-Specific: Works across AI tools (Kiro, Strands, Claude Code and others Agentic AI frameworks)
Convention Over Configuration: Sensible defaults reduce friction
Transparent Governance Over Closed Control: Open decision-making with community input

This allows tool builders, registry operators, and package authors to work independently while maintaining interoperability.

1. A package format (ara.json) – A standardized manifest that describes AI artifacts with metadata, dependencies, and installation sources. The format supports six types of packages:

Kiro Custom Agents: AI assistant configurations with prompts, tools, and behaviors
MCP Servers: Model Context Protocol servers that extend AI capabilities
Context: Knowledge files, prompt templates, and reference materials
Skills: Procedural knowledge via SKILL.md that agents load dynamically
Kiro Powers
Agent.md

2. A registry API – A RESTful HTTP API specification that registries implement to provide consistent endpoints for discovery, publishing, and installation.

The Package Format

Here’s what an ARA package looks like:

{ 
"$schema": "https://raw.githubusercontent.com/ara-registry/spec/refs/heads/main/ara.schema.json",
  "name": "acme/code-reviewer", 
  "version": "1.0.0", 
  "description": "AI agent for automated code review", 
  "author": "[email protected]", 
  "tags": ["code-review", "automation"], 
  "type": "agent" 
}

That’s it. A simple JSON file that any tool can understand. The $schema field points to a JSON schema for validation. Package names use namespace/package-name format to prevent conflicts. The specification enforces semantic versioning.

For packages with files, you can specify which files to include:

{ 
"$schema": "https://raw.githubusercontent.com/ara-registry/spec/refs/heads/main/ara.schema.json",
 "name": "acme/code-reviewer", 
 "version": "1.0.0", 
 "description": "AI agent for automated code review", 
 "author": "[email protected]", 
 "tags": ["code-review", "automation"], 
 "type": "agent", 
 "files": [ 
   "prompts/", 
   "config.json" 
  ] 
}

Directory paths ending with / include all contents recursively, making it easy to package entire folders.

For MCP servers, packages can reference multiple installation sources:

{ 
 "$schema": "https://raw.githubusercontent.com/ara-registry/spec/refs/heads/main/ara.schema.json", 
 "name": "acme/weather-server", 
 "version": "1.2.0", 
 "description": "MCP server for weather data access", 
 "author": "[email protected]", 
 "tags": ["weather", "api", "mcp"], 
 "type": "mcpserver", 
 "sources": [ 
   { 
     "type": "npm", 
     "package": "@acme/weather-mcp", 
     "version": "1.2.0", 
     "preferred": true 
   }, 
   { 
     "type": "pypi", 
     "package": "weather-mcp-server", 
     "version": "1.2.0" 
   } 
 ] 
}

Client tools try each source, in order, until one succeeds. This provides fallback options and ensures availability even when a registry is temporarily down.
Packages can reference dependencies:

{ 
"$schema": "https://raw.githubusercontent.com/ara-registry/spec/refs/heads/main/ara.schema.json",
  "name": "acme/crop-grower ", 
  "version": "1.0.0", 
  "description": "AI agent to grow crops", 
  "author": "[email protected]", 
  "tags": ["code-review", "automation"], 
  "type": "agent", 
  "files": [ 
    "prompts/", 
    "config.json" 
  ] , 

  "dependencies": { 
      " acme/weather-server": "^1.2.0", 
    }, 
}

Now when you or your team want to use crop-grower agent, they can just install acme/crop-grower package and ARA will install and configure acme/weather-server MCP Server.

Reproducible Installations with Lock Files

ARA includes support for lock files (ara.lock) that record exact versions and integrity hashes for reproducible installations. This ensures all team members install identical versions and verifies package contents haven’t changed. Lock files are generated automatically when installing packages locally, similar to how npm’s package-lock.json or uv’s uv.lock for Python work.

The Registry API

The specification defines standard endpoints that registries implement:

GET    /packages                                        # Search and discover
GET    /packages/{namespace}/{name}/versions            # List versions
GET    /packages/{namespace}/{name}/{version}/ara.json  # Get manifest
GET    /packages/{namespace}/{name}/{version}/download  # Download package
PUT    /packages/{namespace}/{name}/{version}           # Publish
DELETE /packages/{namespace}/{name}/{version}           # Unpublish

Registries return consistent JSON responses. This means a package published to one compliant registry can be discovered and installed by any compliant client.

The specification includes authentication patterns, ownership models, and security guidance. It defines how packages are published, how dependencies are resolved, and how lock files ensure reproducible installations.

Security Considerations

The specification includes security guidance for implementers on key topics such as:

Package integrity verification through SHA-256 hashes
Authentication and authorization for write operations
Git repository allowlisting for source installations
Signed URLs with expiration for uploads and downloads

Security is built into the specification from the ground up, not added as an afterthought.

What You Can Build

The specification has been designed with different user personas in mind: tool builders, registry operators, and package authors. It’s also extensible, so as the AI development ecosystem evolves, the spec can support new package types and registry features while maintaining backward compatibility.

Tool builders can adopt the specification to add package management to AI assistants. Users publish packages once, and they work across all compliant tools.
Registry operators can implement the API to host packages. Whether you’re building a public community registry or a private enterprise registry, the specification provides a proven foundation.
Package authors can create compliant manifests for their artifacts. Your agent configurations, MCP servers, and prompt templates become discoverable and reusable across the ecosystem.

Getting Started

The ARA specification is available now on GitHub. The repository includes:

Complete ara.json format documentation
Registry API specification with example requests and responses
JSON Schema for validation
Security guidance for implementers
Reference implementations in Python and Rust

We designed the specification to be simple to adopt. If you’re building an AI tool, you can add ARA support by parsing ara.json files—our reference implementations below show you how. If you’re operating a registry, you can implement the API endpoints. If you’re publishing packages, you can create ara.json manifests.

The specification follows open governance principles. We make decisions transparently through GitHub issues and discussions. No single organization controls the direction. You can propose enhancements, report issues, and contribute to the specification through our GitHub repository.

Reference Implementations

To help you get started, we’ve included reference libraries in both Python and Rust:

Python:

# Install the reference library 
pip install -e lib/python 
 
# Validate an ara.json file 
ara-ref validate path/to/ara.json 
 
# Read and parse a manifest 
ara-ref read path/to/ara.json

Rust:

# Build the reference library 
cd lib/rust 
cargo build --release 
 
# Validate an ara.json file 
cargo run -- validate path/to/ara.json

These reference implementations demonstrate how to parse and validate ARA manifests. They’re intended for demonstration purposes and provide a starting point for building production-ready implementations.

Try It Yourself

Create your first ara.json file:

# Create a new package manifest 
cat > ara.json << 'EOF' 
{ 
 "$schema": "https://raw.githubusercontent.com/ara-registry/spec/refs/heads/main/ara.schema.json",
  "name": "myorg/my-first-agent", 
  "version": "1.0.0", 
  "description": "My first AI agent package", 
  "author": "[email protected]", 
  "tags": ["example", "getting-started"], 
  "type": "agent" 
} 
EOF

# Validate it using the Python reference library 
pip install -e lib/python 
ara-ref validate ara.json

Clean Up

This walkthrough doesn’t create any AWS resources that require cleanup. If you created test ara.json files while exploring the specification, you can remove them from your local system:

rm ara.json
rm -rf test-packages/

Conclusion

The AI development ecosystem needs standards. Without them, we’re stuck recreating the same artifacts, adapting packages between tools, and missing opportunities to build on each other’s work. ARA provides that standard.

By defining a common format and API, the specification enables interoperability while giving implementers flexibility. Package authors publish once. Tool builders integrate once. Registry operators implement once. Everyone benefits from a shared ecosystem.

We’re releasing this as an open specification because we believe standardization benefits the entire community. As implementations emerge and the ecosystem grows, we’ll iterate on the specification based on real-world usage and community feedback.

Ready to get started?

Explore the ARA specification on GitHub
Review the ara.json format specification
Read the Registry API specification
Check out the JSON Schema
Try the Python reference library
Try the Rust reference library

Join the community. Help shape the future of AI development package management. We’re excited to see what you build with ARA.

This post first appeared on Read More