@bluefly/openstandardagents 0.1.9 → 0.2.5-RC

package/website/content/docs/for-audiences/Students-Researchers.md

@@ -0,0 +1,122 @@
+---
+title: "Students Researchers"
+---
+
+# For Students & Researchers
+
+OSSA provides a standard format for studying, comparing, and researching AI agent architectures.
+
+## Why OSSA for Research?
+
+### Standard Format Enables Comparison
+
+Before OSSA, comparing agents across frameworks was difficult:
+- Different code structures
+- Framework-specific implementations
+- No standard metrics
+
+With OSSA:
+- ✅ Standard format enables direct comparison
+- ✅ Framework-agnostic research
+- ✅ Reproducible experiments
+- ✅ Academic paper support
+
+## Research Use Cases
+
+### 1. Agent Architecture Comparison
+
+Compare agent designs across frameworks:
+
+```yaml
+# LangChain agent → OSSA
+# Anthropic SDK agent → OSSA
+# Custom framework → OSSA
+# Compare capabilities, performance, cost
+```
+
+### 2. Multi-Agent System Research
+
+Study agent orchestration patterns:
+
+- Agent-to-agent communication
+- Workflow patterns
+- Failure recovery
+- Cost optimization
+
+### 3. Framework Migration Studies
+
+Research migration patterns:
+
+- Framework lock-in analysis
+- Portability metrics
+- Migration complexity
+- Performance impact
+
+## Academic Resources
+
+### Papers & Publications
+
+- OSSA Specification: [spec/v0.2.x/ossa-0.2.x.schema.json](https://github.com/blueflyio/openstandardagents/blob/main/spec/v0.2.5-RC/ossa-0.2.5-RC.schema.json) (latest v0.2.x schema)
+- Examples Library: [examples/](https://github.com/blueflyio/openstandardagents/tree/main/examples)
+
+### Research Questions
+
+1. **How do different LLM providers affect agent performance?**
+   - Compare OpenAI, Anthropic, Google agents in OSSA format
+   - Measure latency, cost, accuracy
+
+2. **What are optimal agent orchestration patterns?**
+   - Study multi-agent workflows
+   - Analyze failure recovery strategies
+
+3. **How does framework choice impact agent portability?**
+   - Measure migration effort
+   - Compare runtime performance
+
+## Getting Started for Research
+
+### Step 1: Understand the Standard
+
+Read the specification:
+- [Specification Deep-Dive](../Technical/Specification-Deep-Dive)
+- [Schema Reference](../Technical/Schema-Reference)
+
+### Step 2: Study Examples
+
+Review annotated examples:
+- [Hello World Complete](https://github.com/blueflyio/openstandardagents/blob/main/examples/getting-started/hello-world-complete.ossa.yaml)
+- [Integration Patterns](../Examples/Integration-Patterns)
+
+### Step 3: Create Research Agents
+
+Generate agents for your research:
+
+```bash
+ossa generate chat --name "research-agent-1"
+ossa generate workflow --name "research-agent-2"
+```
+
+### Step 4: Compare & Analyze
+
+Use OSSA format to:
+- Compare agent designs
+- Measure performance
+- Analyze costs
+- Study patterns
+
+## Contributing Research
+
+We welcome research contributions:
+
+1. **Case Studies**: Document your research findings
+2. **Pattern Analysis**: Share discovered patterns
+3. **Performance Studies**: Contribute benchmarks
+4. **Academic Papers**: Reference OSSA in publications
+
+## Related Resources
+
+- [Getting Started](../Getting-Started/5-Minute-Overview)
+- [Technical Documentation](../Technical/Specification-Deep-Dive)
+- [Examples & Patterns](../Examples/Getting-Started-Examples)
+- [Repository](https://github.com/blueflyio/openstandardagents)
+

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.x
+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/open-standards-scalable-agents`
+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/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.x
+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)
+

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.x
+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.x
+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 v0.2.x
+```
+
+## 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)
+