OSSA Web Agents (Playground)

GitLab: https://gitlab.com/blueflyio/ossa/lab/openstandard-ui
npm (public): https://www.npmjs.com/package/@bluefly/ossa-studio — install with npm i @bluefly/ossa-studio or pnpm add @bluefly/ossa-studio. MIT license.

This repository is the interactive playground and agent creator for OSSA. It hosts:

• Agent Creator UI - Interactive "Try Now" creator (embedded in website homepage)
• Playground Interface - Full-featured agent editing and testing
• User-Generated Agents - All agents created via the creator
• Showcase Gallery - Curated showcase-worthy agents for website display
• Site Agents - Agents that maintain openstandardagents.org
• GitLab Agents - GitLab automation agents

Quick Start

# Install dependencies
npm install

# Run development server
npm run dev

# Build for production
npm run build

Architecture

Agent Creator (app/creator/)

Interactive agent creation interface that can be:

• Used standalone at /creator
• Embedded as iframe/widget on website homepage
• Deployed to GitLab Pages/CDN for embedding

Components:

• AgentCreator - Main creator component (wizard → editor → preview)
• AgentWizard - 6-step wizard for agent creation
• ManifestEditor - Monaco editor for YAML editing
• ValidationPanel - Real-time validation feedback
• PreviewPanel - Agent preview

Artifacts (artifacts/)

• user-generated/ - All user-created agents (gitignored)
• showcase/ - Curated showcase agents
  • featured/ - Featured agents
  • community/ - Community submissions
  • metadata/gallery.json - Generated gallery index

Separation of duties: The canonical Git repo for wizard-generated agents is openstandard-generated-agents. Save/push from the creator should target that repo; the platform registry (platform-agents) is for platform agents only and must not be used for user-generated output.

API (OpenAPI-first)

Spec: spec/openapi.yaml (OpenAPI 3.1). Schemas: spec/schemas.zod.ts (Zod; request/response validation).

| Method | Path | Description | |--------|------|-------------| | GET | /api/agents | List cataloged agents (query: page, limit, minScore, curated, sort) | | POST | /api/agents | Save agent (body: manifest YAML string, optional metadata); returns uuid (canonical id) | | GET | /api/agents/:id | Get one agent (manifest + metadata; uuid when length >= 20) | | GET | /api/agents/:id/artifact | Download manifest (query: format=yaml|json) | | POST | /api/score | Score agent 0-100 (body: manifest or agentId); persists score when agentId provided | | GET | /api/leaderboard | Leaderboard by score (query: minScore=70, limit, page) | | GET | /api/showcase/gallery | Gallery index for website sync | | POST | /api/export | Trigger export pipeline (manifest + platform) | | POST | /api/manifest/validate | Validate manifest against OSSA schema |

Legacy: /api/agents/save is a deprecated alias for POST /api/agents. Use POST /api/agents per spec.

Agent UUID (unique id): Every saved agent gets a server-generated UUID (crypto.randomUUID(), 36 chars). It is the catalog id (directory name under artifacts/user-generated/), stored in metadata as uuid, and returned as id, uuid, and sessionId on POST. List and detail responses include uuid only when length >= 20 (legacy short ids omitted). See spec/openapi.yaml and spec/schemas.zod.ts for minLength and validation.