OSSA Specification - Complete Reference

Single Source of Truth - This document consolidates all OSSA specification information, comparisons, and migration guides into one authoritative reference.

Overview

The Open Standard for Software Agents (OSSA) is a specification standard for defining AI agents, similar to how OpenAPI standardizes REST APIs. OSSA enables agent interoperability across frameworks, runtimes, and organizations.

Table of Contents

1. Specification Versions
2. Core Concepts
3. Schema Reference
4. Framework Comparison
5. Migration Guides
6. Version-Specific Information

---

Specification Versions

Current Version: v0.3.2

Status: Stable
Release Date: 2025-12-31
Schema: v0.3.2 JSON Schema

Previous Versions

• v0.3.1: Previous stable release
• v0.3.0: First v0.3.x stable release
• v0.2.9: Legacy version

Version Migration

See Migration Guides section for version-to-version migration instructions.

---

Core Concepts

What is OSSA?

OSSA is a specification standard (not a framework) that defines:

• A canonical folder structure (agents/) that scales from one agent to thousands
• Agent manifest format (agent.ossa.yaml) as the single source of truth
• Agent capabilities, roles, and taxonomy
• Context window strategies (sliding window + long-term memory)
• Agent-to-agent messaging (A2A protocol)
• Workflow composition
• Observability and governance

Key Principles

1. Framework Agnostic: Works with any agent framework
2. Language Independent: Not tied to any programming language
3. Vendor Neutral: Open standard, no vendor lock-in
4. Designed for Enterprise: Built-in governance, compliance, and observability features
5. Versioned: Semantic versioning with migration paths
6. Auditable Context: Agents declare deterministic context strategies for predictable behavior

Resource Kinds

OSSA v0.3.2 supports multiple resource kinds:

• Agent: Single agent definition
• Workflow: Multi-agent composition
• Task: Deterministic task definition
• MessageRouting: Message routing rules

---

Schema Reference

Canonical Folder Structure

OSSA defines a filesystem layout that scales from a single agent to thousands:

agents/
├── registry.yaml               # Optional: local index (generated)
├── _shared/                    # Optional: shared prompt/tool/policy assets
│   ├── policies/               # Org/team policy bundles (OPA, etc.)
│   ├── prompts/                # Reusable prompt fragments
│   └── tools/                  # Shared tool schemas (OpenAPI/JSON Schema)
├── <agent-name>/
│   ├── agent.ossa.yaml         # REQUIRED: single source of truth
│   ├── system-prompt.md        # Optional: long prompt (referenced by manifest)
│   ├── tools/                  # Optional: agent-specific tool schemas
│   ├── knowledge/              # Optional: RAG sources (docs) or pointers
│   └── tests/                  # Optional: evals + conformance tests

agents-workspace/               # Derived outputs (gitignored)
├── exports/                    # Generated target formats (LangGraph/CrewAI/etc.)
├── state/                      # Runtime checkpoints
└── logs/                       # Traces

See Project Structure for the complete guide.

What a Perfect Agent Must Declare

At minimum, the agent.ossa.yaml manifest must answer four questions:

1. Who published this? - Identity + provenance (metadata, labels, annotations)
2. What can it do? - Capabilities/skills + interfaces (role, domain, tools)
3. What does it need? - Runtime + resources + dependencies (LLM config, sandbox, limits)
4. What is it allowed to access? - Policy + secrets + data boundaries

Core Agent Fields

Agent Identification

• metadata.name: Human-readable name
• metadata.version: Semantic version (e.g., "1.2.0")
• metadata.labels: Key-value pairs for classification (team, tier, etc.)
• metadata.annotations: Extended metadata (owner, SLA, repo URL)

Agent Capabilities

• spec.role: Agent role classification (worker, supervisor, coordinator, specialist)
• spec.domain: Business/functional domain
• spec.capabilities: Array of capability names
• spec.tools: Available tools with source references

Agent Context Strategy

• spec.context.strategy: How to manage the context window (sliding_window, summarize, etc.)
• spec.context.max_tokens: Hard token limit
• spec.context.reserved_tokens: Token reservations for system prompt, tools, and output
• spec.context.long_term_memory: Vector store configuration for persistent recall

Agent Configuration

• spec.llm: LLM provider and model configuration with env var substitution
• spec.runtime: Execution sandbox and resource limits
• spec.policies: Policy references (OPA, custom)
• spec.data_boundaries: Allowed and denied data namespaces

Complete Schema Documentation

For detailed field-by-field documentation, see:

• Schema Reference Index
• Agent Spec
• Workflow Spec

Validation

Validate agent manifests:

ossa validate agent.ossa.yaml

---

Framework Comparison

OSSA vs. Popular Frameworks

Key Differentiators

OSSA Advantages

1. Framework Agnostic: Not tied to any specific framework
2. Multi-Language: Works with any programming language
3. Enterprise Governance: Built-in compliance, audit, and policy enforcement
4. Standardized Observability: OpenTelemetry integration
5. Portability: Agents can move between runtimes
6. Versioning: Semantic versioning with migration paths

Framework-Specific Strengths

• LangChain: Rich ecosystem, rapid prototyping
• AutoGPT: Full autonomy, self-directed tasks
• CrewAI: Role-based agent teams, simple orchestration
• AutoGen: Conversational AI, human-in-the-loop

Detailed Comparison

For comprehensive framework comparison, see:

• Framework Comparison Matrix
• Agent Schema Comparison

---

Migration Guides

Framework Migrations

Migrate agents from popular frameworks to OSSA:

• LangChain to OSSA
• CrewAI to OSSA
• Drupal ECA to OSSA
• Anthropic MCP to OSSA
• OpenAI to OSSA
• Langflow to OSSA

Version Migrations

v0.3.1 -> v0.3.2

New Features:

• Unified LLM configuration with runtime-configurable models
• Environment variable substitution for LLM config
• Fallback models configuration
• Retry configuration with backoff strategies
• Cross-platform compatibility (GitLab Duo, Google A2A, MCP)

Migration Steps:

1. Update apiVersion to ossa/v0.3.2
2. Optionally migrate hardcoded provider/model to env vars
3. Add fallback_models for production resilience
4. Configure retry_config for transient failures
5. Validate with ossa validate

Migration Tool:

ossa migrate agent.ossa.yaml --from v0.3.1 --to v0.3.2

v0.2.x -> v0.3.2

Breaking Changes:

• Agent messaging (A2A protocol) introduced
• Workflow composition enhanced
• Schema structure updated
• Unified LLM configuration

Migration Steps:

1. Update apiVersion to ossa/v0.3.2
2. Review messaging configuration
3. Update workflow definitions
4. Migrate LLM config to new unified format
5. Validate with ossa validate

Migration Tool:

ossa migrate agent.ossa.yaml --from v0.2.9 --to v0.3.2

---

Version-Specific Information

OSSA v0.3.2

New Features

1. Unified LLM Configuration

   • Runtime-configurable models (no hardcoded providers)
   • Environment variable substitution: ${LLM_PROVIDER:-anthropic}
   • Fallback models for automatic failover
   • Retry configuration with backoff strategies
   • Cross-platform compatibility (OSSA, GitLab Duo, Google A2A, MCP)

2. Execution Profiles

   • Task-specific optimization profiles
   • Compatible with Google A2A
   • Profiles: fast, balanced, deep, safe

3. Enhanced Resilience

   • Fallback conditions: on_error, on_timeout, on_rate_limit, always
   • Backoff strategies: exponential, linear, constant

4. Enterprise Governance

   • Compliance metadata (SOC2, GDPR, HIPAA)
   • Policy enforcement
   • Audit logging

Schema Changes

• Added fallback_models to LLM config
• Added retry_config to LLM config
• Added profile field for execution profiles
• Environment variable substitution support

Example Configuration

apiVersion: ossa/v0.4.9
kind: Agent
metadata:
  name: production-agent
  version: 1.0.0
spec:
  llm:
    provider: ${LLM_PROVIDER:-anthropic}
    model: ${LLM_MODEL:-claude-sonnet-4}
    profile: balanced
    temperature: 0.3
    maxTokens: 8192

    fallback_models:
      - provider: openai
        model: gpt-4o
        condition: on_error

    retry_config:
      max_attempts: 3
      backoff_strategy: exponential

OSSA v0.3.1

Features

1. Agent-to-Agent (A2A) Messaging

   • Standardized message envelopes
   • Message routing and delivery
   • Authentication and encryption support

2. Enhanced Workflow Composition

   • Multi-agent workflows
   • Conditional execution
   • Parallel and sequential patterns

3. Improved Observability

   • OpenTelemetry integration
   • Distributed tracing
   • Structured logging

---

Agent Schema Comparison

GitLab Duo Agent vs. OSSA Agent

GitLab Duo Agent:

• Specialized for GitLab integration
• Project-scoped agents
• GitLab-specific triggers

OSSA Agent:

• Platform-agnostic design
• Universal trigger types
• Framework-independent

For detailed comparison, see:

• Agent Schema Comparison

---

Related Documentation

Getting Started

• 5-Minute Overview
• Installation Guide
• Hello World Tutorial

Technical Reference

• Schema Reference
• CLI Reference
• API Reference
• LLM Configuration

Integration Guides

• Drupal Integration
• Symphony + Drupal Integration
• Framework Support

---

References

• OSSA Specification Repository: https://gitlab.com/blueflyio/openstandardagents
• npm Package: @bluefly/openstandardagents
• Website: https://openstandardagents.org
• JSON Schema: v0.3.2 Schema

---

Changelog

See Changelog for detailed version history and changes.

---

Last Updated: 2025-12-31
Specification Version: v0.3.2
Document Status: Complete and Authoritative