OSSA Specification v0.2.4

The Open Standard for Scalable AI Agents

Overview

OSSA (Open Standard for Scalable AI Agents) is the definitive open standard for defining and connecting AI agents. Just as OpenAPI standardized REST APIs, OSSA standardizes AI agent interaction, enabling vendor-neutral interoperability across frameworks.

OSSA is NOT a framework - it's a standard that defines the contract. Implementations provide the functionality.

Key Principles

Specification-Driven - OSSA defines the standard, implementations provide functionality
Implementation-Agnostic - Any runtime can implement OSSA (Kubernetes, Docker, Serverless, etc.)
Minimal Tooling - Basic CLI for validation & generation
No Vendor Lock-in - Deploy to any infrastructure (AWS, GCP, Azure, on-premise)
Vendor-Neutral - Community-driven, not controlled by any single company
Interoperable - Common language enabling diverse AI agents to work together
Trustworthy - Built with compliance and security in mind

Specification Version

Current Version: v0.2.4
Specification: ossa-0.2.4.schema.json
Website: openstandardagents.org

Required Fields

Every OSSA-compliant agent manifest must contain:

ossaVersion: "0.2.4"

agent:
  id: my-agent                    # DNS-1123 format (lowercase, hyphens allowed)
  name: My Agent                  # Human-readable name
  version: "1.0.0"                # Semantic version (MAJOR.MINOR.PATCH)
  role: worker                    # Agent role (governor, worker, critic, observer)

  runtime:
    type: k8s                     # Runtime type (k8s, docker, local, serverless)

  capabilities:                   # At least one capability required
    - name: process_data
      description: Process incoming data
      input_schema:               # JSON Schema for inputs
        type: object
        properties:
          data:
            type: string
      output_schema:              # JSON Schema for outputs
        type: object
        properties:
          result:
            type: string

Agent Roles

OSSA defines four primary agent roles:

Role	Purpose	Responsibilities
governor	Orchestration and coordination	Manages workflows, coordinates other agents, enforces policies
worker	Task execution	Performs specific tasks, processes data, executes operations
critic	Quality assurance	Reviews outputs, validates results, provides feedback
observer	Monitoring and reporting	Tracks system state, collects metrics, generates reports

Runtime Types

OSSA supports multiple runtime environments:

Runtime	Description	Use Case
k8s	Kubernetes	Production deployments, enterprise scale
docker	Docker containers	Local development, testing
local	Local process	Development, debugging
serverless	FaaS platforms	Event-driven, auto-scaling workloads
edge	Edge computing	IoT, distributed systems

Capabilities

Capabilities define what an agent can do. Each capability must include:

capabilities:
  - name: unique_capability_name
    description: Human-readable description
    input_schema:                 # JSON Schema v7
      type: object
      properties: { ... }
      required: [ ... ]
    output_schema:                # JSON Schema v7
      type: object
      properties: { ... }

    # Optional fields
    parameters:                   # Configuration parameters
      timeout: 30000
      retries: 3

    dependencies:                 # Required capabilities from other agents
      - agent_id: data-processor
        capability: process_data

Optional Fields

Metadata

agent:
  metadata:
    description: Detailed agent description
    author: Your Name
    license: Apache-2.0
    homepage: https://example.com
    repository: https://gitlab.com/org/project
    tags:
      - data-processing
      - ml
      - production

Model Configuration

agent:
  model:
    provider: anthropic           # or openai, google, etc.
    name: claude-sonnet-4
    version: "20250101"
    parameters:
      temperature: 0.7
      max_tokens: 4096
      top_p: 0.9

Dependencies

agent:
  dependencies:
    agents:                       # Other OSSA agents
      - id: vector-search
        version: "^1.0.0"

    services:                     # External services
      - type: database
        provider: postgresql
        version: "15"

      - type: vector_db
        provider: qdrant
        version: "1.7.0"

Security

agent:
  security:
    authentication:
      type: oauth2
      provider: gitlab

    authorization:
      rbac:
        roles:
          - admin
          - user

    compliance:
      frameworks:
        - fedramp
        - soc2

      data_classification: sensitive

Monitoring

agent:
  monitoring:
    health_check:
      endpoint: /health
      interval: 30s

    metrics:
      endpoint: /metrics
      format: prometheus

    tracing:
      enabled: true
      provider: opentelemetry
      endpoint: http://jaeger:4318

Complete Example

ossaVersion: "0.2.4"

agent:
  id: compliance-checker
  name: FedRAMP Compliance Checker
  version: "1.2.0"
  role: critic

  metadata:
    description: Automated FedRAMP compliance validation agent
    author: Bluefly.io
    license: Apache-2.0
    repository: https://gitlab.com/blueflyio/agent-platform/compliance-engine
    tags:
      - compliance
      - fedramp
      - security

  runtime:
    type: k8s
    config:
      replicas: 3
      resources:
        requests:
          memory: "256Mi"
          cpu: "100m"
        limits:
          memory: "512Mi"
          cpu: "500m"

  model:
    provider: anthropic
    name: claude-sonnet-4
    version: "20250101"
    parameters:
      temperature: 0.2            # Low temperature for consistency
      max_tokens: 8192

  capabilities:
    - name: validate_nist_controls
      description: Validate NIST 800-53 security controls
      input_schema:
        type: object
        properties:
          control_id:
            type: string
            pattern: "^[A-Z]{2}-\\d+$"
          implementation:
            type: object
        required:
          - control_id
          - implementation
      output_schema:
        type: object
        properties:
          compliant:
            type: boolean
          findings:
            type: array
            items:
              type: object
              properties:
                severity:
                  type: string
                  enum: [critical, high, medium, low]
                message:
                  type: string
          recommendations:
            type: array
            items:
              type: string
      parameters:
        timeout: 60000
        retries: 2

    - name: generate_compliance_report
      description: Generate FedRAMP compliance report
      input_schema:
        type: object
        properties:
          system_id:
            type: string
          assessment_date:
            type: string
            format: date
        required:
          - system_id
      output_schema:
        type: object
        properties:
          report_id:
            type: string
          compliance_score:
            type: number
            minimum: 0
            maximum: 100
          report_url:
            type: string
            format: uri

  dependencies:
    agents:
      - id: security-scanner
        version: "^2.0.0"
        capabilities:
          - scan_vulnerabilities

    services:
      - type: database
        provider: postgresql
        version: "15"

      - type: vector_db
        provider: qdrant
        version: "1.7.0"

  security:
    authentication:
      type: oauth2
      provider: gitlab

    authorization:
      rbac:
        roles:
          - compliance_admin
          - auditor
          - reader

    compliance:
      frameworks:
        - fedramp
        - soc2
        - nist-800-53
      data_classification: confidential

  monitoring:
    health_check:
      endpoint: /health
      interval: 30s
      timeout: 5s

    metrics:
      endpoint: /metrics
      format: prometheus

    tracing:
      enabled: true
      provider: opentelemetry
      endpoint: http://jaeger-collector:4318

    logging:
      level: info
      format: json
      output: stdout

Validation

Validate your OSSA manifest:

# Using OSSA CLI
ossa validate agent.yml

# Using BuildKit (includes OSSA validation + extras)
buildkit ossa validate agent.yml

Next Steps

JSON Schema Reference - Complete schema documentation
Versioning Strategy - Semantic versioning for OSSA
Compliance Badge - Display OSSA compliance
OpenAPI Extensions - Extend OpenAPI with OSSA
Migration Guides - Migrate from other frameworks

External Resources

Specification: ossa-0.2.4.schema.json
Website: openstandardagents.org
Examples: GitLab Examples
Issues: GitLab Issues

← Back to Standards | Next: Schema Reference →