@bluefly/openstandardagents 0.2.4

package/spec/v0.2.5-dev/migrations/v0.2.4-to-v0.2.5.md

@@ -0,0 +1,317 @@
+# Migration Guide: OSSA v0.2.4 to v0.2.5-dev
+
+This guide covers migrating from OSSA v0.2.4 to v0.2.5-dev.
+
+## Overview
+
+v0.2.5-dev is a **backward-compatible** release. Existing Agent manifests will continue to work without modification. The major addition is the new `AgentGraph` resource type for multi-agent compositions.
+
+## Breaking Changes
+
+**None** - This is a fully backward-compatible release.
+
+## What's New
+
+### 1. AgentGraph Resource Type
+
+v0.2.5-dev introduces a new `kind` value: `AgentGraph`
+
+```yaml
+# Old: Single agent (still works)
+apiVersion: ossa/v0.2.4
+kind: Agent
+metadata:
+  name: my-agent
+spec:
+  role: "Agent role"
+
+# New: Multi-agent graph
+apiVersion: ossa/v0.2.5-dev
+kind: AgentGraph
+metadata:
+  name: my-agent-graph
+spec:
+  process: sequential
+  agents:
+    - ref: agent-1
+    - ref: agent-2
+```
+
+### 2. New Framework Extensions
+
+Three new framework extensions are available:
+
+- `google_adk` - Google Agent Development Kit
+- `microsoft_af` - Microsoft AutoGen/Magentic-One
+- `metagpt` - MetaGPT software teams
+
+### 3. Enhanced CrewAI Extension
+
+The `crewai` extension now includes crew-level configuration:
+
+```yaml
+extensions:
+  crewai:
+    enabled: true
+    # Existing agent properties
+    role: "Researcher"
+    goal: "Find information"
+    backstory: "Expert researcher"
+    # New crew properties
+    crew:
+      process: hierarchical
+      manager_llm: gpt-4
+      verbose: true
+```
+
+## Migration Steps
+
+### Step 1: Update API Version
+
+Update the `apiVersion` field in your manifests:
+
+```yaml
+# From
+apiVersion: ossa/v0.2.4
+
+# To
+apiVersion: ossa/v0.2.5-dev
+```
+
+### Step 2: Review Existing Manifests
+
+Existing Agent manifests require no changes. Verify they validate against the new schema:
+
+```bash
+# Validate using JSON Schema
+ajv validate -s ossa-0.2.5-dev.schema.json -d your-agent.ossa.yaml
+```
+
+### Step 3: Create AgentGraph Manifests (Optional)
+
+If you have multi-agent workflows, consider migrating them to AgentGraph:
+
+#### Before: Multiple Separate Agents
+
+```yaml
+# agent-1.ossa.yaml
+apiVersion: ossa/v0.2.4
+kind: Agent
+metadata:
+  name: intake-agent
+spec:
+  role: "Handle incoming requests"
+
+# agent-2.ossa.yaml
+apiVersion: ossa/v0.2.4
+kind: Agent
+metadata:
+  name: process-agent
+spec:
+  role: "Process requests"
+```
+
+#### After: Unified AgentGraph
+
+```yaml
+# workflow.ossa.yaml
+apiVersion: ossa/v0.2.5-dev
+kind: AgentGraph
+metadata:
+  name: request-workflow
+  description: "End-to-end request processing"
+spec:
+  process: sequential
+  agents:
+    - ref: intake-agent
+    - ref: process-agent
+  edges:
+    - from: intake-agent
+      to: process-agent
+  entry_point: intake-agent
+  exit_points:
+    - process-agent
+```
+
+## Framework-Specific Migration
+
+### CrewAI Users
+
+If you're using CrewAI's crew orchestration:
+
+```yaml
+# v0.2.4 - Agent only
+apiVersion: ossa/v0.2.4
+kind: Agent
+metadata:
+  name: researcher
+spec:
+  role: "Research specialist"
+extensions:
+  crewai:
+    enabled: true
+    role: "Researcher"
+    goal: "Find and analyze information"
+
+# v0.2.5-dev - Add AgentGraph for crew
+apiVersion: ossa/v0.2.5-dev
+kind: AgentGraph
+metadata:
+  name: research-crew
+spec:
+  process: hierarchical
+  agents:
+    - ref: researcher
+      role: worker
+    - ref: writer
+      role: worker
+extensions:
+  crewai:
+    enabled: true
+    crew:
+      process: hierarchical
+      manager_llm: gpt-4
+```
+
+### LangGraph Users
+
+If you're using LangGraph state machines:
+
+```yaml
+# Map your existing LangGraph to AgentGraph
+apiVersion: ossa/v0.2.5-dev
+kind: AgentGraph
+metadata:
+  name: state-machine
+spec:
+  process: conditional
+  agents:
+    - ref: router
+    - ref: handler-a
+    - ref: handler-b
+  edges:
+    - from: router
+      to: handler-a
+      condition: "route == 'a'"
+    - from: router
+      to: handler-b
+      condition: "route == 'b'"
+  state:
+    schema:
+      type: object
+      properties:
+        route:
+          type: string
+        messages:
+          type: array
+extensions:
+  langgraph:
+    enabled: true
+    checkpoint:
+      enabled: true
+      type: sqlite
+```
+
+### AutoGen Users
+
+For AutoGen GroupChat migrations:
+
+```yaml
+# v0.2.5-dev with Microsoft AF extension
+apiVersion: ossa/v0.2.5-dev
+kind: AgentGraph
+metadata:
+  name: autogen-team
+spec:
+  process: conditional
+  agents:
+    - ref: assistant
+    - ref: user-proxy
+    - ref: coder
+extensions:
+  microsoft_af:
+    enabled: true
+    framework: autogen_v0.4
+    team_type: selector
+    termination:
+      type: text_mention
+      condition: "TERMINATE"
+```
+
+## Validation
+
+### Schema Validation
+
+```bash
+# Install ajv-cli
+npm install -g ajv-cli
+
+# Validate Agent manifest
+ajv validate \
+  -s /path/to/ossa-0.2.5-dev.schema.json \
+  -d your-manifest.ossa.yaml
+
+# Validate with referenced agents
+ajv validate \
+  -s /path/to/ossa-0.2.5-dev.schema.json \
+  -d your-graph.ossa.yaml \
+  -r agent-1.ossa.yaml \
+  -r agent-2.ossa.yaml
+```
+
+### Runtime Validation
+
+```typescript
+// TypeScript validation
+import { validateOSSA } from '@ossa/validator';
+
+const manifest = loadYAML('workflow.ossa.yaml');
+const result = validateOSSA(manifest, '0.2.5-dev');
+
+if (!result.valid) {
+  console.error('Validation errors:', result.errors);
+}
+```
+
+## Common Issues
+
+### Issue: Schema validation fails
+
+**Cause**: Using v0.2.5-dev features with v0.2.4 schema
+
+**Solution**: Update apiVersion and use v0.2.5-dev schema
+
+### Issue: Agent refs not found
+
+**Cause**: AgentGraph references agents that don't exist
+
+**Solution**: Ensure all referenced agents are defined or use inline specs
+
+```yaml
+spec:
+  agents:
+    - ref: existing-agent  # Must exist
+    - inline:              # Or define inline
+        role: "Inline agent role"
+```
+
+### Issue: Invalid process type
+
+**Cause**: Using unsupported process value
+
+**Solution**: Use one of: sequential, parallel, hierarchical, conditional, loop
+
+## Rollback
+
+To rollback to v0.2.4:
+
+1. Change `apiVersion` back to `ossa/v0.2.4`
+2. Remove any `AgentGraph` manifests (or convert to individual Agents)
+3. Remove new extension properties (google_adk, microsoft_af, metagpt)
+4. Remove `crew` property from crewai extension
+
+## Support
+
+- Documentation: https://gitlab.bluefly.io/llm/ossa/-/wikis
+- Issues: https://gitlab.bluefly.io/llm/ossa/-/issues
+- Discussions: https://gitlab.bluefly.io/llm/ossa/-/discussions