@bluefly/openstandardagents 0.2.4

package/website/content/docs/for-audiences/developers.md

@@ -0,0 +1,220 @@
+---
+title: "Developers"
+---
+
+# For Developers
+
+Build OSSA-compliant agents using your preferred framework and deploy anywhere.
+
+## Quick Start
+
+### 1. Install OSSA CLI
+
+```bash
+npm install -g @bluefly/openstandardagents
+```
+
+### 2. Generate Your First Agent
+
+```bash
+ossa generate chat --name "My Agent" --output agent.ossa.yaml
+```
+
+### 3. Validate
+
+```bash
+ossa validate agent.ossa.yaml
+```
+
+### 4. Deploy
+
+Use your preferred deployment method - OSSA doesn't care!
+
+## Development Workflow
+
+### Build with Your Framework
+
+OSSA is framework-agnostic. Build agents with:
+
+- **LangChain** - Python-based agent framework
+- **Anthropic SDK** - TypeScript/Python SDK
+- **Custom Code** - Your own implementation
+- **Any Framework** - OSSA works with all
+
+### Validate with OSSA
+
+Once built, validate against OSSA:
+
+```bash
+ossa validate my-agent.ossa.yaml
+```
+
+### Deploy Anywhere
+
+Deploy to:
+- Kubernetes
+- Docker
+- Serverless (AWS Lambda, Google Cloud Functions)
+- On-premise
+- Your infrastructure
+
+## Migration from Existing Frameworks
+
+### LangChain → OSSA
+
+See: [Migration Guide: LangChain](../Examples/Migration-Guides/from-langchain-to-ossa)
+
+### Anthropic SDK → OSSA
+
+Coming soon: Anthropic SDK migration guide
+
+### Custom Framework → OSSA
+
+1. Map your agent structure to OSSA format
+2. Define tools/capabilities
+3. Configure LLM settings
+4. Add observability
+5. Validate
+
+## API Reference
+
+### CLI Commands
+
+```bash
+# Validate agent
+ossa validate <path> [--schema <version>] [--verbose]
+
+# Generate agent
+ossa generate <type> [--name <name>] [--output <file>]
+
+# Migrate agent
+ossa migrate <source> [--target-version <version>]
+```
+
+### Programmatic API
+
+```typescript
+import { ValidationService } from '@bluefly/openstandardagents/validation';
+import { GenerationService } from '@bluefly/openstandardagents/generation';
+
+// Validate
+const validationService = new ValidationService();
+const result = await validationService.validate(manifest, '0.2.2');
+
+// Generate
+const generationService = new GenerationService();
+const manifest = await generationService.generate(template);
+```
+
+## Best Practices
+
+### 1. Use Descriptive Names
+
+```yaml
+metadata:
+  name: customer-support-agent  # Good
+  # name: agent1  # Bad
+```
+
+### 2. Add Comprehensive Descriptions
+
+```yaml
+metadata:
+  description: |
+    Customer support agent that handles:
+    - Product inquiries
+    - Order status
+    - Returns and refunds
+```
+
+### 3. Configure Constraints
+
+```yaml
+constraints:
+  cost:
+    maxTokensPerDay: 100000
+    maxCostPerDay: 10.00
+  performance:
+    maxLatencySeconds: 5.0
+```
+
+### 4. Enable Observability
+
+```yaml
+observability:
+  tracing:
+    enabled: true
+  metrics:
+    enabled: true
+  logging:
+    level: info
+```
+
+## Common Patterns
+
+### Pattern 1: Simple Chat Agent
+
+```yaml
+spec:
+  role: You are a helpful assistant
+  llm:
+    provider: openai
+    model: gpt-3.5-turbo
+  tools: []
+```
+
+### Pattern 2: Agent with Tools
+
+```yaml
+spec:
+  role: You are a research assistant
+  llm:
+    provider: openai
+    model: gpt-4
+  tools:
+    - type: http
+      name: web_search
+      endpoint: https://api.search.com/search
+```
+
+### Pattern 3: Multi-Agent Orchestration
+
+See: [Integration Patterns](../Examples/Integration-Patterns)
+
+## Testing
+
+### Validate Before Deployment
+
+```bash
+ossa validate agent.ossa.yaml --verbose
+```
+
+### Test with Examples
+
+```bash
+# Validate all examples
+npm run validate:examples
+```
+
+## Troubleshooting
+
+### Validation Errors
+
+```bash
+# Get detailed error messages
+ossa validate agent.ossa.yaml --verbose
+```
+
+### Common Issues
+
+1. **Missing required fields**: Check schema reference
+2. **Invalid tool types**: Use supported types (http, function, mcp, etc.)
+3. **LLM provider not supported**: Check provider enum values
+
+## Resources
+
+- [Getting Started](../Getting-Started/Hello-World)
+- [API Reference](../Technical/CLI-Reference)
+- [Migration Guides](../Examples/Migration-Guides)
+- [Examples](../Examples/Getting-Started-Examples)
+

package/website/content/docs/getting-started/5-minute-overview.md

@@ -0,0 +1,85 @@
+---
+title: "5 Minute Overview"
+---
+
+# 5-Minute Overview
+
+Get up to speed on OSSA in 5 minutes.
+
+## What is OSSA?
+
+**OSSA (Open Standard for Scalable Agents)** is like OpenAPI, but for AI agents.
+
+- **OpenAPI** = Standard format for REST APIs
+- **OSSA** = Standard format for AI agents
+
+## Why Does This Matter?
+
+### Before OSSA
+- Agents built with LangChain couldn't work with Anthropic SDK agents
+- Moving agents between teams required rewriting
+- No standard way to validate agent correctness
+- Framework lock-in everywhere
+
+### With OSSA
+- ✅ Agents work across any framework
+- ✅ Move agents between teams/organizations easily
+- ✅ Validate agents before deployment
+- ✅ No vendor lock-in
+
+## Core Concept
+
+OSSA defines agents using a **declarative YAML/JSON format**:
+
+```yaml
+apiVersion: ossa/v0.2.3
+kind: Agent
+
+metadata:
+  name: my-agent
+  version: 1.0.0
+  description: My first OSSA agent
+
+spec:
+  role: You are a helpful assistant
+  llm:
+    provider: openai
+    model: gpt-3.5-turbo
+  tools:
+    - type: function
+      name: greet_user
+      description: Greet a user by name
+```
+
+## Key Components
+
+| Component | What It Does |
+|-----------|--------------|
+| **Specification** | JSON Schema that defines the standard |
+| **CLI** | Validates and generates agent manifests |
+| **Examples** | Reference implementations for learning |
+| **agent-buildkit** | Reference implementation with production features |
+
+## What OSSA Is NOT
+
+- ❌ **Not a framework** - It's a standard
+- ❌ **Not a runtime** - It's a specification
+- ❌ **Not an orchestration tool** - It's a contract definition
+
+## Next Steps
+
+1. **Install OSSA CLI**: `npm install -g @bluefly/openstandardagents`
+2. **Try the Hello World example**: See [Hello World Tutorial](Hello-World)
+3. **Create your first agent**: See [First Agent Creation](First-Agent)
+4. **Explore examples**: Check out [Examples & Patterns](../Examples/Getting-Started-Examples)
+
+## Learn More
+
+- [Installation Guide](Installation)
+- [Hello World Tutorial](Hello-World)
+- [Full Documentation](../Technical/Specification-Deep-Dive)
+
+---
+
+**Time to next level**: ~15 minutes → [Hello World Tutorial](Hello-World)
+

package/website/content/docs/getting-started/Hello-World.md

@@ -0,0 +1,184 @@
+---
+title: "Hello World"
+---
+
+# Hello World Tutorial
+
+Create your first OSSA agent in 10 minutes.
+
+## Overview
+
+In this tutorial, you'll:
+1. Generate a minimal OSSA agent
+2. Understand the agent structure
+3. Validate the agent
+4. Learn what each field means
+
+## Step 1: Generate Your First Agent
+
+Use the OSSA CLI to generate a chat agent:
+
+```bash
+ossa generate chat --name "Hello World Agent" --output hello-world.ossa.yaml
+```
+
+This creates a minimal, valid OSSA agent manifest.
+
+## Step 2: Examine the Generated Agent
+
+Open `hello-world.ossa.yaml`:
+
+```yaml
+apiVersion: ossa/v0.2.3
+kind: Agent
+
+metadata:
+  name: hello-world-agent
+  version: 0.1.0
+  description: Hello World Agent
+
+spec:
+  role: |
+    You are a helpful chat assistant.
+    Answer questions clearly and concisely.
+  
+  llm:
+    provider: openai
+    model: gpt-3.5-turbo
+    temperature: 0.7
+  
+  tools: []
+```
+
+## Step 3: Understand the Structure
+
+### apiVersion & kind
+
+```yaml
+apiVersion: ossa/v0.2.3
+kind: Agent
+```
+
+- **apiVersion**: OSSA specification version
+- **kind**: Resource type (currently only "Agent")
+
+### metadata
+
+```yaml
+metadata:
+  name: hello-world-agent
+  version: 0.1.0
+  description: Hello World Agent
+```
+
+- **name**: Agent identifier (DNS-1123 format)
+- **version**: Semantic version
+- **description**: Human-readable description
+
+### spec
+
+```yaml
+spec:
+  role: |
+    You are a helpful chat assistant.
+    Answer questions clearly and concisely.
+  
+  llm:
+    provider: openai
+    model: gpt-3.5-turbo
+    temperature: 0.7
+  
+  tools: []
+```
+
+- **role**: System prompt/instructions for the agent
+- **llm**: Language model configuration
+- **tools**: Available capabilities (empty for basic chat)
+
+## Step 4: Validate Your Agent
+
+Validate the agent against the OSSA schema:
+
+```bash
+ossa validate hello-world.ossa.yaml
+```
+
+You should see:
+
+```
+✓ Agent manifest is valid OSSA 0.2.2
+```
+
+## Step 5: Add a Tool (Optional)
+
+Edit `hello-world.ossa.yaml` to add a greeting tool:
+
+```yaml
+spec:
+  role: |
+    You are a helpful chat assistant.
+    Answer questions clearly and concisely.
+  
+  llm:
+    provider: openai
+    model: gpt-3.5-turbo
+    temperature: 0.7
+  
+  tools:
+    - type: function
+      name: greet_user
+      description: Generate a personalized greeting
+      config:
+        handler: greet_handler
+```
+
+Validate again:
+
+```bash
+ossa validate hello-world.ossa.yaml
+```
+
+## Understanding the Complete Example
+
+For a fully annotated example with extensive comments, see:
+
+[examples/getting-started/hello-world-complete.ossa.yaml](https://github.com/blueflyio/openstandardagents/blob/main/examples/getting-started/hello-world-complete.ossa.yaml)
+
+This example includes:
+- Detailed comments for every field
+- All optional fields explained
+- Best practices
+- Usage examples
+
+## What You've Learned
+
+✅ OSSA agents are defined in YAML/JSON  
+✅ Agents have metadata (name, version, description)  
+✅ Agents have a spec (role, LLM, tools)  
+✅ OSSA CLI can validate agent correctness  
+✅ Tools extend agent capabilities  
+
+## Next Steps
+
+1. ✅ Hello World complete
+2. → [First Agent Creation](First-Agent) - Build a real agent
+3. → [Examples & Patterns](../Examples/Getting-Started-Examples) - See more examples
+4. → [Schema Reference](../Technical/Schema-Reference) - Deep dive into the spec
+
+## Common Questions
+
+**Q: Can I use a different LLM provider?**  
+A: Yes! OSSA supports OpenAI, Anthropic, Google, Azure, Ollama, and custom providers.
+
+**Q: What if I don't have tools?**  
+A: Tools are optional. A basic chat agent can have an empty tools array.
+
+**Q: How do I deploy this agent?**  
+A: OSSA is just a standard. Use agent-buildkit or your own deployment system.
+
+## Related
+
+- [5-Minute Overview](5-Minute-Overview)
+- [First Agent Creation](First-Agent)
+- [Complete Annotated Example](https://github.com/blueflyio/openstandardagents/blob/main/examples/getting-started/hello-world-complete.ossa.yaml)
+

package/website/content/docs/getting-started/first-agent.md

@@ -0,0 +1,196 @@
+---
+title: "First Agent"
+---
+
+# First Agent Creation
+
+Build your first real OSSA agent with capabilities.
+
+## Overview
+
+In this guide, you'll create a complete agent with:
+- Multiple tools/capabilities
+- LLM configuration
+- Observability setup
+- Constraints and limits
+
+## Step 1: Choose Your Agent Type
+
+OSSA supports various agent types:
+
+- **chat** - Conversational agent
+- **workflow** - Workflow orchestration
+- **compliance** - Compliance checking
+- **monitoring** - System monitoring
+- **worker** - Task processing
+
+For this tutorial, we'll create a **chat** agent with web search capability.
+
+## Step 2: Generate Base Agent
+
+```bash
+ossa generate chat \
+  --name "Research Assistant" \
+  --description "An agent that can search the web and answer questions" \
+  --output research-assistant.ossa.yaml
+```
+
+## Step 3: Add Tools
+
+Edit `research-assistant.ossa.yaml` to add a web search tool:
+
+```yaml
+spec:
+  role: |
+    You are a research assistant. Your job is to:
+    1. Search the web for current information
+    2. Synthesize information from multiple sources
+    3. Provide accurate, well-sourced answers
+    
+    Always cite your sources and verify information.
+  
+  llm:
+    provider: openai
+    model: gpt-4
+    temperature: 0.3  # Lower for factual accuracy
+  
+  tools:
+    - type: http
+      name: web_search
+      description: Search the web for current information
+      endpoint: https://api.search-service.com/search
+      config:
+        method: POST
+        timeout: 10
+      auth:
+        type: apikey
+        credentials: SEARCH_API_KEY
+```
+
+## Step 4: Add Observability
+
+Add observability configuration:
+
+```yaml
+spec:
+  # ... existing config ...
+  
+  observability:
+    tracing:
+      enabled: true
+      exporter: otlp
+      endpoint: http://localhost:4318
+    metrics:
+      enabled: true
+      exporter: prometheus
+      endpoint: http://localhost:9090/metrics
+    logging:
+      level: info
+      format: json
+```
+
+## Step 5: Add Constraints
+
+Add cost and performance constraints:
+
+```yaml
+spec:
+  # ... existing config ...
+  
+  constraints:
+    cost:
+      maxTokensPerDay: 100000
+      maxCostPerDay: 10.00
+      currency: USD
+    performance:
+      maxLatencySeconds: 5.0
+      maxConcurrentRequests: 10
+      timeoutSeconds: 30
+```
+
+## Step 6: Validate
+
+Validate your complete agent:
+
+```bash
+ossa validate research-assistant.ossa.yaml --verbose
+```
+
+## Complete Example
+
+Your final agent should look like:
+
+```yaml
+apiVersion: ossa/v0.2.3
+kind: Agent
+
+metadata:
+  name: research-assistant
+  version: 1.0.0
+  description: An agent that can search the web and answer questions
+  labels:
+    environment: development
+    team: research
+
+spec:
+  role: |
+    You are a research assistant. Your job is to:
+    1. Search the web for current information
+    2. Synthesize information from multiple sources
+    3. Provide accurate, well-sourced answers
+    
+    Always cite your sources and verify information.
+  
+  llm:
+    provider: openai
+    model: gpt-4
+    temperature: 0.3
+    maxTokens: 2000
+  
+  tools:
+    - type: http
+      name: web_search
+      description: Search the web for current information
+      endpoint: https://api.search-service.com/search
+      config:
+        method: POST
+        timeout: 10
+      auth:
+        type: apikey
+        credentials: SEARCH_API_KEY
+  
+  constraints:
+    cost:
+      maxTokensPerDay: 100000
+      maxCostPerDay: 10.00
+      currency: USD
+    performance:
+      maxLatencySeconds: 5.0
+      maxConcurrentRequests: 10
+  
+  observability:
+    tracing:
+      enabled: true
+      exporter: otlp
+      endpoint: http://localhost:4318
+    metrics:
+      enabled: true
+      exporter: prometheus
+    logging:
+      level: info
+      format: json
+```
+
+## Next Steps
+
+1. ✅ First agent created
+2. → [Integration Patterns](../Examples/Integration-Patterns) - Connect multiple agents
+3. → [Migration Guides](../Examples/Migration-Guides) - Migrate from other frameworks
+4. → [Advanced Patterns](../Examples/Advanced-Patterns) - Enterprise patterns
+
+## Related
+
+- [Hello World Tutorial](Hello-World)
+- [Schema Reference](../Technical/Schema-Reference)
+- [Complete Examples](../Examples/Getting-Started-Examples)
+