@bluefly/openstandardagents 0.2.7 → 0.2.9

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

@@ -1,2075 +0,0 @@
----
-title: "Langflow to OSSA"
----
-
-# Langflow to OSSA Migration Guide
-
-**Version:** 1.0
-**Last Updated:** 2025-11-10
-**Status:** Production Ready
-
----
-
-## Table of Contents
-
-1. [Overview](#overview)
-2. [Key Concepts Mapping](#key-concepts-mapping)
-3. [Architecture Comparison](#architecture-comparison)
-4. [Migration Strategy](#migration-strategy)
-5. [Component Mapping Reference](#component-mapping-reference)
-6. [Migration Examples](#migration-examples)
-7. [Advanced Patterns](#advanced-patterns)
-8. [Testing & Validation](#testing--validation)
-9. [Best Practices](#best-practices)
-10. [Troubleshooting](#troubleshooting)
-
----
-
-## Overview
-
-This guide provides a comprehensive methodology for migrating from Langflow's visual flow-based architecture to OSSA (Open Standards for Scalable Agents). While Langflow excels at rapid prototyping with visual workflows, OSSA provides production-grade agent orchestration with enhanced interoperability, type safety, and enterprise features.
-
-### Why Migrate to OSSA?
-
-- **Production-Ready Infrastructure**: Built-in monitoring, metrics, and compliance
-- **Multi-Protocol Support**: HTTP, gRPC, WebSocket, stdio, A2A protocol bridges
-- **Framework Interoperability**: Works with LangChain, CrewAI, AutoGen, and MCP
-- **Type Safety**: Full JSON Schema validation and TypeScript definitions
-- **Enterprise Features**: RBAC, encryption, audit logging, compliance frameworks
-- **Cloud-Native**: Kubernetes-ready with resource management and auto-scaling
-- **Version Control Friendly**: YAML-based configuration vs. JSON blobs
-
-### Migration Effort Estimation
-
-| Flow Complexity | Estimated Time | Difficulty |
-|----------------|----------------|------------|
-| Simple (1-5 nodes) | 30-60 minutes | Easy |
-| Medium (6-15 nodes) | 2-4 hours | Moderate |
-| Complex (16+ nodes) | 4-8 hours | Advanced |
-| Multi-flow systems | 1-2 days | Advanced |
-
----
-
-## Key Concepts Mapping
-
-### Langflow → OSSA Terminology
-
-| Langflow Concept | OSSA Equivalent | Description |
-|-----------------|-----------------|-------------|
-| **Flow** | **Agent Workflow** | Complete end-to-end process |
-| **Node** | **Capability Operation** | Individual processing unit |
-| **Edge** | **Workflow Step Connection** | Data flow between operations |
-| **Component** | **Agent Capability** | Reusable functionality |
-| **Input/Output** | **Input/Output Schema** | Data contracts with JSON Schema |
-| **Template** | **Agent Manifest** | Configuration specification |
-| **Variable** | **Environment Variable** | Runtime configuration |
-| **API Key** | **Authentication Config** | Security credentials |
-| **Prompt Template** | **LLM Configuration** | Model interaction setup |
-| **Memory** | **Context Management** | State persistence |
-
-### Data Flow Models
-
-**Langflow (Node-Edge Graph)**:
-```
-ChatInput → PromptTemplate → OpenAI → ChatOutput
-   ↓              ↓              ↓          ↓
- User Msg    Format Prompt   Generate    Display
-```
-
-**OSSA (Capability-Based Workflow)**:
-```yaml
-capabilities:
-  - accept_input      # ChatInput
-  - format_prompt     # PromptTemplate
-  - llm_generation    # OpenAI
-  - return_output     # ChatOutput
-
-workflow:
-  steps:
-    - accept_input → format_prompt
-    - format_prompt → llm_generation
-    - llm_generation → return_output
-```
-
----
-
-## Architecture Comparison
-
-### Langflow Architecture
-
-```
-┌─────────────────────────────────────┐
-│      Visual Flow Builder (UI)       │
-├─────────────────────────────────────┤
-│  Nodes (Components) + Edges (Flows) │
-├─────────────────────────────────────┤
-│      Langflow Runtime Engine        │
-├─────────────────────────────────────┤
-│    Python Execution Environment     │
-└─────────────────────────────────────┘
-```
-
-**Characteristics**:
-- Visual-first design
-- Python-centric execution
-- JSON export format
-- Single runtime model
-- Limited interoperability
-
-### OSSA Architecture
-
-```
-┌─────────────────────────────────────┐
-│    Agent Manifest (YAML Config)     │
-├─────────────────────────────────────┤
-│  Capabilities + Operations + Schema │
-├─────────────────────────────────────┤
-│   Protocol Bridges (MCP/HTTP/A2A)   │
-├─────────────────────────────────────┤
-│ Multi-Runtime (Local/K8s/Serverless)│
-├─────────────────────────────────────┤
-│  Monitoring + Metrics + Compliance   │
-└─────────────────────────────────────┘
-```
-
-**Characteristics**:
-- Code and config as infrastructure
-- Multi-language support (TypeScript, Python, Go, etc.)
-- YAML manifest format
-- Multiple deployment targets
-- Universal interoperability via bridges
-
----
-
-## Migration Strategy
-
-### Phase 1: Analysis & Planning
-
-#### 1.1 Export Langflow Configuration
-
-```bash
-# From Langflow UI
-1. Open your flow
-2. Click "Export" button
-3. Select "Save with my API keys" (optional)
-4. Save as FLOW_NAME.json
-```
-
-#### 1.2 Analyze Flow Structure
-
-```bash
-# Use jq to inspect flow structure
-jq '.data.nodes[] | {id: .id, type: .data.type, display_name: .data.node.display_name}' flow.json
-
-# Count components
-jq '.data.nodes | length' flow.json
-
-# List edges (connections)
-jq '.data.edges[] | {source: .source, target: .target}' flow.json
-```
-
-#### 1.3 Identify Migration Patterns
-
-- **Sequential Processing**: Linear node chains → Workflow steps
-- **Conditional Logic**: Switch nodes → Conditional capabilities
-- **Parallel Processing**: Multiple edge branches → Parallel execution
-- **Memory/State**: Context nodes → Context management
-- **API Integrations**: HTTP nodes → Integration endpoints
-
-### Phase 2: Component Mapping
-
-#### 2.1 Create Capability Inventory
-
-Map each unique Langflow node type to OSSA capabilities:
-
-```yaml
-# Example mapping table
-langflow_components:
-  ChatInput: { ossa_capability: "accept_user_input", category: "input" }
-  PromptTemplate: { ossa_capability: "format_prompt", category: "processing" }
-  OpenAI: { ossa_capability: "llm_generation", category: "ai" }
-  ConversationChain: { ossa_capability: "conversation_management", category: "ai" }
-  ChatOutput: { ossa_capability: "return_response", category: "output" }
-  VectorStore: { ossa_capability: "vector_storage", category: "storage" }
-  Retriever: { ossa_capability: "semantic_search", category: "retrieval" }
-```
-
-#### 2.2 Define JSON Schemas
-
-For each capability, create input/output schemas:
-
-```yaml
-capabilities:
-  - name: format_prompt
-    description: "Format user input into LLM prompt"
-    input_schema:
-      type: object
-      required: ["user_message", "template"]
-      properties:
-        user_message:
-          type: string
-          description: "User's input message"
-        template:
-          type: string
-          description: "Prompt template with placeholders"
-        variables:
-          type: object
-          description: "Template variable values"
-    output_schema:
-      type: object
-      required: ["formatted_prompt"]
-      properties:
-        formatted_prompt:
-          type: string
-          description: "Fully formatted prompt ready for LLM"
-```
-
-### Phase 3: OSSA Manifest Creation
-
-#### 3.1 Base Agent Structure
-
-```yaml
-apiVersion: ossa/v1
-kind: Agent
-metadata:
-  name: migrated-chatbot-agent
-  version: 1.0.0
-  description: "Migrated from Langflow chatbot flow"
-  labels:
-    migration_source: langflow
-    original_flow: chatbot-v1
-    created_date: "2025-11-10"
-
-spec:
-  role: workflow
-
-  runtime:
-    type: local
-    command: [node, dist/index.js]
-    resources:
-      cpu: 500m
-      memory: 512Mi
-
-  capabilities:
-    # Define all capabilities from mapping
-
-  integration:
-    protocol: http
-    endpoints:
-      base_url: http://localhost:3000
-      execute: /api/v1/execute
-    authentication:
-      type: api-key
-
-  monitoring:
-    traces: true
-    metrics: true
-    logs: true
-```
-
-### Phase 4: Implementation
-
-#### 4.1 Generate Agent Scaffold
-
-```bash
-# Use BuildKit to create agent structure
-buildkit agents create \
-  --name migrated-chatbot-agent \
-  --type workflow \
-  --capabilities "accept_input,format_prompt,llm_generation,return_response" \
-  --enable-mcp \
-  --interactive
-```
-
-#### 4.2 Implement Capability Handlers
-
-```typescript
-// src/capabilities/format-prompt.ts
-import { CapabilityHandler } from '@ossa/agent-sdk';
-
-export const formatPromptHandler: CapabilityHandler = async (input, context) => {
-  const { user_message, template, variables } = input;
-
-  // Replace template placeholders
-  let formatted_prompt = template;
-  for (const [key, value] of Object.entries(variables || {})) {
-    formatted_prompt = formatted_prompt.replace(`{${key}}`, value);
-  }
-  formatted_prompt = formatted_prompt.replace('{user_input}', user_message);
-
-  return { formatted_prompt };
-};
-```
-
-### Phase 5: Testing & Validation
-
-```bash
-# Validate agent manifest
-buildkit agents validate ./migrated-chatbot-agent.yaml
-
-# Test individual capabilities
-buildkit agents test \
-  --name migrated-chatbot-agent \
-  --capability format_prompt \
-  --input '{"user_message": "Hello", "template": "User said: {user_input}"}'
-
-# Integration test
-buildkit agents deploy --name migrated-chatbot-agent --env dev
-curl -X POST http://localhost:3000/api/v1/execute \
-  -H "Content-Type: application/json" \
-  -d '{"operation": "process_conversation", "input": {"message": "Hello world"}}'
-```
-
----
-
-## Component Mapping Reference
-
-### Input Components
-
-| Langflow Component | OSSA Capability Pattern | Notes |
-|-------------------|------------------------|-------|
-| `ChatInput` | `accept_user_input` | HTTP endpoint or stdio |
-| `TextInput` | `accept_text_input` | Structured text input |
-| `File` | `accept_file_upload` | File handling capability |
-| `URLInput` | `fetch_url_content` | Web scraping capability |
-
-### Processing Components
-
-| Langflow Component | OSSA Capability Pattern | Notes |
-|-------------------|------------------------|-------|
-| `PromptTemplate` | `format_prompt` | Template string processing |
-| `TextSplitter` | `split_text` | Chunking logic |
-| `CharacterTextSplitter` | `split_by_character` | Character-based splitting |
-| `RecursiveCharacterTextSplitter` | `recursive_split` | Recursive chunking |
-| `PythonFunction` | `execute_custom_logic` | Custom code execution |
-| `ConditionalRouter` | `route_conditionally` | Conditional branching |
-
-### AI/LLM Components
-
-| Langflow Component | OSSA Capability Pattern | Notes |
-|-------------------|------------------------|-------|
-| `OpenAI` | `openai_completion` | LLM generation |
-| `ChatOpenAI` | `openai_chat` | Chat completion |
-| `Anthropic` | `anthropic_completion` | Claude integration |
-| `HuggingFace` | `huggingface_inference` | HF models |
-| `Ollama` | `ollama_inference` | Local LLM |
-| `ConversationChain` | `conversation_management` | Stateful conversation |
-| `LLMChain` | `llm_chain_execution` | Chain processing |
-
-### Vector Store Components
-
-| Langflow Component | OSSA Capability Pattern | Notes |
-|-------------------|------------------------|-------|
-| `Chroma` | `chroma_vector_store` | Chroma DB integration |
-| `Pinecone` | `pinecone_vector_store` | Pinecone integration |
-| `FAISS` | `faiss_vector_store` | Local vector DB |
-| `Qdrant` | `qdrant_vector_store` | Qdrant integration |
-| `Weaviate` | `weaviate_vector_store` | Weaviate integration |
-
-### Retrieval Components
-
-| Langflow Component | OSSA Capability Pattern | Notes |
-|-------------------|------------------------|-------|
-| `VectorStoreRetriever` | `semantic_search` | Vector similarity search |
-| `MultiQueryRetriever` | `multi_query_search` | Query expansion |
-| `ContextualCompressionRetriever` | `compressed_retrieval` | Result compression |
-
-### Memory Components
-
-| Langflow Component | OSSA Capability Pattern | Notes |
-|-------------------|------------------------|-------|
-| `ConversationBufferMemory` | `buffer_memory_management` | Full history storage |
-| `ConversationSummaryMemory` | `summary_memory_management` | Summarized history |
-| `ConversationBufferWindowMemory` | `window_memory_management` | Sliding window |
-
-### Output Components
-
-| Langflow Component | OSSA Capability Pattern | Notes |
-|-------------------|------------------------|-------|
-| `ChatOutput` | `return_chat_response` | Chat response |
-| `TextOutput` | `return_text_output` | Plain text output |
-| `JSONOutput` | `return_json_output` | Structured JSON |
-
----
-
-## Migration Examples
-
-### Example 1: Simple Chatbot Flow
-
-#### Langflow JSON Export
-
-```json
-{
-  "data": {
-    "nodes": [
-      {
-        "id": "ChatInput-abc123",
-        "type": "ChatInput",
-        "position": { "x": 100, "y": 100 },
-        "data": {
-          "node": {
-            "display_name": "Chat Input",
-            "description": "Accept user messages",
-            "template": {
-              "input_value": {
-                "type": "str",
-                "required": true,
-                "placeholder": "Enter your message"
-              }
-            }
-          }
-        }
-      },
-      {
-        "id": "PromptTemplate-def456",
-        "type": "PromptTemplate",
-        "position": { "x": 300, "y": 100 },
-        "data": {
-          "node": {
-            "display_name": "Prompt Formatter",
-            "template": {
-              "template": {
-                "type": "str",
-                "value": "You are a helpful assistant. User: {user_input}\nAssistant:"
-              }
-            }
-          }
-        }
-      },
-      {
-        "id": "OpenAI-ghi789",
-        "type": "ChatOpenAI",
-        "position": { "x": 500, "y": 100 },
-        "data": {
-          "node": {
-            "display_name": "OpenAI GPT-4",
-            "template": {
-              "model_name": {
-                "value": "gpt-4"
-              },
-              "temperature": {
-                "value": 0.7
-              },
-              "max_tokens": {
-                "value": 500
-              }
-            }
-          }
-        }
-      },
-      {
-        "id": "ChatOutput-jkl012",
-        "type": "ChatOutput",
-        "position": { "x": 700, "y": 100 },
-        "data": {
-          "node": {
-            "display_name": "Chat Output",
-            "description": "Display response to user"
-          }
-        }
-      }
-    ],
-    "edges": [
-      {
-        "id": "edge-1",
-        "source": "ChatInput-abc123",
-        "target": "PromptTemplate-def456",
-        "sourceHandle": "output",
-        "targetHandle": "user_input"
-      },
-      {
-        "id": "edge-2",
-        "source": "PromptTemplate-def456",
-        "target": "OpenAI-ghi789",
-        "sourceHandle": "prompt",
-        "targetHandle": "messages"
-      },
-      {
-        "id": "edge-3",
-        "source": "OpenAI-ghi789",
-        "target": "ChatOutput-jkl012",
-        "sourceHandle": "response",
-        "targetHandle": "input"
-      }
-    ]
-  },
-  "description": "Simple chatbot with OpenAI",
-  "name": "Simple Chatbot"
-}
-```
-
-#### OSSA YAML Manifest
-
-```yaml
-apiVersion: ossa/v1
-kind: Agent
-metadata:
-  name: simple-chatbot
-  version: 1.0.0
-  description: "Simple chatbot with OpenAI - migrated from Langflow"
-  labels:
-    migration_source: langflow
-    original_flow: simple-chatbot
-  annotations:
-    langflow.original_nodes: "4"
-    langflow.original_edges: "3"
-
-spec:
-  role: workflow
-
-  # LLM Configuration (from OpenAI node)
-  llm:
-    provider: openai
-    model: gpt-4
-    temperature: 0.7
-    maxTokens: 500
-
-  # Capabilities (mapped from nodes)
-  capabilities:
-    - name: accept_chat_input
-      description: "Accept user messages (from ChatInput node)"
-      input_schema:
-        type: object
-        required: ["message"]
-        properties:
-          message:
-            type: string
-            description: "User's chat message"
-      output_schema:
-        type: object
-        properties:
-          user_message:
-            type: string
-
-    - name: format_prompt
-      description: "Format message into LLM prompt (from PromptTemplate node)"
-      input_schema:
-        type: object
-        required: ["user_input"]
-        properties:
-          user_input:
-            type: string
-      output_schema:
-        type: object
-        properties:
-          formatted_prompt:
-            type: string
-
-    - name: generate_response
-      description: "Generate AI response (from ChatOpenAI node)"
-      input_schema:
-        type: object
-        required: ["prompt"]
-        properties:
-          prompt:
-            type: string
-      output_schema:
-        type: object
-        properties:
-          response:
-            type: string
-            description: "AI-generated response"
-
-    - name: return_response
-      description: "Return chat response (from ChatOutput node)"
-      input_schema:
-        type: object
-        required: ["response"]
-        properties:
-          response:
-            type: string
-      output_schema:
-        type: object
-        properties:
-          output:
-            type: string
-
-  # Runtime Configuration
-  runtime:
-    type: local
-    command: [node, dist/index.js]
-    environment:
-      OPENAI_API_KEY: ${OPENAI_API_KEY}
-      NODE_ENV: production
-    resources:
-      cpu: 500m
-      memory: 512Mi
-
-  # Integration Protocol
-  integration:
-    protocol: http
-    endpoints:
-      base_url: http://localhost:3000
-      execute: /api/v1/chat
-      health: /health
-      metrics: /metrics
-    authentication:
-      type: api-key
-      config:
-        header: X-API-Key
-
-  # Monitoring
-  monitoring:
-    traces: true
-    metrics: true
-    logs: true
-    alerts:
-      - type: error_rate
-        threshold: 0.05
-        action: notify
-
-  # Policies
-  policies:
-    encryption: true
-    audit: true
-    compliance:
-      - ISO42001
-      - SOC2
-```
-
-#### Implementation Code
-
-```typescript
-// src/index.ts
-import { OSSAAgent, CapabilityHandler } from '@ossa/agent-sdk';
-import OpenAI from 'openai';
-
-const openai = new OpenAI({
-  apiKey: process.env.OPENAI_API_KEY,
-});
-
-// Capability: accept_chat_input
-const acceptChatInput: CapabilityHandler = async (input) => {
-  return { user_message: input.message };
-};
-
-// Capability: format_prompt
-const formatPrompt: CapabilityHandler = async (input) => {
-  const template = "You are a helpful assistant. User: {user_input}\nAssistant:";
-  const formatted_prompt = template.replace('{user_input}', input.user_input);
-  return { formatted_prompt };
-};
-
-// Capability: generate_response
-const generateResponse: CapabilityHandler = async (input) => {
-  const completion = await openai.chat.completions.create({
-    model: 'gpt-4',
-    messages: [{ role: 'user', content: input.prompt }],
-    temperature: 0.7,
-    max_tokens: 500,
-  });
-  return { response: completion.choices[0].message.content };
-};
-
-// Capability: return_response
-const returnResponse: CapabilityHandler = async (input) => {
-  return { output: input.response };
-};
-
-// Agent initialization
-const agent = new OSSAAgent({
-  manifestPath: './simple-chatbot.yaml',
-  capabilities: {
-    accept_chat_input: acceptChatInput,
-    format_prompt: formatPrompt,
-    generate_response: generateResponse,
-    return_response: returnResponse,
-  },
-});
-
-// Workflow orchestration
-agent.defineWorkflow('chat', async (input) => {
-  const step1 = await agent.execute('accept_chat_input', { message: input.message });
-  const step2 = await agent.execute('format_prompt', { user_input: step1.user_message });
-  const step3 = await agent.execute('generate_response', { prompt: step2.formatted_prompt });
-  const step4 = await agent.execute('return_response', { response: step3.response });
-  return step4.output;
-});
-
-agent.start();
-```
-
----
-
-### Example 2: RAG System with Vector Store
-
-#### Langflow JSON Export
-
-```json
-{
-  "data": {
-    "nodes": [
-      {
-        "id": "TextInput-rag001",
-        "type": "TextInput",
-        "data": {
-          "node": {
-            "display_name": "User Query",
-            "template": {
-              "input_value": { "type": "str" }
-            }
-          }
-        }
-      },
-      {
-        "id": "Embeddings-rag002",
-        "type": "OpenAIEmbeddings",
-        "data": {
-          "node": {
-            "display_name": "Query Embeddings",
-            "template": {
-              "model": { "value": "text-embedding-3-small" }
-            }
-          }
-        }
-      },
-      {
-        "id": "VectorStore-rag003",
-        "type": "Qdrant",
-        "data": {
-          "node": {
-            "display_name": "Vector Database",
-            "template": {
-              "collection_name": { "value": "knowledge_base" },
-              "url": { "value": "http://localhost:6333" }
-            }
-          }
-        }
-      },
-      {
-        "id": "Retriever-rag004",
-        "type": "VectorStoreRetriever",
-        "data": {
-          "node": {
-            "display_name": "Semantic Search",
-            "template": {
-              "search_type": { "value": "similarity" },
-              "k": { "value": 5 }
-            }
-          }
-        }
-      },
-      {
-        "id": "PromptTemplate-rag005",
-        "type": "PromptTemplate",
-        "data": {
-          "node": {
-            "template": {
-              "template": {
-                "value": "Context: {context}\n\nQuestion: {question}\n\nAnswer based on context:"
-              }
-            }
-          }
-        }
-      },
-      {
-        "id": "LLM-rag006",
-        "type": "ChatOpenAI",
-        "data": {
-          "node": {
-            "template": {
-              "model_name": { "value": "gpt-4" },
-              "temperature": { "value": 0.3 }
-            }
-          }
-        }
-      },
-      {
-        "id": "Output-rag007",
-        "type": "TextOutput",
-        "data": {
-          "node": { "display_name": "Final Answer" }
-        }
-      }
-    ],
-    "edges": [
-      {
-        "source": "TextInput-rag001",
-        "target": "Embeddings-rag002"
-      },
-      {
-        "source": "Embeddings-rag002",
-        "target": "VectorStore-rag003"
-      },
-      {
-        "source": "VectorStore-rag003",
-        "target": "Retriever-rag004"
-      },
-      {
-        "source": "Retriever-rag004",
-        "target": "PromptTemplate-rag005",
-        "sourceHandle": "documents",
-        "targetHandle": "context"
-      },
-      {
-        "source": "TextInput-rag001",
-        "target": "PromptTemplate-rag005",
-        "targetHandle": "question"
-      },
-      {
-        "source": "PromptTemplate-rag005",
-        "target": "LLM-rag006"
-      },
-      {
-        "source": "LLM-rag006",
-        "target": "Output-rag007"
-      }
-    ]
-  },
-  "name": "RAG Knowledge Base",
-  "description": "RAG system with Qdrant vector store"
-}
-```
-
-#### OSSA YAML Manifest
-
-```yaml
-apiVersion: ossa/v1
-kind: Agent
-metadata:
-  name: rag-knowledge-base
-  version: 1.0.0
-  description: "RAG system with vector store - migrated from Langflow"
-  labels:
-    migration_source: langflow
-    pattern: retrieval-augmented-generation
-    vector_db: qdrant
-
-spec:
-  role: workflow
-
-  # LLM Configuration
-  llm:
-    provider: openai
-    model: gpt-4
-    temperature: 0.3
-    maxTokens: 1000
-
-  # Capabilities
-  capabilities:
-    - name: accept_query
-      description: "Accept user query"
-      input_schema:
-        type: object
-        required: ["question"]
-        properties:
-          question:
-            type: string
-            description: "User's question"
-      output_schema:
-        type: object
-        properties:
-          query:
-            type: string
-
-    - name: generate_embeddings
-      description: "Generate query embeddings"
-      input_schema:
-        type: object
-        required: ["text"]
-        properties:
-          text:
-            type: string
-      output_schema:
-        type: object
-        properties:
-          embeddings:
-            type: array
-            items:
-              type: number
-
-    - name: vector_search
-      description: "Search vector database"
-      input_schema:
-        type: object
-        required: ["embeddings", "k"]
-        properties:
-          embeddings:
-            type: array
-            items:
-              type: number
-          k:
-            type: integer
-            default: 5
-            description: "Number of results to return"
-          collection:
-            type: string
-            default: "knowledge_base"
-      output_schema:
-        type: object
-        properties:
-          documents:
-            type: array
-            items:
-              type: object
-              properties:
-                content:
-                  type: string
-                score:
-                  type: number
-                metadata:
-                  type: object
-
-    - name: format_rag_prompt
-      description: "Format RAG prompt with context"
-      input_schema:
-        type: object
-        required: ["question", "documents"]
-        properties:
-          question:
-            type: string
-          documents:
-            type: array
-            items:
-              type: object
-      output_schema:
-        type: object
-        properties:
-          prompt:
-            type: string
-
-    - name: generate_answer
-      description: "Generate contextual answer"
-      input_schema:
-        type: object
-        required: ["prompt"]
-        properties:
-          prompt:
-            type: string
-      output_schema:
-        type: object
-        properties:
-          answer:
-            type: string
-            description: "Generated answer with citations"
-
-  # Runtime Configuration
-  runtime:
-    type: docker
-    image: ossa/rag-agent:1.0.0
-    environment:
-      OPENAI_API_KEY: ${OPENAI_API_KEY}
-      QDRANT_URL: http://qdrant:6333
-      QDRANT_API_KEY: ${QDRANT_API_KEY}
-      EMBEDDING_MODEL: text-embedding-3-small
-    resources:
-      cpu: 1000m
-      memory: 1Gi
-
-  # Integration
-  integration:
-    protocol: http
-    endpoints:
-      base_url: http://localhost:3000
-      execute: /api/v1/query
-      health: /health
-    authentication:
-      type: bearer
-      config:
-        token_env: API_TOKEN
-
-  # External Integrations
-  dependencies:
-    - name: qdrant
-      type: vector_database
-      endpoint: http://qdrant:6333
-      authentication:
-        type: api-key
-    - name: openai
-      type: llm_provider
-      endpoint: https://api.openai.com/v1
-
-  # Monitoring
-  monitoring:
-    traces: true
-    metrics: true
-    logs: true
-    custom_metrics:
-      - name: retrieval_latency_ms
-        type: histogram
-      - name: embedding_generation_time_ms
-        type: histogram
-      - name: documents_retrieved
-        type: gauge
-
-  # Performance
-  performance:
-    throughput:
-      requestsPerSecond: 20
-      concurrentRequests: 5
-    latency:
-      p50: 2000
-      p95: 5000
-      p99: 8000
-```
-
-#### Implementation Code
-
-```typescript
-// src/index.ts
-import { OSSAAgent } from '@ossa/agent-sdk';
-import OpenAI from 'openai';
-import { QdrantClient } from '@qdrant/js-client-rest';
-
-const openai = new OpenAI({ apiKey: process.env.OPENAI_API_KEY });
-const qdrant = new QdrantClient({ url: process.env.QDRANT_URL });
-
-const agent = new OSSAAgent({ manifestPath: './rag-knowledge-base.yaml' });
-
-// Capability: accept_query
-agent.registerCapability('accept_query', async (input) => {
-  return { query: input.question };
-});
-
-// Capability: generate_embeddings
-agent.registerCapability('generate_embeddings', async (input) => {
-  const response = await openai.embeddings.create({
-    model: 'text-embedding-3-small',
-    input: input.text,
-  });
-  return { embeddings: response.data[0].embedding };
-});
-
-// Capability: vector_search
-agent.registerCapability('vector_search', async (input) => {
-  const results = await qdrant.search(input.collection || 'knowledge_base', {
-    vector: input.embeddings,
-    limit: input.k || 5,
-    with_payload: true,
-  });
-
-  const documents = results.map(result => ({
-    content: result.payload?.text || '',
-    score: result.score,
-    metadata: result.payload || {},
-  }));
-
-  return { documents };
-});
-
-// Capability: format_rag_prompt
-agent.registerCapability('format_rag_prompt', async (input) => {
-  const context = input.documents
-    .map((doc: any) => doc.content)
-    .join('\n\n');
-
-  const prompt = `Context: ${context}\n\nQuestion: ${input.question}\n\nAnswer based on context:`;
-  return { prompt };
-});
-
-// Capability: generate_answer
-agent.registerCapability('generate_answer', async (input) => {
-  const completion = await openai.chat.completions.create({
-    model: 'gpt-4',
-    messages: [{ role: 'user', content: input.prompt }],
-    temperature: 0.3,
-    max_tokens: 1000,
-  });
-
-  return { answer: completion.choices[0].message.content };
-});
-
-// Workflow: RAG query processing
-agent.defineWorkflow('rag_query', async (input) => {
-  // Step 1: Accept and validate query
-  const { query } = await agent.execute('accept_query', { question: input.question });
-
-  // Step 2: Generate embeddings
-  const { embeddings } = await agent.execute('generate_embeddings', { text: query });
-
-  // Step 3: Search vector database
-  const { documents } = await agent.execute('vector_search', {
-    embeddings,
-    k: input.k || 5,
-    collection: input.collection || 'knowledge_base'
-  });
-
-  // Step 4: Format RAG prompt
-  const { prompt } = await agent.execute('format_rag_prompt', {
-    question: query,
-    documents
-  });
-
-  // Step 5: Generate answer
-  const { answer } = await agent.execute('generate_answer', { prompt });
-
-  return {
-    answer,
-    sources: documents,
-    metadata: {
-      query,
-      num_sources: documents.length,
-      timestamp: new Date().toISOString(),
-    }
-  };
-});
-
-agent.start();
-```
-
----
-
-### Example 3: Multi-Agent Workflow with Conditional Routing
-
-#### Langflow JSON Export
-
-```json
-{
-  "data": {
-    "nodes": [
-      {
-        "id": "Input-multi001",
-        "type": "ChatInput",
-        "data": {
-          "node": {
-            "display_name": "User Request"
-          }
-        }
-      },
-      {
-        "id": "Classifier-multi002",
-        "type": "ChatOpenAI",
-        "data": {
-          "node": {
-            "display_name": "Intent Classifier",
-            "template": {
-              "system_message": {
-                "value": "Classify user intent: QUESTION, CODE_HELP, or GENERAL_CHAT"
-              }
-            }
-          }
-        }
-      },
-      {
-        "id": "Router-multi003",
-        "type": "ConditionalRouter",
-        "data": {
-          "node": {
-            "display_name": "Route by Intent",
-            "template": {
-              "rules": [
-                { "condition": "intent == 'QUESTION'", "route": "qa_agent" },
-                { "condition": "intent == 'CODE_HELP'", "route": "code_agent" },
-                { "condition": "intent == 'GENERAL_CHAT'", "route": "chat_agent" }
-              ]
-            }
-          }
-        }
-      },
-      {
-        "id": "QAAgent-multi004",
-        "type": "ConversationChain",
-        "data": {
-          "node": {
-            "display_name": "Q&A Specialist",
-            "template": {
-              "llm": { "value": "gpt-4" },
-              "system_message": { "value": "You are a Q&A expert." }
-            }
-          }
-        }
-      },
-      {
-        "id": "CodeAgent-multi005",
-        "type": "ConversationChain",
-        "data": {
-          "node": {
-            "display_name": "Code Assistant",
-            "template": {
-              "llm": { "value": "gpt-4" },
-              "system_message": { "value": "You are a coding expert." }
-            }
-          }
-        }
-      },
-      {
-        "id": "ChatAgent-multi006",
-        "type": "ConversationChain",
-        "data": {
-          "node": {
-            "display_name": "General Chatbot",
-            "template": {
-              "llm": { "value": "gpt-3.5-turbo" }
-            }
-          }
-        }
-      },
-      {
-        "id": "Merger-multi007",
-        "type": "MergeData",
-        "data": {
-          "node": {
-            "display_name": "Merge Responses"
-          }
-        }
-      },
-      {
-        "id": "Output-multi008",
-        "type": "ChatOutput",
-        "data": {
-          "node": {
-            "display_name": "Final Response"
-          }
-        }
-      }
-    ],
-    "edges": [
-      { "source": "Input-multi001", "target": "Classifier-multi002" },
-      { "source": "Classifier-multi002", "target": "Router-multi003" },
-      { "source": "Router-multi003", "target": "QAAgent-multi004", "sourceHandle": "qa_agent" },
-      { "source": "Router-multi003", "target": "CodeAgent-multi005", "sourceHandle": "code_agent" },
-      { "source": "Router-multi003", "target": "ChatAgent-multi006", "sourceHandle": "chat_agent" },
-      { "source": "QAAgent-multi004", "target": "Merger-multi007" },
-      { "source": "CodeAgent-multi005", "target": "Merger-multi007" },
-      { "source": "ChatAgent-multi006", "target": "Merger-multi007" },
-      { "source": "Merger-multi007", "target": "Output-multi008" }
-    ]
-  },
-  "name": "Multi-Agent Router",
-  "description": "Intelligent routing to specialized agents"
-}
-```
-
-#### OSSA YAML Manifest
-
-```yaml
-apiVersion: ossa/v1
-kind: Agent
-metadata:
-  name: multi-agent-router
-  version: 1.0.0
-  description: "Multi-agent system with intelligent routing - migrated from Langflow"
-  labels:
-    migration_source: langflow
-    pattern: multi-agent-orchestration
-    routing: intent-based
-
-spec:
-  role: orchestration
-
-  # Capabilities
-  capabilities:
-    - name: classify_intent
-      description: "Classify user intent for routing"
-      input_schema:
-        type: object
-        required: ["message"]
-        properties:
-          message:
-            type: string
-      output_schema:
-        type: object
-        required: ["intent", "confidence"]
-        properties:
-          intent:
-            type: string
-            enum: ["QUESTION", "CODE_HELP", "GENERAL_CHAT"]
-          confidence:
-            type: number
-            minimum: 0
-            maximum: 1
-
-    - name: route_to_specialist
-      description: "Route to appropriate specialist agent"
-      input_schema:
-        type: object
-        required: ["intent", "message"]
-        properties:
-          intent:
-            type: string
-          message:
-            type: string
-      output_schema:
-        type: object
-        properties:
-          agent_id:
-            type: string
-            description: "Selected specialist agent"
-
-    - name: qa_specialist
-      description: "Q&A expert agent"
-      input_schema:
-        type: object
-        required: ["question"]
-        properties:
-          question:
-            type: string
-      output_schema:
-        type: object
-        properties:
-          answer:
-            type: string
-
-    - name: code_specialist
-      description: "Code assistant agent"
-      input_schema:
-        type: object
-        required: ["code_query"]
-        properties:
-          code_query:
-            type: string
-      output_schema:
-        type: object
-        properties:
-          code_response:
-            type: string
-            description: "Code help with examples"
-
-    - name: chat_specialist
-      description: "General conversation agent"
-      input_schema:
-        type: object
-        required: ["message"]
-        properties:
-          message:
-            type: string
-      output_schema:
-        type: object
-        properties:
-          chat_response:
-            type: string
-
-  # Sub-agents (specialist agents)
-  agents:
-    - id: qa-specialist-agent
-      name: Q&A Specialist
-      role: workflow
-      llm:
-        provider: openai
-        model: gpt-4
-        temperature: 0.2
-        systemMessage: "You are a Q&A expert. Provide accurate, detailed answers."
-
-    - id: code-specialist-agent
-      name: Code Assistant
-      role: workflow
-      llm:
-        provider: openai
-        model: gpt-4
-        temperature: 0.1
-        systemMessage: "You are a coding expert. Provide code examples and explanations."
-
-    - id: chat-specialist-agent
-      name: General Chatbot
-      role: workflow
-      llm:
-        provider: openai
-        model: gpt-3.5-turbo
-        temperature: 0.7
-        systemMessage: "You are a friendly general chatbot."
-
-  # Runtime
-  runtime:
-    type: kubernetes
-    image: ossa/multi-agent-router:1.0.0
-    replicas: 2
-    resources:
-      cpu: 1000m
-      memory: 1Gi
-
-  # Integration
-  integration:
-    protocol: http
-    endpoints:
-      base_url: http://localhost:3000
-      execute: /api/v1/route
-
-  # Monitoring
-  monitoring:
-    traces: true
-    metrics: true
-    logs: true
-    custom_metrics:
-      - name: intent_classification_accuracy
-        type: gauge
-      - name: routing_decisions
-        type: counter
-        labels: ["intent", "agent"]
-      - name: specialist_response_time_ms
-        type: histogram
-        labels: ["agent"]
-```
-
-#### Implementation Code
-
-```typescript
-// src/index.ts
-import { OSSAAgent, OrchestratorAgent } from '@ossa/agent-sdk';
-import OpenAI from 'openai';
-
-const openai = new OpenAI({ apiKey: process.env.OPENAI_API_KEY });
-
-// Main orchestrator agent
-const orchestrator = new OrchestratorAgent({
-  manifestPath: './multi-agent-router.yaml',
-});
-
-// Capability: classify_intent
-orchestrator.registerCapability('classify_intent', async (input) => {
-  const completion = await openai.chat.completions.create({
-    model: 'gpt-4',
-    messages: [
-      {
-        role: 'system',
-        content: 'Classify user intent. Respond ONLY with JSON: {"intent": "QUESTION"|"CODE_HELP"|"GENERAL_CHAT", "confidence": 0.0-1.0}',
-      },
-      { role: 'user', content: input.message },
-    ],
-    temperature: 0.1,
-  });
-
-  const result = JSON.parse(completion.choices[0].message.content);
-  return result;
-});
-
-// Capability: route_to_specialist
-orchestrator.registerCapability('route_to_specialist', async (input) => {
-  const routingMap = {
-    QUESTION: 'qa-specialist-agent',
-    CODE_HELP: 'code-specialist-agent',
-    GENERAL_CHAT: 'chat-specialist-agent',
-  };
-
-  return { agent_id: routingMap[input.intent] || 'chat-specialist-agent' };
-});
-
-// Specialist Agents
-const qaAgent = new OSSAAgent({
-  id: 'qa-specialist-agent',
-  name: 'Q&A Specialist',
-});
-
-qaAgent.registerCapability('qa_specialist', async (input) => {
-  const completion = await openai.chat.completions.create({
-    model: 'gpt-4',
-    messages: [
-      {
-        role: 'system',
-        content: 'You are a Q&A expert. Provide accurate, detailed answers.',
-      },
-      { role: 'user', content: input.question },
-    ],
-    temperature: 0.2,
-  });
-
-  return { answer: completion.choices[0].message.content };
-});
-
-const codeAgent = new OSSAAgent({
-  id: 'code-specialist-agent',
-  name: 'Code Assistant',
-});
-
-codeAgent.registerCapability('code_specialist', async (input) => {
-  const completion = await openai.chat.completions.create({
-    model: 'gpt-4',
-    messages: [
-      {
-        role: 'system',
-        content: 'You are a coding expert. Provide code examples and explanations.',
-      },
-      { role: 'user', content: input.code_query },
-    ],
-    temperature: 0.1,
-  });
-
-  return { code_response: completion.choices[0].message.content };
-});
-
-const chatAgent = new OSSAAgent({
-  id: 'chat-specialist-agent',
-  name: 'General Chatbot',
-});
-
-chatAgent.registerCapability('chat_specialist', async (input) => {
-  const completion = await openai.chat.completions.create({
-    model: 'gpt-3.5-turbo',
-    messages: [
-      {
-        role: 'system',
-        content: 'You are a friendly general chatbot.',
-      },
-      { role: 'user', content: input.message },
-    ],
-    temperature: 0.7,
-  });
-
-  return { chat_response: completion.choices[0].message.content };
-});
-
-// Register specialist agents with orchestrator
-orchestrator.registerAgent(qaAgent);
-orchestrator.registerAgent(codeAgent);
-orchestrator.registerAgent(chatAgent);
-
-// Orchestration workflow
-orchestrator.defineWorkflow('intelligent_routing', async (input) => {
-  // Step 1: Classify intent
-  const { intent, confidence } = await orchestrator.execute('classify_intent', {
-    message: input.message,
-  });
-
-  // Step 2: Route to specialist
-  const { agent_id } = await orchestrator.execute('route_to_specialist', {
-    intent,
-    message: input.message,
-  });
-
-  // Step 3: Execute on specialist agent
-  let response;
-  switch (agent_id) {
-    case 'qa-specialist-agent':
-      const qaResult = await orchestrator.delegateTo(agent_id, 'qa_specialist', {
-        question: input.message,
-      });
-      response = qaResult.answer;
-      break;
-
-    case 'code-specialist-agent':
-      const codeResult = await orchestrator.delegateTo(agent_id, 'code_specialist', {
-        code_query: input.message,
-      });
-      response = codeResult.code_response;
-      break;
-
-    case 'chat-specialist-agent':
-      const chatResult = await orchestrator.delegateTo(agent_id, 'chat_specialist', {
-        message: input.message,
-      });
-      response = chatResult.chat_response;
-      break;
-  }
-
-  return {
-    response,
-    metadata: {
-      intent,
-      confidence,
-      routed_to: agent_id,
-      timestamp: new Date().toISOString(),
-    },
-  };
-});
-
-orchestrator.start();
-```
-
----
-
-## Advanced Patterns
-
-### Pattern 1: Memory/State Management
-
-**Langflow**: `ConversationBufferMemory` node
-
-**OSSA**: Context management capability
-
-```yaml
-capabilities:
-  - name: manage_conversation_context
-    description: "Manage conversation history and context"
-    input_schema:
-      type: object
-      properties:
-        session_id:
-          type: string
-        message:
-          type: string
-        action:
-          type: string
-          enum: ["add", "retrieve", "clear"]
-    output_schema:
-      type: object
-      properties:
-        context:
-          type: array
-          items:
-            type: object
-            properties:
-              role:
-                type: string
-              content:
-                type: string
-              timestamp:
-                type: string
-
-configuration:
-  context_management:
-    backend: redis
-    max_history: 10
-    ttl_seconds: 3600
-    compression: true
-```
-
-### Pattern 2: Parallel Processing
-
-**Langflow**: Multiple parallel edge branches
-
-**OSSA**: Parallel execution in workflow
-
-```typescript
-// Parallel execution
-orchestrator.defineWorkflow('parallel_processing', async (input) => {
-  // Execute multiple capabilities in parallel
-  const [result1, result2, result3] = await Promise.all([
-    orchestrator.execute('process_option_a', input),
-    orchestrator.execute('process_option_b', input),
-    orchestrator.execute('process_option_c', input),
-  ]);
-
-  // Merge results
-  return {
-    combined: [result1, result2, result3],
-    best_result: selectBestResult([result1, result2, result3]),
-  };
-});
-```
-
-### Pattern 3: Error Handling & Retry
-
-**Langflow**: Limited error handling
-
-**OSSA**: Built-in retry policies and error handling
-
-```yaml
-policies:
-  retry:
-    max_attempts: 3
-    backoff_strategy: exponential
-    backoff_multiplier: 2
-    initial_delay_ms: 1000
-    max_delay_ms: 10000
-    retry_on:
-      - network_error
-      - timeout
-      - rate_limit
-
-  circuit_breaker:
-    enabled: true
-    failure_threshold: 5
-    recovery_timeout_ms: 30000
-
-  fallback:
-    enabled: true
-    fallback_agent: backup-agent
-    conditions:
-      - primary_agent_unavailable
-      - response_time_exceeded
-```
-
----
-
-## Testing & Validation
-
-### Pre-Migration Testing Checklist
-
-```bash
-# 1. Export Langflow flow
-# Download flow.json from Langflow UI
-
-# 2. Validate JSON structure
-jq '.' flow.json > /dev/null && echo "Valid JSON" || echo "Invalid JSON"
-
-# 3. Document flow behavior
-# Test in Langflow UI and record:
-# - Input examples
-# - Expected outputs
-# - Edge cases
-# - Error scenarios
-
-# 4. Identify external dependencies
-jq '.data.nodes[] | select(.data.node.template.api_key != null) | .data.node.display_name' flow.json
-```
-
-### Post-Migration Testing
-
-```bash
-# 1. Validate OSSA manifest
-buildkit agents validate ./migrated-agent.yaml
-
-# 2. Test individual capabilities
-buildkit agents test \
-  --name migrated-agent \
-  --capability format_prompt \
-  --input '{"user_input": "test message"}' \
-  --expect-output '{"formatted_prompt": ".*test message.*"}'
-
-# 3. Integration test
-buildkit agents deploy --name migrated-agent --env test
-
-# Test HTTP endpoint
-curl -X POST http://localhost:3000/api/v1/execute \
-  -H "Content-Type: application/json" \
-  -d '{
-    "operation": "process_conversation",
-    "input": {"message": "Hello world"},
-    "context": {"session_id": "test-123"}
-  }'
-
-# 4. Load testing
-npx autocannon -c 10 -d 30 http://localhost:3000/api/v1/execute \
-  -m POST \
-  -H "Content-Type: application/json" \
-  -b '{"operation":"process_conversation","input":{"message":"test"}}'
-
-# 5. Compare outputs
-# Run same inputs through Langflow and OSSA
-# Compare outputs for consistency
-```
-
-### Regression Test Suite
-
-```typescript
-// tests/migration-regression.test.ts
-import { describe, test, expect } from 'vitest';
-import { OSSAAgent } from '@ossa/agent-sdk';
-
-describe('Migration Regression Tests', () => {
-  const agent = new OSSAAgent({ manifestPath: './migrated-agent.yaml' });
-
-  test('should match Langflow output for simple query', async () => {
-    const input = { message: 'What is the capital of France?' };
-
-    const ossaResult = await agent.executeWorkflow('chat', input);
-
-    // Compare with known Langflow output
-    expect(ossaResult.output).toContain('Paris');
-  });
-
-  test('should handle edge case: empty input', async () => {
-    const input = { message: '' };
-
-    await expect(
-      agent.executeWorkflow('chat', input)
-    ).rejects.toThrow('Input validation failed');
-  });
-
-  test('should preserve response quality', async () => {
-    const input = { message: 'Explain quantum computing' };
-
-    const result = await agent.executeWorkflow('chat', input);
-
-    // Quality checks
-    expect(result.output.length).toBeGreaterThan(100);
-    expect(result.output).toMatch(/quantum|qubit|superposition/i);
-  });
-});
-```
-
----
-
-## Best Practices
-
-### 1. Incremental Migration
-
-Migrate flows incrementally rather than all at once:
-
-```bash
-# Phase 1: Migrate simple flows (1-5 nodes)
-# Phase 2: Migrate medium flows (6-15 nodes)
-# Phase 3: Migrate complex flows (16+ nodes)
-# Phase 4: Integrate all migrated agents
-```
-
-### 2. Preserve Original Flows
-
-Keep Langflow flows as reference:
-
-```bash
-# Create migration archive
-mkdir -p ./migration-archive/langflow-exports
-cp *.json ./migration-archive/langflow-exports/
-git add ./migration-archive
-git commit -m "Archive original Langflow flows for reference"
-```
-
-### 3. Documentation
-
-Document migration decisions:
-
-```yaml
-# In agent manifest
-metadata:
-  annotations:
-    migration.source: "langflow"
-    migration.original_flow: "chatbot-v1.json"
-    migration.date: "2025-11-10"
-    migration.notes: |
-      - Converted PromptTemplate node to format_prompt capability
-      - Replaced ConversationBufferMemory with Redis-backed context management
-      - Added retry policy for OpenAI API calls
-      - Enhanced error handling with circuit breaker
-```
-
-### 4. Type Safety
-
-Leverage OSSA's JSON Schema validation:
-
-```yaml
-capabilities:
-  - name: process_data
-    input_schema:
-      type: object
-      required: ["data", "format"]
-      properties:
-        data:
-          type: string
-          minLength: 1
-          maxLength: 10000
-        format:
-          type: string
-          enum: ["json", "xml", "yaml"]
-        options:
-          type: object
-          additionalProperties: false
-          properties:
-            pretty:
-              type: boolean
-              default: false
-    output_schema:
-      type: object
-      required: ["processed_data", "metadata"]
-      properties:
-        processed_data:
-          type: string
-        metadata:
-          type: object
-          required: ["processing_time_ms", "format"]
-```
-
-### 5. Monitoring & Observability
-
-Add comprehensive monitoring:
-
-```yaml
-monitoring:
-  traces: true
-  metrics: true
-  logs: true
-
-  custom_metrics:
-    - name: langflow_compatibility_score
-      type: gauge
-      description: "Compatibility with original Langflow flow behavior"
-
-    - name: migration_regression_errors
-      type: counter
-      description: "Regression errors vs. original flow"
-
-  alerts:
-    - type: regression_detected
-      condition: "migration_regression_errors > 0"
-      action: notify
-      channels: ["slack", "pagerduty"]
-
-    - type: performance_degradation
-      condition: "avg_response_time > langflow_baseline * 1.5"
-      action: notify
-```
-
-### 6. Version Control Strategy
-
-```bash
-# Create migration branch
-git checkout -b migration/langflow-to-ossa
-
-# Commit structure
-git add .agents/migrated-agent/
-git commit -m "feat: migrate chatbot flow from Langflow to OSSA
-
-- Convert 4 nodes to OSSA capabilities
-- Add JSON Schema validation
-- Implement error handling and retries
-- Add comprehensive monitoring
-
-Migration notes:
-- Source: langflow-chatbot-v1.json
-- All regression tests passing
-- Performance within 5% of original"
-```
-
----
-
-## Troubleshooting
-
-### Common Issues
-
-#### Issue 1: Missing Langflow Component Equivalent
-
-**Problem**: Langflow component has no direct OSSA equivalent
-
-**Solution**: Create custom capability
-
-```typescript
-// Example: Custom Langflow component
-agent.registerCapability('custom_langflow_component', async (input) => {
-  // Replicate Langflow component logic
-  const result = await customLogic(input);
-  return result;
-});
-```
-
-#### Issue 2: Complex Edge Routing
-
-**Problem**: Langflow has complex conditional edges
-
-**Solution**: Implement workflow logic with conditionals
-
-```typescript
-orchestrator.defineWorkflow('complex_routing', async (input) => {
-  const step1 = await orchestrator.execute('initial_process', input);
-
-  // Conditional routing
-  if (step1.condition === 'A') {
-    return await orchestrator.execute('route_a', step1);
-  } else if (step1.condition === 'B') {
-    return await orchestrator.execute('route_b', step1);
-  } else {
-    return await orchestrator.execute('default_route', step1);
-  }
-});
-```
-
-#### Issue 3: State Management Differences
-
-**Problem**: Langflow memory components work differently
-
-**Solution**: Implement external state store
-
-```yaml
-configuration:
-  state_management:
-    backend: redis
-    redis_url: redis://localhost:6379
-    key_prefix: "agent:state:"
-    ttl: 3600
-```
-
-```typescript
-import Redis from 'ioredis';
-
-const redis = new Redis(process.env.REDIS_URL);
-
-agent.registerCapability('manage_state', async (input) => {
-  const key = `agent:state:${input.session_id}`;
-
-  if (input.action === 'save') {
-    await redis.setex(key, 3600, JSON.stringify(input.state));
-  } else if (input.action === 'retrieve') {
-    const state = await redis.get(key);
-    return { state: state ? JSON.parse(state) : null };
-  }
-});
-```
-
-#### Issue 4: Performance Degradation
-
-**Problem**: OSSA agent slower than Langflow
-
-**Solution**: Optimize capability execution and add caching
-
-```yaml
-configuration:
-  caching:
-    enabled: true
-    backend: redis
-    ttl_seconds: 300
-    cache_key_strategy: input_hash
-
-  performance:
-    enable_parallel_execution: true
-    max_concurrent_capabilities: 5
-    timeout_ms: 5000
-```
-
-#### Issue 5: API Key Management
-
-**Problem**: Langflow's API key handling differs
-
-**Solution**: Use OSSA environment variables and secret management
-
-```yaml
-runtime:
-  environment:
-    OPENAI_API_KEY: ${OPENAI_API_KEY}
-    QDRANT_API_KEY: ${QDRANT_API_KEY}
-
-  secrets:
-    - name: api-keys
-      type: kubernetes-secret
-      mount_path: /secrets
-```
-
----
-
-## Migration Automation Tools
-
-### Langflow-to-OSSA CLI Tool
-
-```bash
-# Install migration tool
-npm install -g @ossa/langflow-migrator
-
-# Analyze Langflow flow
-ossa-migrate analyze langflow-flow.json
-
-# Output:
-# Flow Complexity: Medium (7 nodes, 6 edges)
-# Estimated Migration Time: 2-3 hours
-# Components:
-#   - ChatInput (1) → accept_user_input capability
-#   - PromptTemplate (1) → format_prompt capability
-#   - OpenAI (1) → llm_generation capability
-#   - VectorStore (1) → vector_storage capability
-#   - Retriever (1) → semantic_search capability
-#   - ConversationMemory (1) → context_management capability
-#   - ChatOutput (1) → return_response capability
-
-# Generate OSSA manifest
-ossa-migrate convert langflow-flow.json \
-  --output ./agents/migrated-agent.yaml \
-  --generate-code \
-  --add-tests
-
-# Output:
-# ✓ Generated OSSA manifest: ./agents/migrated-agent.yaml
-# ✓ Generated TypeScript implementation: ./agents/migrated-agent/src/index.ts
-# ✓ Generated test suite: ./agents/migrated-agent/tests/
-# ✓ Generated documentation: ./agents/migrated-agent/README.md
-
-# Validate migration
-ossa-migrate validate \
-  --langflow langflow-flow.json \
-  --ossa ./agents/migrated-agent.yaml \
-  --test-inputs test-cases.json
-```
-
----
-
-## Additional Resources
-
-### Documentation
-
-- **OSSA Specification**: https://github.com/blueflyio/openstandardagents/wiki/home
-- **OSSA Quick Reference**: [OSSA-QUICK-REFERENCE.md](../OSSA-QUICK-REFERENCE.md)
-- **BuildKit CLI**: https://github.com/blueflyio/documentation/-/wikis/BuildKit-CLI-Reference
-- **Langflow Documentation**: https://docs.langflow.org/
-
-### Example Repositories
-
-- **OSSA Agent Examples**: `.agents/` directory in agent-buildkit
-- **Migration Examples**: `examples/migrations/langflow/`
-
-### Community & Support
-
-- **GitLab Issues**: https://github.com/blueflyio/documentation/-/issues
-- **Migration Support**: Tag issues with `migration::langflow`
-
----
-
-**Version:** 1.0
-**Last Updated:** 2025-11-10
-**Maintained By:** OSSA Team
-**License:** MIT
-
-**Feedback**: Please report issues or suggestions at https://github.com/blueflyio/documentation/-/issues/new?issue[title]=Langflow%20Migration%20Guide%20Feedback