@bluefly/openstandardagents 0.2.4 → 0.2.5-RC

package/website/content/docs/getting-started/running-agents.md

@@ -15,7 +15,7 @@ Learn how to run OSSA agents using the CLI.
 ## Installation
 
 ```bash
-npm install -g @bluefly/openstandardagents
+npm install -g @bluefly/open-standards-scalable-agents
 ```
 
 ## Quick Start
@@ -30,7 +30,7 @@ export OPENAI_API_KEY=sk-...
 
 ```yaml
 # support-agent.ossa.yaml
-apiVersion: ossa/v0.2.3
+apiVersion: ossa/v0.2.x
 kind: Agent
 
 metadata:
@@ -64,13 +64,75 @@ ossa run support-agent.ossa.yaml -v
 
 ## Command Options
 
-| Option | Description |
-|--------|-------------|
-| `-r, --runtime` | Runtime adapter (default: openai) |
-| `-v, --verbose` | Show tool calls |
-| `-m, --message` | Single message mode |
-| `--no-validate` | Skip validation |
-| `--max-turns` | Max tool call iterations |
+| Option | Description | Default |
+|--------|-------------|---------|
+| `-r, --runtime <runtime>` | Runtime adapter to use | `openai` |
+| `-v, --verbose` | Show detailed output including tool calls | `false` |
+| `-m, --message <message>` | Single message mode (non-interactive) | Interactive REPL |
+| `--no-validate` | Skip manifest validation before running | Validation enabled |
+| `--max-turns <turns>` | Maximum tool call iterations | `10` |
+
+### Detailed Option Descriptions
+
+#### Runtime Selection (`-r, --runtime`)
+
+Choose which runtime adapter to use for executing your agent:
+
+```bash
+# Use OpenAI (default)
+ossa run agent.ossa.yaml --runtime openai
+
+# Short form
+ossa run agent.ossa.yaml -r openai
+```
+
+#### Verbose Mode (`-v, --verbose`)
+
+Enable verbose output to see detailed information about tool calls and execution:
+
+```bash
+ossa run agent.ossa.yaml --verbose
+
+# Shows:
+# - Tool call names and arguments
+# - Tool execution results
+# - Conversation flow
+# - Validation details
+```
+
+#### Single Message Mode (`-m, --message`)
+
+Execute a single message and exit (non-interactive):
+
+```bash
+# Ask a single question
+ossa run agent.ossa.yaml -m "What is the weather today?"
+
+# Long form
+ossa run agent.ossa.yaml --message "Analyze this data"
+```
+
+#### Skip Validation (`--no-validate`)
+
+Skip manifest validation for faster startup (use with caution):
+
+```bash
+ossa run agent.ossa.yaml --no-validate
+```
+
+**Note:** Validation is recommended to catch configuration errors early.
+
+#### Max Turns (`--max-turns`)
+
+Limit the number of tool call iterations to prevent infinite loops:
+
+```bash
+# Allow up to 5 tool call iterations
+ossa run agent.ossa.yaml --max-turns 5
+
+# Default is 10
+ossa run agent.ossa.yaml --max-turns 10
+```
 
 ## Supported Runtimes
 
@@ -83,7 +145,7 @@ ossa run support-agent.ossa.yaml -v
 
 ## Adding Tools
 
-Define tools in your manifest:
+Define tools in your manifest using the OpenAI extension:
 
 ```yaml
 extensions:
@@ -97,11 +159,151 @@ extensions:
           properties:
             order_id:
               type: string
+              description: The order ID to track
           required: [order_id]
 ```
 
+## Interactive REPL Mode
+
+When you run an agent without the `-m` flag, you enter interactive mode:
+
+```bash
+ossa run agent.ossa.yaml
+
+# Output:
+# ✓ Agent 'my-agent' loaded
+#   Model: gpt-4o-mini
+#   Tools: search, calculate
+#
+# Entering interactive mode. Type "exit" to quit.
+#
+# You: 
+```
+
+In interactive mode:
+- Type your messages and press Enter
+- The agent maintains conversation history
+- Type `exit` or `quit` to end the session
+- Press Ctrl+C to force quit
+
+## Troubleshooting
+
+### API Key Not Set
+
+**Error:** `OPENAI_API_KEY environment variable not set`
+
+**Solution:**
+```bash
+export OPENAI_API_KEY=sk-your-key-here
+```
+
+### Validation Errors
+
+**Error:** `Agent manifest validation failed`
+
+**Solution:** Check your manifest against the schema:
+```bash
+ossa validate agent.ossa.yaml --verbose
+```
+
+### Runtime Not Supported
+
+**Error:** `Runtime 'xyz' not supported yet`
+
+**Solution:** Use the OpenAI runtime (currently the only supported runtime):
+```bash
+ossa run agent.ossa.yaml --runtime openai
+```
+
+### Max Turns Reached
+
+**Error:** `Max turns reached without completion`
+
+**Solution:** Increase the max turns limit:
+```bash
+ossa run agent.ossa.yaml --max-turns 20
+```
+
+## Advanced Usage
+
+### Combining Options
+
+You can combine multiple options:
+
+```bash
+# Verbose single message with custom max turns
+ossa run agent.ossa.yaml -v -m "Complex query" --max-turns 15
+
+# Skip validation in verbose mode
+ossa run agent.ossa.yaml --no-validate --verbose
+```
+
+### Using with Different Models
+
+Specify the model in your manifest:
+
+```yaml
+spec:
+  llm:
+    provider: openai
+    model: gpt-4-turbo
+    temperature: 0.8
+    maxTokens: 2000
+```
+
+Or use the OpenAI extension:
+
+```yaml
+extensions:
+  openai_agents:
+    model: gpt-4-turbo
+    instructions: Custom system prompt
+```
+
+### Environment Variables
+
+The run command respects these environment variables:
+
+- `OPENAI_API_KEY` - Your OpenAI API key (required)
+- `OPENAI_ORG_ID` - Your OpenAI organization ID (optional)
+
+## Examples
+
+### Customer Support Agent
+
+```bash
+# Create the manifest
+cat > support.ossa.yaml << EOF
+apiVersion: ossa/v0.2.4
+kind: Agent
+metadata:
+  name: support-agent
+  version: 1.0.0
+spec:
+  role: You are a helpful customer support agent
+  llm:
+    provider: openai
+    model: gpt-4o-mini
+EOF
+
+# Run interactively
+ossa run support.ossa.yaml
+
+# Or single message
+ossa run support.ossa.yaml -m "How do I reset my password?"
+```
+
+### Code Assistant with Tools
+
+```bash
+# See examples/openai/swarm-agent.ossa.json for a complete example
+ossa run examples/openai/swarm-agent.ossa.json -v
+```
+
 ## Next Steps
 
-- [Manifest Reference](/docs/schema-reference)
-- [Framework Extensions](/docs/openapi-extensions)
-- [Drupal Integration](/docs/integrations/drupal)
+- [CLI Reference](/docs/cli/run-command) - Complete command reference
+- [OpenAI Adapter](/docs/adapters/openai-adapter) - OpenAI adapter configuration
+- [Manifest Reference](/docs/schema-reference) - Full manifest schema
+- [Framework Extensions](/docs/openapi-extensions) - Extension system
+- [Migration Guides](/docs/migration-guides) - Migrate from other frameworks

package/{docs → website/content/docs}/getting-started.md

@@ -1,3 +1,7 @@
+---
+title: "Getting Started"
+---
+
 # Getting Started with OSSA
 
 ## What is OSSA?
@@ -9,7 +13,7 @@ OSSA (Open Standard for Scalable AI Agents) is a specification standard for AI a
 ## Installation
 
 ```bash
-npm install -g @bluefly/open-standards-scalable-agents
+npm install -g @bluefly/openstandardagents
 ```
 
 ## Quick Start
@@ -26,7 +30,7 @@ cd .agents/my-agent
 Edit `agent.yml`:
 
 ```yaml
-ossaVersion: "1.0"
+ossaVersion: "0.2.5-RC"
 
 agent:
   id: my-agent
@@ -75,13 +79,13 @@ OSSA doesn't dictate deployment. Deploy to YOUR infrastructure:
 
 ## Next Steps
 
-- Review [Examples](../examples/)
-- Read the [Specification](../spec/ossa-1.0.schema.json)
-- Visit the [GitLab Wiki](https://gitlab.bluefly.io/llm/openapi-ai-agents-standard/-/wikis/home)
+- Review [Examples](Examples/)
+- Read the [Specification](Specification/ossa-1.0.schema.json)
+- Visit the [GitHub Repository](https://github.com/blueflyio/openstandardagents)
 
 ## Need More Features?
 
 For production features like GitLab integration, Kubernetes deployment, and monitoring, see:
 
-**[agent-buildkit](https://gitlab.bluefly.io/llm/npm/agent-buildkit)** - Reference implementation with production tooling
+**[agent-buildkit](https://github.com/blueflyio/openstandardagents)** - Reference implementation with production tooling
 

package/website/content/docs/integrations/aiflow.md

@@ -34,7 +34,7 @@ The OpenAPI 3.1 specification defines the REST API interface for the AIFlow agen
 
 ### OSSA Schema
 
-**Location**: [OSSA/spec/v1.0/ossa-1.0.schema.json](https://github.com/blueflyio/openstandardagents/blob/development/spec/v1.0/ossa-1.0.schema.json)
+**Location**: [OSSA/spec/v0.2.5-RC/ossa-0.2.5-RC.schema.json](https://github.com/blueflyio/openstandardagents/blob/development/spec/v0.2.5-RC/ossa-0.2.5-RC.schema.json)
 
 JSON Schema definition for OSSA 1.0 manifest validation. All agent manifests must conform to this schema.
 
@@ -98,7 +98,7 @@ This generates Kubernetes manifests and deploys the agent with:
 - **AIFlow Repository**: https://github.com/AIFlow-agent/AIFlow-Agent
 - **OSSA Project**: [openapi-ai-agents-standard](https://github.com/blueflyio/openstandardagents)
 - **Integration Guide**: [agent-buildkit Wiki](https://github.com/blueflyio/openstandardagents/wiki/AIFlow-Integration-with-OSSA-BuildKit-and-K-Agent)
-- **OSSA Specification Schema**: [OSSA 1.0 Schema](https://github.com/blueflyio/openstandardagents/blob/development/spec/v1.0/ossa-1.0.schema.json)
+- **OSSA Specification Schema**: [OSSA 1.0 Schema](https://github.com/blueflyio/openstandardagents/blob/development/spec/v0.2.5-RC/ossa-0.2.5-RC.schema.json)
 - **Example Manifest**: [social-agent-aiflow.ossa.yaml](https://github.com/blueflyio/openstandardagents/blob/development/examples/aiflow-integration/social-agent-aiflow.ossa.yaml)
 - **OpenAPI Spec**: [aiflow-agent.openapi.yml](https://github.com/blueflyio/openstandardagents/blob/development/openapi/aiflow-agent.openapi.yml)
 

package/website/content/docs/integrations/drupal.md

@@ -66,7 +66,7 @@ The `ai_agents_orchestra` module enables multi-agent workflows:
 
 ```yaml
 # workflow.ossa.yaml
-apiVersion: ossa/v0.2.5
+apiVersion: ossa/v0.2.x
 kind: AgentGraph
 
 metadata:
@@ -101,5 +101,5 @@ OSSA agents work with Drupal's ECA (Event-Condition-Action):
 ## Next Steps
 
 - [OSSA Manifest Reference](/docs/schema-reference)
-- [Orchestra Module Docs](https://github.com/blueflyio/openstandardagents)
+- [Orchestra Module Docs](https://github.com/blueflyio/drupal/ai_agents_orchestra)
 - [CrewAI Integration](/docs/migration-guides/crewai-to-ossa)

package/website/content/docs/migration-guides/README.md

@@ -123,7 +123,7 @@ Starting fresh? → Check Getting Started guide
 
 Found an issue or want to add a migration guide?
 
-1. Create an issue: [GitHub Issues](https://github.com/blueflyio/openstandardagents/issues)
+1. Create an issue: [GitLab Issues](https://github.com/blueflyio/documentation/-/issues)
 2. Submit a merge request with your guide
 3. Follow the existing structure and format
 

package/website/content/docs/migration-guides/agent-schema-comparison.md

@@ -0,0 +1,232 @@
+# Agent Schema Comparison: GitLab Duo Agent vs General Agent
+
+## Overview
+
+This document compares the GitLab Duo Agent API schema with a generalized agent schema to highlight the differences, similarities, and architectural approaches.
+
+## 1. Core Agent Entity Comparison
+
+### GitLab Duo Agent (CLIAgent)
+```yaml
+CLIAgent:
+  type: object
+  properties:
+    id: string (uuid)
+    project_id: integer
+    service_account_id: string
+    service_account_username: string
+    flow_id: string (uuid)
+    status: [active, inactive, error]
+    last_invocation: string (date-time, nullable)
+    total_invocations: integer (default: 0)
+    created_at: string (date-time)
+```
+
+### General Agent
+```yaml
+Agent:
+  type: object
+  properties:
+    id: string (uuid)
+    name: string
+    description: string
+    agent_type: [cli, web, chat, workflow, autonomous]
+    status: [active, inactive, paused, error, training]
+    capabilities: array of strings
+    configuration: object (model, provider, temperature, max_tokens)
+    permissions: array of strings
+    created_at: string (date-time)
+    updated_at: string (date-time)
+    last_activity: string (date-time)
+    metadata: object
+```
+
+## 2. Key Differences
+
+### A. Scope and Purpose
+- **GitLab Duo Agent**: Highly specialized for GitLab integration, focused on CLI agents that work within GitLab projects
+- **General Agent**: Universal design for various agent types (CLI, web, chat, workflow, autonomous)
+
+### B. Integration Context
+- **GitLab Duo Agent**: 
+  - Tightly coupled with GitLab projects (`project_id`)
+  - Uses GitLab service accounts for authentication
+  - Linked to specific AI flows (`flow_id`)
+  - Designed for GitLab-specific triggers (issue comments, MR comments, epic comments)
+
+- **General Agent**:
+  - Platform-agnostic design
+  - Generic permission system
+  - Self-contained configuration
+  - Supports various trigger types (manual, scheduled, event-based, API calls, webhooks)
+
+### C. Status Management
+- **GitLab Duo Agent**: Simple 3-state system (`active`, `inactive`, `error`)
+- **General Agent**: More comprehensive 5-state system (`active`, `inactive`, `paused`, `error`, `training`)
+
+### D. Capabilities Model
+- **GitLab Duo Agent**: Implicit capabilities through flow types (code_generation, code_review, etc.)
+- **General Agent**: Explicit capabilities array with predefined skill types
+
+## 3. Execution Model Comparison
+
+### GitLab Duo Agent Execution
+```yaml
+InvokeCLIAgentRequest:
+  required:
+    - task_description
+    - trigger_context
+  properties:
+    task_description: string
+    trigger_context:
+      trigger_type: [issue_comment, merge_request_comment, epic_comment]
+      issue_iid: integer
+      merge_request_iid: integer
+      epic_id: integer
+      comment_id: integer
+      mentioned_by_user: string
+
+AgentInvocationResult:
+  properties:
+    invocation_id: string (uuid)
+    status: [accepted, running, completed, failed]
+    pipeline_id: integer (nullable)
+    response_comment_id: integer (nullable)
+    error_message: string (nullable)
+```
+
+### General Agent Execution
+```yaml
+AgentExecution:
+  properties:
+    execution_id: string (uuid)
+    agent_id: string (uuid)
+    task:
+      description: string
+      input_data: object
+      context: object
+    status: [pending, running, completed, failed, cancelled]
+    result:
+      output: string
+      artifacts: array
+      metrics: object
+    logs: array of log objects
+    started_at: string (date-time)
+    completed_at: string (date-time)
+    duration_ms: integer
+```
+
+### Key Execution Differences
+- **GitLab Duo**: Focused on GitLab-specific responses (pipeline creation, comment responses)
+- **General Agent**: Generic execution with comprehensive logging and metrics
+- **GitLab Duo**: Simpler status tracking
+- **General Agent**: More detailed execution tracking with duration and metrics
+
+## 4. Flow vs Agent Architecture
+
+### GitLab Duo: Flow-Centric Architecture
+```yaml
+AIFlow:
+  properties:
+    id: string (uuid)
+    project_id: integer
+    name: string
+    description: string
+    config_path: string
+    flow_type: [code_generation, code_review, issue_analysis, merge_request_analysis, documentation_generation, testing_assistance, custom]
+    ai_provider: [anthropic_claude, openai_codex, gitlab_managed]
+    configuration: object (model, temperature, max_tokens, use_gitlab_managed_credentials)
+    environment_variables: array
+    status: [active, inactive, error]
+    created_at: string (date-time)
+    updated_at: string (date-time)
+```
+
+### General Agent: Agent-Centric Architecture
+```yaml
+Agent:
+  # Direct agent capabilities and configuration
+  # No separate flow concept - agents contain their own capabilities
+```
+
+### Architectural Difference
+- **GitLab Duo**: Separates AI capabilities (flows) from execution agents (CLI agents)
+- **General Agent**: Combines capabilities and execution in a single agent entity
+
+## 5. Trigger System Comparison
+
+### GitLab Duo Triggers
+```yaml
+FlowTrigger:
+  properties:
+    id: string (uuid)
+    project_id: integer
+    name: string
+    service_account_id: string
+    config_path: string
+    event_types: [issue_comment_created, merge_request_comment_created, epic_comment_created]
+    status: [active, inactive]
+    created_at: string (date-time)
+```
+
+### General Agent Triggers
+```yaml
+AgentTrigger:
+  properties:
+    id: string (uuid)
+    agent_id: string (uuid)
+    name: string
+    trigger_type: [manual, scheduled, event_based, api_call, webhook]
+    event_config:
+      events: array
+      conditions: object
+    schedule:
+      cron_expression: string
+      timezone: string
+    status: [active, inactive]
+    created_at: string (date-time)
+    last_triggered: string (date-time, nullable)
+```
+
+### Trigger Differences
+- **GitLab Duo**: Limited to GitLab-specific events, project-scoped
+- **General Agent**: Universal trigger types with scheduling support
+- **GitLab Duo**: Simple event configuration
+- **General Agent**: Complex event conditions and scheduling
+
+## 6. Advanced Features
+
+### General Agent Exclusive Features
+1. **Agent Skills**: Modular capability system with input/output schemas
+2. **Agent Memory**: Memory management with different memory types and embeddings
+3. **Comprehensive Logging**: Structured logging with multiple levels
+4. **Metrics and Performance**: Execution duration and performance tracking
+5. **Metadata System**: Flexible metadata for extensibility
+
+### GitLab Duo Exclusive Features
+1. **GitLab Integration**: Deep integration with GitLab projects and service accounts
+2. **AI Gateway**: Managed AI provider credentials through GitLab
+3. **Environment Variables**: Project-specific environment variable management
+4. **Pipeline Integration**: Direct CI/CD pipeline creation and management
+
+## 7. Summary
+
+### GitLab Duo Agent Schema Strengths
+- **Specialized**: Optimized for GitLab ecosystem integration
+- **Practical**: Focused on real-world GitLab automation scenarios
+- **Integrated**: Seamless connection with GitLab authentication and authorization
+- **Production-Ready**: Designed for actual deployment in GitLab environments
+
+### General Agent Schema Strengths
+- **Universal**: Platform-agnostic design suitable for various environments
+- **Extensible**: Modular architecture with skills and memory systems
+- **Comprehensive**: Rich feature set for advanced agent capabilities
+- **Flexible**: Supports multiple agent types and execution patterns
+
+### Architectural Philosophies
+- **GitLab Duo**: "Integration-first" - designed to work seamlessly within GitLab
+- **General Agent**: "Capability-first" - designed to maximize agent functionality
+
+### Use Case Recommendations
+- **Use GitLab Duo Agent** when: Building GitLab-specific automation and AI assistants
+- **Use General Agent** when: Building universal agents that work across platforms or need advanced capabilities like memory, skills, and complex scheduling

package/website/content/docs/migration-guides/anthropic-mcp-to-ossa.md

@@ -317,7 +317,7 @@ buildkit agents create simple-agent \
 
 **2. Agent Manifest (`agent.yml`):**
 ```yaml
-ossaVersion: "1.0"
+ossaVersion: "0.2.5-RC"
 agent:
   id: simple-agent
   name: simple-agent
@@ -707,7 +707,7 @@ server.connect(transport);
 
 **Agent Manifest (`agent.yml`):**
 ```yaml
-ossaVersion: "1.0"
+ossaVersion: "0.2.5-RC"
 agent:
   id: filesystem-agent
   name: filesystem-agent
@@ -1124,7 +1124,7 @@ server.connect(transport);
 
 **Agent Manifest (`agent.yml`):**
 ```yaml
-ossaVersion: "1.0"
+ossaVersion: "0.2.5-RC"
 agent:
   id: database-agent
   name: database-agent
@@ -1462,7 +1462,7 @@ bridge:
 
 ```yaml
 # orchestrator-agent.yml
-ossaVersion: "1.0"
+ossaVersion: "0.2.5-RC"
 agent:
   id: orchestrator
   role: orchestration
@@ -1502,7 +1502,7 @@ agent:
 
 ```yaml
 # gateway-agent.yml
-ossaVersion: "1.0"
+ossaVersion: "0.2.5-RC"
 agent:
   id: mcp-gateway
   role: workflow

package/website/content/docs/migration-guides/crewai-to-ossa.md

@@ -115,7 +115,7 @@ result = crew.kickoff()
 **Orchestrator Agent** (`orchestrator.ossa.yaml`):
 
 \`\`\`yaml
-ossaVersion: "0.2.3"
+ossaVersion: "0.2.5-RC"
 agent:
   id: research-writing-orchestrator
   name: Research & Writing Orchestrator
@@ -170,7 +170,7 @@ agent:
 **Researcher Agent** (`researcher.ossa.yaml`):
 
 \`\`\`yaml
-ossaVersion: "0.2.3"
+ossaVersion: "0.2.5-RC"
 agent:
   id: ai-researcher
   name: AI Research Agent
@@ -203,7 +203,7 @@ agent:
 **Writer Agent** (`writer.ossa.yaml`):
 
 \`\`\`yaml
-ossaVersion: "0.2.3"
+ossaVersion: "0.2.5-RC"
 agent:
   id: technical-writer
   name: Technical Writer Agent