Open Standard for Software Agents (OSSA)

OSSA is an open standard for defining, validating, discovering, and governing software agents.

OSSA is not a framework. It is a contract layer: schema, identity, capabilities, policy bindings, discovery metadata, and validation rules that allow agents to be portable across runtimes and organizations.

Development happens on GitLab (source of truth). Source | Issues | npm

Why OSSA Exists

Agent systems are fragmenting across IDEs, model providers, MCP servers, workflow engines, Drupal, GitLab, Kubernetes, and private enterprise platforms.

OSSA provides a stable contract for agent identity, manifests, tool declarations, capability boundaries, governance metadata, runtime interoperability, discovery, validation, and auditability.

Without a contract layer, every integration is bespoke. With OSSA, one manifest describes an agent and any conforming runtime can consume it.

Core Analogy

OpenAPI : APIs :: OSSA : Agents

OpenAPI does not implement your API. It describes it. OSSA does not implement your agent. It describes it.

Package

npm: @bluefly/openstandardagents

Current stable release: 0.5.6

Note: 0.5.3, 0.5.4, and 0.5.5 were accidentally published during recovery and are deprecated. Do not use them.

npm install @bluefly/[email protected]

Requires Node.js 20+.

CLI

npx ossa validate ./agent.ossa.yaml
npx ossa validate-spec
npx ossa discover https://example.com
npx ossa resolve-did did:web:example.com:agent:demo
npx ossa lint-openapi

Exit code 0 means valid. Non-zero prints JSON-pointer paths and error messages.

From a repo clone (avoids conflicting global shims):

pnpm install
pnpm build
pnpm run ossa validate path/to/agent.ossa.yaml

What This Package Contains

• JSON Schemas for OSSA v0.5 manifests (agent, workflow, registry, policy-binding)
• Reference OpenAPI contracts (invocation, compliance-engine)
• Validation utilities (programmatic and CLI)
• CLI entrypoint (ossa)
• Reference agent manifests
• Well-known discovery document (.well-known/ossa.json)

What This Package Does Not Contain

• Agent runtime
• Orchestration engine
• MCP server implementation
• Deployment controller
• Drupal module
• GitLab automation
• Policy decision point

Those belong in adjacent projects (see Project Ecosystem below).

OSSA v0.5 Concepts

Agent Manifest — Defines an agent's identity, role, tools, capabilities, governance metadata, and interoperability surfaces.

Role — A behavioral and operational profile used by an agent, IDE, runtime, or workflow.

Tool — A callable capability declared by the manifest and enforced by the runtime or policy layer.

Workflow — A deterministic or semi-deterministic process composed from agents, tools, events, or external systems.

Registry — A discoverable index of agent manifests and related metadata.

Policy Binding — A link between an agent/action/resource and an external policy authority such as Cedar or ContractPlane.

Minimal Manifest Example

apiVersion: ossa/v0.5
kind: Agent
metadata:
  name: accessibility-reviewer
  namespace: blueflyio
  version: 1.0.0
  uuid: 7e3f4b8d-2c91-4a6e-b015-9f8d3e2c7a64
spec:
  role: accessibility-reviewer
  description: Reviews content and rendered pages for accessibility issues.
  tools:
    - name: drupal_render_api
      type: mcp
    - name: axe_core_scanner
      type: external
  capabilities:
    - name: scan_page_accessibility
    - name: generate_remediation_plan
  governance:
    cedar_policy_pack: accessibility-reviewer-v1
    trust_tier: T2
    evidence_required: true
  discovery:
    duadp: true

Validation

Programmatic

import { validateManifestFile } from '@bluefly/openstandardagents';

const result = await validateManifestFile('agent.ossa.yaml');
if (!result.valid) {
  console.error(result.errors);
  process.exit(1);
}

CLI

ossa validate ./agent.ossa.yaml

Exports

| Export | Purpose | |--------|---------| | @bluefly/openstandardagents | Validator entrypoint | | @bluefly/openstandardagents/schema | v0.5 agent schema | | @bluefly/openstandardagents/schema/v0.5 | Explicit v0.5 agent schema | | @bluefly/openstandardagents/schema/workflow | Workflow schema | | @bluefly/openstandardagents/schema/registry | Registry schema | | @bluefly/openstandardagents/schema/policy-binding | Policy binding schema | | @bluefly/openstandardagents/openapi/invocation | Invocation OpenAPI contract | | @bluefly/openstandardagents/well-known | OSSA well-known discovery document | | @bluefly/openstandardagents/validation | Validation utilities (alias) |

Project Ecosystem

| Project | Role | |---------|------| | openstandardagents | OSSA schemas, CLI, validator, reference contracts | | duadp | Federated discovery and agent registry resolution | | agents | Canonical Bluefly agent manifests, including @blu | | skills | Reusable skill packages referenced by agents | | compliance-engine | Cedar policy evaluation, evidence, and OSSA validation API | | cedar-policies | Cedar policy source (product IP) | | ai_agents_ossa | Drupal bridge between OSSA manifests and AI Agents | | api_normalization | API/OpenAPI normalization layer | | kb_cache | Contextual memory and retrieval engine | | ContextControl.ai | Governed Drupal-based context/control plane | | blu-cli | Governed Bluefly operator CLI | | context-cli | ContextControl/knowledge workflow CLI | | gitlab_components | Reusable CI/CD pipeline components | | ossa-studio | Visual/modeling surface for OSSA authoring |

Relationship to DUADP

DUADP handles discovery. OSSA defines what is discovered.

OSSA answers: What is this agent? What can it do? What tools does it declare? What policy bindings apply? What schema validates it?

DUADP answers: Where is the agent card? How is it resolved? How is it revoked? How is it discovered across organizations?

Relationship to ContractPlane and Cedar

OSSA declares governance metadata and policy bindings. It does not evaluate policy.

ContractPlane and Cedar are policy/evidence enforcement layers that consume OSSA manifests and evaluate actions before runtime execution. Cedar policies are authored in cedar-policies and evaluated by compliance-engine.

Relationship to Drupal

Drupal is one implementation surface for OSSA-governed agents. OSSA remains runtime-agnostic. Drupal is an implementation target, not a dependency of the standard.

Relevant Drupal modules: ai, ai_agents, ai_agents_ossa, tool, mcp, orchestration, eca, agui, api_normalization, ai_context, kb_cache.

Why OSSA + DUADP

AI agents need the same foundational infrastructure the internet has: identity, discovery, and governance.

Identity   (OSSA)  — Agent DID, signed manifests, Cedar policy bindings
Discovery  (DUADP) — Federated DNS + WebFinger, gossip, trust-tier gating
Execution  (yours) — Kubernetes, Claude, LangChain, Drupal, or any runtime

OSSA defines the agent. DUADP discovers it. Your runtime executes it.

Development

pnpm install
pnpm build
pnpm typecheck
pnpm test
pnpm validate
pnpm gen:check
pnpm publint

Full CI-equivalent gate:

pnpm ci:validate

Runs install, build, typecheck, vitest conformance, schema validation, OpenAPI validation, generated-code checks, and package dry-run. All jobs are fail-closed.

Conformance Targets

Tests validate the canonical platform agent at WORKING_DEMOs/agents/agents/@blu/agent.ossa.yaml when OSSA_AGENTS_ROOT points at that repo (default relative path from this checkout). Toy example directories are not shipped in this package.

Release Policy

• Release branches are protected.
• Release artifacts must pass build, typecheck, tests, schema validation, OpenAPI validation, generated-code checks, and package dry-run.
• npm versions are immutable after publish.
• Package contents must be allowlisted through files.
• Do not publish from a dirty working tree.
• Do not publish from a generated temporary tree unless the package identity and tarball contents are verified.

npm State

0.5.6 is the current stable release.

0.5.3, 0.5.4, and 0.5.5 were accidentally published during recovery and are deprecated. Do not use them.

Contributing

Use GitLab issues and merge requests against the source of truth:

https://gitlab.com/blueflyio/ossa/openstandardagents

Before submitting:

pnpm ci:validate

License

Apache-2.0. See LICENSE.