@bluefly/openstandardagents 0.1.9 → 0.2.5-RC

package/examples/minimal/agent.yml

@@ -0,0 +1,152 @@
+# ========================================
+# Hello World - Minimal OSSA Agent Example
+# ========================================
+#
+# Use Case:
+#   Simplest possible OSSA agent to demonstrate core concepts
+#   and provide a starting template for beginners.
+#
+# Target Audience:
+#   Developers learning OSSA fundamentals, new agent creators,
+#   teams evaluating OSSA for their infrastructure.
+#
+# Complexity Level:
+#   Minimal - ~50 lines, covers essential fields only, no advanced features
+#
+# Key Concepts Demonstrated:
+#   1. Minimal required fields for OSSA compliance
+#   2. Basic capability definition (greeting, echo, status)
+#   3. Simple REST API endpoint mapping
+#   4. Service discovery configuration
+#
+# Related Examples:
+#   - See ../production/ for enterprise-grade examples
+#   - See ../advanced/ for complex multi-capability agents
+#   - See ../kagent/ for Kubernetes-integrated examples
+#
+# Learning Path:
+#   1. Start here to understand basic structure
+#   2. Move to ../production/ for best practices
+#   3. Explore ../advanced/ for custom configurations
+#
+# ========================================
+
+# OSSA specification version (required)
+# This declares which version of the OSSA spec this manifest adheres to
+# Current stable version: 1.0
+ossa: 1.0
+
+# Agent metadata section (required)
+agent:
+  # Unique identifier for this agent across all deployments
+  # Format: lowercase alphanumeric + hyphens (DNS-safe)
+  # Example: "hello-world", "user-auth-agent", "data-processor-v2"
+  name: hello-world
+
+  # Semantic version of the agent (major.minor.patch)
+  # Increment when creating breaking changes, features, or fixes
+  # Example: 1.0.0 → 1.0.1 (patch fix) → 1.1.0 (new feature) → 2.0.0 (breaking change)
+  version: 1.0.0
+
+  # Human-readable description displayed in registries and dashboards
+  # Keep to 1-2 sentences; detailed docs belong in README/wiki
+  description: Minimal OSSA-compliant agent example
+
+  # Author or organization name for attribution and support contact
+  # Can be team name, company, or individual contributor
+  author: OSSA Community
+
+  # Software license identifier (SPDX standard)
+  # Common: MIT, Apache-2.0, GPL-3.0, Proprietary
+  # See https://spdx.org/licenses/ for complete list
+  license: MIT
+
+# Service discovery configuration (required for production)
+# Controls how other services find and register this agent
+discover:
+  # Enable automatic service discovery
+  # true = agent automatically registers itself when deployed
+  # false = manual registration required via external registry
+  auto: true
+
+# Agent capabilities (required)
+# Lists logical functions/features this agent can perform
+# Each capability can be invoked through REST API endpoints
+# Format: list of capability names (lowercase, hyphen-separated)
+capabilities:
+  # Simple greeting capability - generates personalized responses
+  - greeting
+
+  # Echo capability - reflects input back (useful for testing/debugging)
+  - echo
+
+  # Status capability - reports agent health and runtime information
+  - status
+
+# REST API endpoint definitions (required)
+# Maps HTTP methods + paths to agent capabilities
+# Enables external services to invoke agent functionality
+api:
+  # POST /greet endpoint
+  # HTTP Method: POST (creates/executes something)
+  # Path: /greet (relative to agent base URL)
+  POST /greet:
+    # Which capability this endpoint invokes
+    # Must match a name in the capabilities list above
+    capability: greeting
+
+    # Human-readable description for API documentation
+    # Displayed in OpenAPI/Swagger documentation
+    description: Generate a personalized greeting
+
+  # POST /echo endpoint
+  # Demonstrates request body processing capability
+  POST /echo:
+    # Routes to echo capability defined above
+    capability: echo
+
+    # Documents expected behavior in API docs
+    description: Echo input back to user
+
+  # GET /status endpoint
+  # HTTP Method: GET (retrieves information without side effects)
+  # Used for health checks, monitoring, and readiness probes
+  GET /status:
+    # Links to status capability for runtime inspection
+    capability: status
+
+    # Documents the purpose of status endpoint
+    description: Get agent status
+
+# ========================================
+# Validation & Next Steps
+# ========================================
+#
+# To validate this manifest:
+#
+#   ossa validate ./agent.yml
+#
+# To validate with strict OSSA 1.0 compliance:
+#
+#   ossa validate ./agent.yml --version 1.0 --strict
+#
+# To create a new agent from this template:
+#
+#   ossa init my-agent --template minimal
+#   # Then customize agent.yml with your values
+#
+# To run this agent locally:
+#
+#   ossa run ./agent.yml --port 3000
+#   # Then test endpoints:
+#   curl -X POST http://localhost:3000/greet -H "Content-Type: application/json" -d '{"name":"World"}'
+#   curl -X GET http://localhost:3000/status
+#
+# Key Next Steps:
+#   1. Customize name, description, author for your use case
+#   2. Define actual implementation for each capability
+#   3. Add request/response schemas for type safety
+#   4. Add authentication/authorization if needed (see ../production/)
+#   5. Push to registry: ossa publish ./agent.yml
+#
+# ========================================

package/examples/minimal/openapi.yaml

@@ -0,0 +1,95 @@
+openapi: 3.1.0
+info:
+  title: Hello World Agent
+  version: 1.0.0
+  description: Minimal OSSA-compliant agent API
+
+servers:
+  - url: http://localhost:3000
+    description: Local development server
+
+paths:
+  /greet:
+    post:
+      summary: Generate greeting
+      operationId: greet
+      tags: [greeting]
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              type: object
+              required: [name]
+              properties:
+                name:
+                  type: string
+                  description: Name to greet
+                language:
+                  type: string
+                  enum: [en, es, fr, de]
+                  default: en
+      responses:
+        '200':
+          description: Greeting generated successfully
+          content:
+            application/json:
+              schema:
+                type: object
+                properties:
+                  message:
+                    type: string
+                  timestamp:
+                    type: string
+                    format: date-time
+
+  /echo:
+    post:
+      summary: Echo input
+      operationId: echo
+      tags: [echo]
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              type: object
+              required: [message]
+              properties:
+                message:
+                  type: string
+      responses:
+        '200':
+          description: Message echoed
+          content:
+            application/json:
+              schema:
+                type: object
+                properties:
+                  echo:
+                    type: string
+                  received_at:
+                    type: string
+                    format: date-time
+
+  /status:
+    get:
+      summary: Get agent status
+      operationId: getStatus
+      tags: [status]
+      responses:
+        '200':
+          description: Agent status
+          content:
+            application/json:
+              schema:
+                type: object
+                properties:
+                  status:
+                    type: string
+                    enum: [online, offline, maintenance]
+                  version:
+                    type: string
+                  uptime:
+                    type: integer
+                    description: Uptime in seconds

package/examples/openai/basic-agent.ossa.yaml

@@ -0,0 +1,61 @@
+apiVersion: ossa/v0.2.4
+kind: Agent
+
+metadata:
+  name: basic-openai-agent
+  version: 1.0.0
+  description: A basic OpenAI agent demonstrating simple tool usage
+
+spec:
+  role: |
+    You are a helpful assistant that can search the web and perform calculations.
+    Always provide clear and concise answers.
+
+  llm:
+    provider: openai
+    model: gpt-4o-mini
+    temperature: 0.7
+
+extensions:
+  openai_agents:
+    model: gpt-4o-mini
+    instructions: |
+      You are a helpful assistant with access to web search and calculator tools.
+      Use the search tool to find current information.
+      Use the calculator for mathematical operations.
+      Always explain your reasoning.
+    
+    tools_mapping:
+      - ossa_capability: web_search
+        openai_tool_name: search
+        description: Search the web for current information
+        parameters:
+          type: object
+          properties:
+            query:
+              type: string
+              description: The search query
+          required:
+            - query
+      
+      - ossa_capability: calculator
+        openai_tool_name: calculate
+        description: Perform mathematical calculations
+        parameters:
+          type: object
+          properties:
+            expression:
+              type: string
+              description: Mathematical expression to evaluate (e.g., "2 + 2", "sqrt(16)")
+          required:
+            - expression
+    
+    guardrails:
+      enabled: true
+      max_tool_calls: 5
+      timeout_seconds: 60
+    
+    memory:
+      enabled: true
+      type: session
+      max_messages: 20

package/examples/openai/multi-tool-agent.ossa.json

@@ -0,0 +1,165 @@
+{
+  "apiVersion": "ossa/v0.2.4",
+  "kind": "Agent",
+  "metadata": {
+    "name": "multi-tool-agent",
+    "version": "1.0.0",
+    "description": "Advanced agent demonstrating multiple tools and custom handlers"
+  },
+  "spec": {
+    "role": "You are a versatile AI assistant with multiple capabilities including web search, calculations, weather information, and text translation.",
+    "llm": {
+      "provider": "openai",
+      "model": "gpt-4o",
+      "temperature": 0.7,
+      "maxTokens": 2000
+    }
+  },
+  "extensions": {
+    "openai_agents": {
+      "model": "gpt-4o",
+      "instructions": "You are a versatile AI assistant with access to multiple tools:\n\n1. Web Search - Find current information online\n2. Calculator - Perform mathematical calculations\n3. Weather - Get weather information for any location\n4. Translator - Translate text between languages\n5. Unit Converter - Convert between different units\n6. Time Zone - Get current time in different time zones\n\nAlways:\n- Use the appropriate tool for each task\n- Explain your reasoning\n- Provide accurate and helpful information\n- Ask for clarification if needed",
+      "tools_mapping": [
+        {
+          "ossa_capability": "web_search",
+          "openai_tool_name": "search_web",
+          "description": "Search the web for current information on any topic",
+          "parameters": {
+            "type": "object",
+            "properties": {
+              "query": {
+                "type": "string",
+                "description": "The search query"
+              },
+              "num_results": {
+                "type": "number",
+                "description": "Number of results to return",
+                "default": 5
+              }
+            },
+            "required": ["query"]
+          }
+        },
+        {
+          "ossa_capability": "calculator",
+          "openai_tool_name": "calculate",
+          "description": "Perform mathematical calculations including basic arithmetic, algebra, and common functions",
+          "parameters": {
+            "type": "object",
+            "properties": {
+              "expression": {
+                "type": "string",
+                "description": "Mathematical expression to evaluate (e.g., '2 + 2', 'sqrt(16)', 'sin(pi/2)')"
+              }
+            },
+            "required": ["expression"]
+          }
+        },
+        {
+          "ossa_capability": "weather",
+          "openai_tool_name": "get_weather",
+          "description": "Get current weather information for a specific location",
+          "parameters": {
+            "type": "object",
+            "properties": {
+              "location": {
+                "type": "string",
+                "description": "City name, coordinates, or zip code"
+              },
+              "units": {
+                "type": "string",
+                "enum": ["celsius", "fahrenheit", "kelvin"],
+                "description": "Temperature units",
+                "default": "celsius"
+              },
+              "include_forecast": {
+                "type": "boolean",
+                "description": "Include 5-day forecast",
+                "default": false
+              }
+            },
+            "required": ["location"]
+          }
+        },
+        {
+          "ossa_capability": "translate",
+          "openai_tool_name": "translate_text",
+          "description": "Translate text from one language to another",
+          "parameters": {
+            "type": "object",
+            "properties": {
+              "text": {
+                "type": "string",
+                "description": "Text to translate"
+              },
+              "source_language": {
+                "type": "string",
+                "description": "Source language code (e.g., 'en', 'es', 'fr'). Use 'auto' for automatic detection",
+                "default": "auto"
+              },
+              "target_language": {
+                "type": "string",
+                "description": "Target language code (e.g., 'en', 'es', 'fr')"
+              }
+            },
+            "required": ["text", "target_language"]
+          }
+        },
+        {
+          "ossa_capability": "unit_converter",
+          "openai_tool_name": "convert_units",
+          "description": "Convert between different units of measurement",
+          "parameters": {
+            "type": "object",
+            "properties": {
+              "value": {
+                "type": "number",
+                "description": "The value to convert"
+              },
+              "from_unit": {
+                "type": "string",
+                "description": "Source unit (e.g., 'meters', 'feet', 'celsius', 'pounds')"
+              },
+              "to_unit": {
+                "type": "string",
+                "description": "Target unit (e.g., 'meters', 'feet', 'celsius', 'pounds')"
+              }
+            },
+            "required": ["value", "from_unit", "to_unit"]
+          }
+        },
+        {
+          "ossa_capability": "timezone",
+          "openai_tool_name": "get_time",
+          "description": "Get current time in a specific timezone",
+          "parameters": {
+            "type": "object",
+            "properties": {
+              "timezone": {
+                "type": "string",
+                "description": "Timezone name (e.g., 'America/New_York', 'Europe/London', 'Asia/Tokyo')"
+              },
+              "format": {
+                "type": "string",
+                "enum": ["12h", "24h", "iso"],
+                "description": "Time format",
+                "default": "12h"
+              }
+            },
+            "required": ["timezone"]
+          }
+        }
+      ],
+      "guardrails": {
+        "enabled": true,
+        "max_tool_calls": 15,
+        "timeout_seconds": 300
+      },
+      "memory": {
+        "enabled": true,
+        "type": "session",
+        "max_messages": 50
+      }
+    }
+  }
+}

package/examples/openai/swarm-agent.ossa.json

@@ -0,0 +1,59 @@
+{
+  "apiVersion": "ossa/v0.2",
+  "kind": "Agent",
+  "metadata": {
+    "name": "swarm-agent",
+    "version": "1.0.0",
+    "description": "OpenAI Agents SDK swarm agent"
+  },
+  "spec": {
+    "role": "You are a helpful AI assistant that can coordinate with other agents to solve complex tasks.",
+    "llm": {
+      "provider": "openai",
+      "model": "gpt-4o",
+      "temperature": 0.7
+    },
+    "tools": [
+      {
+        "type": "function",
+        "name": "search_web",
+        "capabilities": ["search", "retrieve"]
+      },
+      {
+        "type": "function",
+        "name": "execute_code",
+        "capabilities": ["run", "evaluate"]
+      }
+    ]
+  },
+  "extensions": {
+    "openai_agents": {
+      "enabled": true,
+      "model": "gpt-4o",
+      "instructions": "You are a helpful AI assistant that can coordinate with other agents to solve complex tasks.",
+      "tools_mapping": [
+        {
+          "ossa_capability": "search_web",
+          "openai_tool_name": "web_search",
+          "description": "Search the web for information"
+        },
+        {
+          "ossa_capability": "execute_code",
+          "openai_tool_name": "code_executor",
+          "description": "Execute Python code safely"
+        }
+      ],
+      "guardrails": {
+        "enabled": true,
+        "max_tool_calls": 10,
+        "timeout_seconds": 300
+      },
+      "memory": {
+        "enabled": true,
+        "type": "session",
+        "max_messages": 50
+      }
+    }
+  }
+}
+

package/examples/openapi-extensions/README.md

@@ -0,0 +1,87 @@
+# OSSA OpenAPI Extensions Examples
+
+This directory contains example OpenAPI 3.1 specifications demonstrating OSSA extensions for AI agents.
+
+## Examples
+
+### minimal-agent-api.openapi.yml
+
+**Purpose**: Minimal example showing basic OSSA extensions
+
+**Features Demonstrated**:
+- Root-level `x-ossa-metadata` extension
+- Root-level `x-ossa` extension with agent identification
+- Operation-level `x-ossa-capability` extension
+- Operation-level `x-ossa-autonomy` extension
+- Operation-level `x-ossa-llm` extension
+
+**Use Case**: Simple greeting agent that demonstrates the basics of OSSA extensions without complexity.
+
+### worker-agent-api.openapi.yml
+
+**Purpose**: Complete worker agent API showing all OSSA extensions
+
+**Features Demonstrated**:
+- Full `x-ossa-metadata` with governance and compliance
+- Complete `x-ossa` and `x-agent` root extensions
+- All operation-level extensions (capability, autonomy, constraints, tools, llm)
+- Parameter extensions (`X-OSSA-Agent-ID`, `X-OSSA-Version`)
+- Schema extensions (`x-ossa-capability-schema`)
+- Real-world example: Kubernetes troubleshooting agent
+
+**Use Case**: Production-ready worker agent that diagnoses Kubernetes pod issues using MCP tools.
+
+### orchestrator-agent-api.openapi.yml
+
+**Purpose**: Multi-agent orchestration example
+
+**Features Demonstrated**:
+- Orchestrator agent type
+- Multi-agent coordination capabilities
+- Complex workflow execution with task delegation
+- Higher-level constraints for orchestrator operations
+- Multiple MCP tool integrations (agent-router, agent-mesh, workflow-engine)
+
+**Use Case**: Orchestrator that coordinates multiple worker agents to execute complex workflows.
+
+## Running Examples
+
+### Validate Examples
+
+```bash
+# Validate a specific example
+ossa validate --openapi examples/openapi-extensions/minimal-agent-api.openapi.yml
+
+# Validate all examples
+find examples/openapi-extensions -name "*.openapi.yml" -exec ossa validate --openapi {} \;
+```
+
+### Using with OpenAPI Tools
+
+All examples are valid OpenAPI 3.1 specs and work with standard OpenAPI tools:
+
+```bash
+# Generate documentation with Redoc
+npx @redocly/cli build-docs examples/openapi-extensions/worker-agent-api.openapi.yml
+
+# Generate client with openapi-generator
+npx @openapitools/openapi-generator-cli generate \
+  -i examples/openapi-extensions/worker-agent-api.openapi.yml \
+  -g typescript-axios \
+  -o ./generated-client
+```
+
+### Viewing Examples
+
+Use any OpenAPI viewer:
+- [Swagger Editor](https://editor.swagger.io/) - Paste YAML content
+- [Swagger UI](https://swagger.io/tools/swagger-ui/) - Host locally
+- [Stoplight Studio](https://stoplight.io/studio) - Desktop app
+
+## Documentation
+
+For complete documentation on OSSA OpenAPI extensions, see:
+- [OpenAPI Extensions Documentation](../../docs/openapi-extensions.md)
+- [OSSA Specification](../../spec/v0.2.2/OSSA-SPECIFICATION-v0.2.2.md)
+- [GitHub Repository](https://github.com/blueflyio/openstandardagents)
+