OpenAgent Specification

Version: 0.1.0
Status: Draft

OpenAgent is an open specification for defining AI agents in a technology-agnostic, portable format. It enables agent definitions to be transferred between different agentic frameworks, platforms, and implementations.

Why OpenAgent?

As AI agents proliferate across different platforms and frameworks, there's a growing need for a standard way to define what an agent is - its capabilities, behavior, constraints, and interfaces. OpenAgent provides:

• 🔄 Portability: Define once, deploy anywhere
• 📖 Clarity: Human-readable documentation that doubles as machine-parseable specification
• ✅ Validation: Programmatic validation of agent definitions
• 📊 Versioning: Built-in support for tracking agent evolution
• 🔌 Interoperability: Standard format for tools, capabilities, and integrations

Quick Start

1. Create an OpenAgent Specification

Start with the template:

cp TEMPLATE.md my-agent.md

Edit the YAML frontmatter and Markdown body to define your agent.

2. Validate Your Specification

python tools/validate.py my-agent.md

3. Use Your Specification

OpenAgent specifications can be:

• Used as documentation for your team
• Parsed by tools to generate agent implementations
• Shared with others to replicate your agent
• Version controlled alongside your code
• Used to compare different agent versions

Format Overview

OpenAgent uses Markdown with YAML frontmatter:

---
spec_version: "0.1.0"

agent:
  id: "com.example.my-agent"
  name: "My Agent"
  version: "1.0.0"
  description: "What this agent does"

capabilities:
  - id: "capability-1"
    name: "Capability Name"
    description: "What it does"

# ... more structured metadata
---

# My Agent

## Overview

Detailed documentation in Markdown format...

Key Concepts

Agent Identity

Every agent has a unique identifier, name, version, and description. This forms the core identity of the agent.

Capabilities

High-level abilities the agent possesses (e.g., "analyze data", "generate reports", "answer questions").

Tools

Specific functions or APIs the agent can invoke to accomplish tasks.

Knowledge Sources

Data sources, databases, APIs, or vector stores the agent can access.

Behavior

System prompts, guardrails, tone, and policies that govern how the agent acts.

Interaction Model

How the agent communicates - modalities (text, voice, video), conversation style, and whether human-in-the-loop is required.

Performance Criteria

Expected latency, cost constraints, and quality metrics.

Relationship to Other Standards

OpenAgent is complementary to other agent-related standards:

• A2A (Agent2Agent): Runtime protocol for agent-to-agent communication. OpenAgent defines what an agent is; A2A defines how agents communicate.
• MCP (Model Context Protocol): Provides tools and context to agents. OpenAgent can reference MCP integrations.
• OpenAPI: Defines REST APIs. OpenAgent can reference OpenAPI specs for tool definitions.

Examples

Minimal Example

---
spec_version: "0.1.0"

agent:
  id: "com.example.hello-agent"
  name: "Hello Agent"
  version: "1.0.0"
  description: "A simple greeting agent"

capabilities:
  - id: "greet"
    name: "Greeting"
    description: "Greets users in multiple languages"
---

# Hello Agent

A simple agent that greets users.

Full Example

See TEMPLATE.md for a comprehensive example with all available fields.

Validation

Use the provided validator to check your specifications:

python tools/validate.py my-agent.md

The validator checks:

• ✅ Required fields are present
• ✅ Field types are correct
• ✅ Dates are in ISO 8601 format
• ✅ Versions follow semantic versioning
• ✅ IDs are unique
• ⚠️ Recommended sections are included

File Naming

• openagent.md - Primary specification
• openagent-{variant}.md - Variants (e.g., openagent-production.md)

Extensibility

Add custom fields with the x- prefix:

x-company-internal-id: "12345"
x-deployment-region: "us-west-2"

Document custom fields in the Markdown body.

Tooling

Current Tools

• Validator (tools/validate.py): Validates OpenAgent specifications

Planned Tools

• Generator: Generate agent implementations from specs
• Converter: Convert between OpenAgent and other formats
• Diff Tool: Compare agent versions
• Registry: Publish and discover agents

Use Cases

Documentation

Use OpenAgent as living documentation for your agents. The specification serves as both human-readable docs and machine-parseable metadata.

Agent Portability

Define an agent once, then generate implementations for different frameworks:

• LangChain
• AutoGPT
• CrewAI
• Custom frameworks

Version Control

Track agent evolution over time with built-in changelog support and semantic versioning.

Team Collaboration

Share agent specifications across teams. Product managers can define requirements, engineers can implement, and everyone works from the same spec.

Agent Marketplace

Publish agent specifications to a registry where others can discover and use them.

Contributing

OpenAgent is an open specification. We welcome contributions:

• 📝 Propose specification changes
• 🐛 Report issues
• 🔧 Contribute tools
• 📚 Improve documentation
• 💡 Share use cases

Roadmap

• Initial specification (v0.1.0)
• Python validator
• JSON Schema for validation
• Example agents
• Generator tools
• Registry/marketplace
• Framework integrations
• v1.0.0 stable release

License

[To be determined - suggest MIT or Apache 2.0]

Community

• Discussions: [Link TBD]
• Issues: [Link TBD]
• Slack/Discord: [Link TBD]

Acknowledgments

Inspired by:

• OpenAPI for API specifications
• Docker Compose for service definitions
• Kubernetes manifests for declarative configuration
• A2A protocol for agent interoperability

---

Status: This is an early draft specification. Feedback and contributions are welcome as we work toward a stable v1.0.0 release.