@bluefly/openstandardagents 0.1.9 → 0.2.5-RC

package/website/content/docs/getting-started/Installation.md

@@ -0,0 +1,155 @@
+---
+title: "Installation"
+---
+
+# Installation Guide
+
+Install OSSA CLI and get ready to create your first agent.
+
+## Prerequisites
+
+- **Node.js** 18+ (for OSSA CLI)
+- **npm** or **yarn** package manager
+- Basic familiarity with YAML/JSON
+
+## Installation Methods
+
+### Method 1: Global Installation (Recommended)
+
+Install OSSA CLI globally for use across all projects:
+
+```bash
+npm install -g @bluefly/open-standards-scalable-agents
+```
+
+Verify installation:
+
+```bash
+ossa --version
+```
+
+### Method 2: Local Installation
+
+Install in a specific project:
+
+```bash
+npm install --save-dev @bluefly/open-standards-scalable-agents
+```
+
+Use via npx:
+
+```bash
+npx ossa --version
+```
+
+### Method 3: Using agent-buildkit (Production)
+
+For production deployments with full features:
+
+```bash
+npm install -g @bluefly/agent-buildkit
+```
+
+This includes OSSA validation plus:
+- GitLab integration
+- Kubernetes deployment
+- Production monitoring
+- Compliance tooling
+
+## Verify Installation
+
+Check that OSSA CLI is working:
+
+```bash
+ossa --help
+```
+
+You should see:
+
+```
+OSSA CLI - Open Standard for Scalable Agents (The OpenAPI for AI Agents)
+
+Usage: ossa [options] [command]
+
+Options:
+  -V, --version   output the version number
+  -h, --help      display help for command
+
+Commands:
+  validate <path>  Validate OSSA agent manifest or OpenAPI spec
+  generate <type>  Generate OSSA agent manifest from template
+  migrate <source> Migrate agent manifest between OSSA versions
+  help [command]   display help for command
+```
+
+## What Gets Installed
+
+### OSSA CLI Commands
+
+- `ossa validate` - Validate agent manifests against JSON Schema
+- `ossa generate` - Generate agent manifests from templates
+- `ossa migrate` - Migrate between OSSA versions
+
+### Package Contents
+
+- **JSON Schema**: `spec/v0.2.x/ossa-0.2.x.schema.json` (see latest in `spec/v0.2.5-RC/`)
+- **TypeScript Types**: Available via package exports
+- **CLI Tool**: `bin/ossa` executable
+
+## Troubleshooting
+
+### Command Not Found
+
+If `ossa` command is not found:
+
+```bash
+# Check npm global bin path
+npm config get prefix
+
+# Add to PATH if needed
+export PATH="$(npm config get prefix)/bin:$PATH"
+```
+
+### Permission Errors
+
+On Linux/macOS, you may need sudo:
+
+```bash
+sudo npm install -g @bluefly/open-standards-scalable-agents
+```
+
+Or configure npm to use a different directory:
+
+```bash
+mkdir ~/.npm-global
+npm config set prefix '~/.npm-global'
+export PATH=~/.npm-global/bin:$PATH
+```
+
+### Version Conflicts
+
+If you have multiple versions:
+
+```bash
+# List global packages
+npm list -g --depth=0
+
+# Uninstall old version
+npm uninstall -g @bluefly/open-standards-scalable-agents
+
+# Install latest
+npm install -g @bluefly/open-standards-scalable-agents@latest
+```
+
+## Next Steps
+
+1. ✅ Installation complete
+2. → [Hello World Tutorial](Hello-World)
+3. → [First Agent Creation](First-Agent)
+
+## Related
+
+- [5-Minute Overview](5-Minute-Overview)
+- [Hello World Tutorial](Hello-World)
+- [CLI Reference](../Technical/CLI-Reference)
+

package/website/content/docs/getting-started/index.md

@@ -0,0 +1,92 @@
+---
+title: "Getting Started with OSSA"
+description: "Quick start guide for building your first OSSA agent"
+---
+
+# Getting Started with OSSA
+
+## What is OSSA?
+
+OSSA (Open Standard for Scalable Agents) is a specification standard for AI agents, similar to how OpenAPI standardizes REST APIs.
+
+**OSSA is NOT a framework** - it's a standard that defines the contract.
+
+## Installation
+
+```bash
+npm install -g @bluefly/openstandardagents
+```
+
+## Quick Start
+
+### 1. Initialize a New Agent
+
+```bash
+ossa init my-agent --type worker
+cd .agents/my-agent
+```
+
+### 2. Edit Agent Manifest
+
+Edit `agent.yml`:
+
+```yaml
+apiVersion: ossa/v{{version}}
+
+agent:
+  id: my-agent
+  name: My Agent
+  version: "1.0.0"
+  role: worker
+  
+  runtime:
+    type: docker
+    
+  capabilities:
+    - name: process_data
+      description: Process incoming data
+      input_schema:
+        type: object
+        properties:
+          data:
+            type: string
+      output_schema:
+        type: object
+        properties:
+          result:
+            type: string
+```
+
+### 3. Validate
+
+```bash
+ossa validate agent.yml
+```
+
+### 4. Deploy
+
+OSSA doesn't dictate deployment. Deploy to YOUR infrastructure:
+- Docker / Kubernetes
+- AWS / GCP / Azure
+- On-premise
+- Serverless
+
+## CLI Commands
+
+- `ossa init <name>` - Initialize new agent project
+- `ossa validate <path>` - Validate against OSSA 1.0 schema
+- `ossa generate <type>` - Generate from template
+- `ossa migrate <source>` - Migrate v0.1.9 → 1.0
+
+## Next Steps
+
+- Review [Examples](/docs/examples/migration-guides)
+- Read the [Schema Reference](/docs/schema-reference)
+- 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://github.com/blueflyio/openstandardagents)** - Reference implementation with production tooling
+

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

@@ -0,0 +1,309 @@
+---
+title: "Running Agents"
+---
+
+# Running Agents
+
+Learn how to run OSSA agents using the CLI.
+
+## Prerequisites
+
+- Node.js 18+
+- npm or yarn
+- API key for your LLM provider
+
+## Installation
+
+```bash
+npm install -g @bluefly/open-standards-scalable-agents
+```
+
+## Quick Start
+
+### 1. Set your API key
+
+```bash
+export OPENAI_API_KEY=sk-...
+```
+
+### 2. Create an agent manifest
+
+```yaml
+# support-agent.ossa.yaml
+apiVersion: ossa/v0.2.x
+kind: Agent
+
+metadata:
+  name: support-agent
+  version: 1.0.0
+  description: Customer support agent
+
+spec:
+  role: |
+    You are a helpful customer support agent.
+    Answer questions about orders and shipping.
+
+  llm:
+    provider: openai
+    model: gpt-4o-mini
+    temperature: 0.7
+```
+
+### 3. Run the agent
+
+```bash
+# Interactive mode
+ossa run support-agent.ossa.yaml
+
+# Single message
+ossa run support-agent.ossa.yaml -m "Help me track my order"
+
+# Verbose (show tool calls)
+ossa run support-agent.ossa.yaml -v
+```
+
+## Command Options
+
+| 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
+
+| Runtime | Status | Provider |
+|---------|--------|----------|
+| openai | Available | OpenAI API |
+| anthropic | Coming Soon | Anthropic Claude |
+| ollama | Coming Soon | Local LLMs |
+| gemini | Coming Soon | Google AI |
+
+## Adding Tools
+
+Define tools in your manifest using the OpenAI extension:
+
+```yaml
+extensions:
+  openai_agents:
+    tools_mapping:
+      - ossa_capability: order_tracking
+        openai_tool_name: get_order_status
+        description: Get order status by ID
+        parameters:
+          type: object
+          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
+
+- [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/website/content/docs/getting-started.md

@@ -0,0 +1,91 @@
+---
+title: "Getting Started"
+---
+
+# Getting Started with OSSA
+
+## What is OSSA?
+
+OSSA (Open Standard for Scalable AI Agents) is a specification standard for AI agents, similar to how OpenAPI standardizes REST APIs.
+
+**OSSA is NOT a framework** - it's a standard that defines the contract.
+
+## Installation
+
+```bash
+npm install -g @bluefly/openstandardagents
+```
+
+## Quick Start
+
+### 1. Initialize a New Agent
+
+```bash
+ossa init my-agent --type worker
+cd .agents/my-agent
+```
+
+### 2. Edit Agent Manifest
+
+Edit `agent.yml`:
+
+```yaml
+ossaVersion: "0.2.5-RC"
+
+agent:
+  id: my-agent
+  name: My Agent
+  version: "1.0.0"
+  role: worker
+  
+  runtime:
+    type: docker
+    
+  capabilities:
+    - name: process_data
+      description: Process incoming data
+      input_schema:
+        type: object
+        properties:
+          data:
+            type: string
+      output_schema:
+        type: object
+        properties:
+          result:
+            type: string
+```
+
+### 3. Validate
+
+```bash
+ossa validate agent.yml
+```
+
+### 4. Deploy
+
+OSSA doesn't dictate deployment. Deploy to YOUR infrastructure:
+- Docker / Kubernetes
+- AWS / GCP / Azure
+- On-premise
+- Serverless
+
+## CLI Commands
+
+- `ossa init <name>` - Initialize new agent project
+- `ossa validate <path>` - Validate against OSSA 1.0 schema
+- `ossa generate <type>` - Generate from template
+- `ossa migrate <source>` - Migrate v0.1.9 → 1.0
+
+## Next Steps
+
+- 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://github.com/blueflyio/openstandardagents)** - Reference implementation with production tooling
+