@bluefly/openstandardagents 0.3.2 → 0.3.3

package/dist/spec/v0.3.3/extensions/semantic-kernel.md

@@ -0,0 +1,1360 @@
+# Microsoft Semantic Kernel Extension for OSSA v0.3.3
+
+**Version:** 0.3.3
+**Status:** Stable
+**Last Updated:** 2025-12-31
+
+## Overview
+
+This document describes the Microsoft Semantic Kernel extension for OSSA manifests. Semantic Kernel is Microsoft's open-source AI orchestration SDK that enables developers to build AI agents with plugins, planners, and memory. This extension provides bidirectional mapping between Semantic Kernel concepts and OSSA primitives.
+
+## Core Concept Mapping
+
+### Semantic Kernel to OSSA Mapping Table
+
+| Semantic Kernel Concept | OSSA Equivalent | Notes |
+|------------------------|-----------------|-------|
+| `Kernel` | `runtime` | Runtime configuration and service container |
+| `Plugin` | `spec.capabilities` | Capability groupings with functions |
+| `KernelFunction` (Native) | `kind: Task` | Deterministic code-based functions |
+| `KernelFunction` (Semantic) | `kind: Agent` (single-turn) | Prompt-based functions with LLM |
+| `SequentialPlanner` | `kind: Workflow` (sequential) | Linear task composition |
+| `StepwisePlanner` | `kind: Workflow` (dag) + `kind: Agent` | Agentic reasoning with tool use |
+| `ActionPlanner` | `kind: Agent` with single tool | Single-action selection |
+| `HandlebarsPlannerOptions` | `spec.prompts.planner` | Planner prompt templates |
+| `ISemanticTextMemory` | `spec.state.memory` | Vector/semantic memory storage |
+| `IChatCompletionService` | `spec.llm` | LLM provider configuration |
+| `ITextEmbeddingGenerationService` | `runtime.bindings.embeddings` | Embedding service binding |
+| `FunctionFilter` | `spec.safety.filters` | Pre/post function execution filters |
+| `PromptFilter` | `spec.safety.prompt_filters` | Prompt modification filters |
+| `AutoFunctionInvocationFilter` | `spec.safety.auto_invoke_filters` | Auto-invocation guards |
+| `KernelAgent` | `kind: Agent` | Full agentic loop with LLM |
+| `AgentGroupChat` | `kind: Workflow` + `messaging` | Multi-agent orchestration |
+
+### OSSA to Semantic Kernel Mapping Table
+
+| OSSA Concept | Semantic Kernel Equivalent | Notes |
+|-------------|---------------------------|-------|
+| `apiVersion: ossa/v0.3.3` | Kernel configuration | Version compatibility |
+| `kind: Agent` | `ChatCompletionAgent` or `OpenAIAssistantAgent` | Agentic LLM loops |
+| `kind: Task` | `KernelFunction` (native) | Deterministic execution |
+| `kind: Workflow` | `Planner` output or `AgentGroupChat` | Composition patterns |
+| `spec.llm.provider` | `IChatCompletionService` implementation | Azure OpenAI, OpenAI, etc. |
+| `spec.tools` | `KernelPlugin` with `KernelFunction` methods | Tool definitions |
+| `spec.capabilities` | Plugin groupings | Abstract capability mapping |
+| `spec.state` | `ISemanticTextMemory` | State persistence |
+| `spec.constraints` | Planner settings + filters | Execution limits |
+| `spec.safety` | `IFunctionFilter`, `IPromptFilter` | Safety guardrails |
+| `spec.observability` | OpenTelemetry integration | Tracing and metrics |
+| `extensions.semanticKernel` | Native SK configuration | Direct passthrough |
+
+## Schema Definition
+
+```yaml
+extensions:
+  semanticKernel:
+    type: object
+    description: "Microsoft Semantic Kernel integration for OSSA agents"
+    properties:
+      enabled:
+        type: boolean
+        default: true
+        description: "Enable Semantic Kernel runtime"
+
+      plugins:
+        type: array
+        description: "Semantic Kernel plugins to load"
+        items:
+          type: object
+          required: [name]
+          properties:
+            name:
+              type: string
+              description: "Plugin name"
+            type:
+              enum: [native, semantic, openapi, grpc]
+              description: "Plugin type"
+            source:
+              type: string
+              description: "Plugin source (assembly, directory, URL)"
+            functions:
+              type: array
+              items:
+                type: object
+                properties:
+                  name:
+                    type: string
+                  description:
+                    type: string
+                  parameters:
+                    type: object
+                  returnType:
+                    type: string
+
+      planner_type:
+        enum: [sequential, stepwise, action, handlebars, function_calling, none]
+        description: "Planner strategy for goal decomposition"
+        default: "function_calling"
+
+      planner_options:
+        type: object
+        description: "Planner-specific configuration"
+        properties:
+          max_iterations:
+            type: integer
+            default: 10
+          max_tokens:
+            type: integer
+            default: 4096
+          allow_loops:
+            type: boolean
+            default: false
+          excluded_plugins:
+            type: array
+            items:
+              type: string
+          excluded_functions:
+            type: array
+            items:
+              type: string
+          semantic_memory_config:
+            type: object
+            properties:
+              relevance_threshold:
+                type: number
+                minimum: 0
+                maximum: 1
+                default: 0.7
+              max_results:
+                type: integer
+                default: 5
+
+      memory_store:
+        type: object
+        description: "Semantic memory configuration"
+        properties:
+          type:
+            enum: [volatile, azure_cognitive_search, qdrant, chroma, pinecone, redis, postgres, sqlite]
+            description: "Memory store backend"
+            default: "volatile"
+          collection:
+            type: string
+            description: "Memory collection/index name"
+          connection:
+            type: object
+            properties:
+              endpoint:
+                type: string
+                format: uri
+              api_key_ref:
+                type: string
+                description: "Reference to secret containing API key"
+              options:
+                type: object
+                additionalProperties: true
+
+      connectors:
+        type: object
+        description: "Service connectors for AI services"
+        properties:
+          chat_completion:
+            type: object
+            properties:
+              service_id:
+                type: string
+                default: "default"
+              provider:
+                enum: [azure_openai, openai, huggingface, ollama, anthropic, google, mistral]
+              model_id:
+                type: string
+              endpoint:
+                type: string
+                format: uri
+              api_key_ref:
+                type: string
+              deployment_name:
+                type: string
+                description: "Azure OpenAI deployment name"
+              options:
+                type: object
+                properties:
+                  temperature:
+                    type: number
+                  max_tokens:
+                    type: integer
+                  top_p:
+                    type: number
+          text_embedding:
+            type: object
+            properties:
+              service_id:
+                type: string
+                default: "default"
+              provider:
+                enum: [azure_openai, openai, huggingface, ollama]
+              model_id:
+                type: string
+              endpoint:
+                type: string
+                format: uri
+              api_key_ref:
+                type: string
+              dimensions:
+                type: integer
+                description: "Embedding vector dimensions"
+          image_generation:
+            type: object
+            properties:
+              service_id:
+                type: string
+              provider:
+                enum: [azure_openai, openai, dall_e]
+              model_id:
+                type: string
+          audio_to_text:
+            type: object
+            properties:
+              service_id:
+                type: string
+              provider:
+                enum: [azure_openai, openai, whisper]
+              model_id:
+                type: string
+          text_to_audio:
+            type: object
+            properties:
+              service_id:
+                type: string
+              provider:
+                enum: [azure_openai, openai, elevenlabs]
+              model_id:
+                type: string
+
+      filters:
+        type: object
+        description: "Semantic Kernel filter configuration"
+        properties:
+          function_filters:
+            type: array
+            description: "Pre/post function execution filters"
+            items:
+              type: object
+              required: [name]
+              properties:
+                name:
+                  type: string
+                type:
+                  enum: [pre, post, both]
+                  default: "both"
+                handler:
+                  type: string
+                  description: "Filter handler reference"
+                config:
+                  type: object
+                  additionalProperties: true
+          prompt_filters:
+            type: array
+            description: "Prompt rendering filters"
+            items:
+              type: object
+              required: [name]
+              properties:
+                name:
+                  type: string
+                type:
+                  enum: [pre_render, post_render, both]
+                  default: "both"
+                handler:
+                  type: string
+          auto_invoke_filters:
+            type: array
+            description: "Auto function invocation filters"
+            items:
+              type: object
+              required: [name]
+              properties:
+                name:
+                  type: string
+                handler:
+                  type: string
+                terminate_on_match:
+                  type: boolean
+                  default: false
+
+      agent_config:
+        type: object
+        description: "Semantic Kernel Agent configuration (for ChatCompletionAgent)"
+        properties:
+          type:
+            enum: [chat_completion, openai_assistant, azure_assistant]
+            default: "chat_completion"
+          instructions:
+            type: string
+            description: "Agent system instructions"
+          name:
+            type: string
+          description:
+            type: string
+          execution_settings:
+            type: object
+            properties:
+              max_iterations:
+                type: integer
+                default: 10
+              enable_code_interpreter:
+                type: boolean
+                default: false
+              enable_file_search:
+                type: boolean
+                default: false
+              tool_choice:
+                enum: [auto, required, none]
+                default: "auto"
+
+      telemetry:
+        type: object
+        description: "OpenTelemetry configuration for SK"
+        properties:
+          enabled:
+            type: boolean
+            default: true
+          activity_source_name:
+            type: string
+            default: "Microsoft.SemanticKernel"
+          meter_name:
+            type: string
+            default: "Microsoft.SemanticKernel"
+          log_function_invocations:
+            type: boolean
+            default: true
+          log_prompt_template_content:
+            type: boolean
+            default: false
+          log_function_results:
+            type: boolean
+            default: false
+```
+
+## Plugin to OSSA Capability Mapping
+
+### Native Function Plugin to OSSA Task
+
+Semantic Kernel native function:
+
+```csharp
+public class MathPlugin
+{
+    [KernelFunction, Description("Adds two numbers")]
+    public double Add(double a, double b) => a + b;
+
+    [KernelFunction, Description("Multiplies two numbers")]
+    public double Multiply(double a, double b) => a * b;
+}
+```
+
+Equivalent OSSA Task manifest:
+
+```yaml
+apiVersion: ossa/v0.3.3
+kind: Task
+metadata:
+  name: math-add
+  version: 1.0.0
+  description: "Adds two numbers"
+  labels:
+    plugin: math
+    function: add
+
+spec:
+  execution:
+    type: deterministic
+    runtime: dotnet
+    entrypoint: "MathPlugin::Add"
+    timeout_seconds: 5
+
+  capabilities:
+    - compute_arithmetic
+
+  input:
+    type: object
+    required: [a, b]
+    properties:
+      a:
+        type: number
+        description: "First number"
+      b:
+        type: number
+        description: "Second number"
+
+  output:
+    type: number
+    description: "Sum of a and b"
+
+extensions:
+  semanticKernel:
+    enabled: true
+    plugins:
+      - name: Math
+        type: native
+        functions:
+          - name: Add
+            description: "Adds two numbers"
+            parameters:
+              a: { type: number }
+              b: { type: number }
+            returnType: number
+```
+
+### Semantic Function to OSSA Agent
+
+Semantic Kernel semantic function:
+
+```yaml
+# SummarizePlugin/Summarize/skprompt.txt
+Summarize the following text in {{$style}} style:
+
+{{$input}}
+
+Summary:
+```
+
+Equivalent OSSA Agent manifest:
+
+```yaml
+apiVersion: ossa/v0.3.3
+kind: Agent
+metadata:
+  name: summarizer
+  version: 1.0.0
+  description: "Summarizes text in specified style"
+  labels:
+    plugin: summarize
+    function: summarize
+
+spec:
+  role: |
+    You are a text summarization agent. Summarize the provided text
+    according to the specified style.
+
+  prompts:
+    system:
+      template: |
+        Summarize the following text in {{style}} style:
+
+        {{input}}
+
+        Summary:
+      version: "1.0.0"
+
+  llm:
+    provider: azure_openai
+    model: gpt-4
+    temperature: 0.3
+
+  autonomy:
+    level: tool_assist
+    max_iterations: 1
+
+extensions:
+  semanticKernel:
+    enabled: true
+    plugins:
+      - name: Summarize
+        type: semantic
+        source: "./prompts/Summarize"
+        functions:
+          - name: Summarize
+            description: "Summarizes text in specified style"
+            parameters:
+              input: { type: string }
+              style: { type: string, default: "concise" }
+```
+
+## Planner to OSSA Workflow Mapping
+
+### Sequential Planner to OSSA Workflow
+
+Semantic Kernel sequential plan:
+
+```csharp
+var planner = new SequentialPlanner(kernel);
+var plan = await planner.CreatePlanAsync("Write a poem about AI and email it");
+```
+
+Generated plan steps:
+1. `WriterPlugin.WritePoem` - Generate poem
+2. `EmailPlugin.SendEmail` - Send email
+
+Equivalent OSSA Workflow:
+
+```yaml
+apiVersion: ossa/v0.3.3
+kind: Workflow
+metadata:
+  name: poem-email-workflow
+  version: 1.0.0
+  description: "Write a poem and email it"
+
+spec:
+  type: sequential
+
+  input:
+    type: object
+    properties:
+      topic:
+        type: string
+        description: "Poem topic"
+      recipient:
+        type: string
+        format: email
+
+  steps:
+    - id: write-poem
+      name: "Write Poem"
+      ref: agents/writer
+      input:
+        topic: "${{ input.topic }}"
+        style: "poetic"
+
+    - id: send-email
+      name: "Send Email"
+      ref: tasks/email-sender
+      input:
+        to: "${{ input.recipient }}"
+        subject: "A Poem About ${{ input.topic }}"
+        body: "${{ steps.write-poem.output.content }}"
+      depends_on:
+        - write-poem
+
+  output:
+    poem: "${{ steps.write-poem.output.content }}"
+    email_sent: "${{ steps.send-email.output.success }}"
+
+extensions:
+  semanticKernel:
+    enabled: true
+    planner_type: sequential
+    planner_options:
+      max_iterations: 5
+      excluded_functions:
+        - "FilePlugin.*"
+```
+
+### Stepwise Planner to OSSA Agent with Workflow
+
+Semantic Kernel stepwise planner (ReAct-style):
+
+```csharp
+var planner = new StepwisePlanner(kernel, new StepwisePlannerConfig
+{
+    MaxIterations = 10,
+    MinIterationTimeMs = 0
+});
+var result = await planner.ExecuteAsync("Research and summarize recent AI news");
+```
+
+Equivalent OSSA Agent with tools:
+
+```yaml
+apiVersion: ossa/v0.3.3
+kind: Agent
+metadata:
+  name: research-agent
+  version: 1.0.0
+  description: "Research and summarize using ReAct-style reasoning"
+
+spec:
+  role: |
+    You are a research agent that gathers information and provides summaries.
+    Think step by step, use available tools to gather information, and
+    synthesize your findings into a coherent summary.
+
+  llm:
+    provider: azure_openai
+    model: gpt-4
+    temperature: 0.7
+
+  tools:
+    - name: web_search
+      description: "Search the web for information"
+      input_schema:
+        type: object
+        properties:
+          query: { type: string }
+
+    - name: summarize
+      description: "Summarize text content"
+      input_schema:
+        type: object
+        properties:
+          text: { type: string }
+          max_length: { type: integer, default: 200 }
+
+  autonomy:
+    level: full_auto
+    max_iterations: 10
+    requires_approval: false
+
+  constraints:
+    max_iterations: 10
+    timeout_seconds: 300
+
+extensions:
+  semanticKernel:
+    enabled: true
+    planner_type: stepwise
+    planner_options:
+      max_iterations: 10
+      allow_loops: true
+      semantic_memory_config:
+        relevance_threshold: 0.75
+        max_results: 3
+```
+
+## Memory Store Configuration
+
+### Semantic Memory to OSSA State
+
+Semantic Kernel memory usage:
+
+```csharp
+var memory = new MemoryBuilder()
+    .WithAzureCognitiveSearchMemoryStore(endpoint, apiKey)
+    .WithAzureOpenAITextEmbeddingGeneration(deploymentName, endpoint, apiKey)
+    .Build();
+
+await memory.SaveInformationAsync("documents", "AI is transforming software", "doc1");
+var results = await memory.SearchAsync("documents", "machine learning", limit: 5);
+```
+
+Equivalent OSSA configuration:
+
+```yaml
+apiVersion: ossa/v0.3.3
+kind: Agent
+metadata:
+  name: knowledge-agent
+  version: 1.0.0
+
+spec:
+  role: "Knowledge assistant with semantic memory"
+
+  llm:
+    provider: azure_openai
+    model: gpt-4
+
+  state:
+    type: semantic
+    memory:
+      backend: azure_cognitive_search
+      collection: documents
+      embedding_model: text-embedding-ada-002
+      retrieval:
+        relevance_threshold: 0.75
+        max_results: 5
+
+extensions:
+  semanticKernel:
+    enabled: true
+    memory_store:
+      type: azure_cognitive_search
+      collection: documents
+      connection:
+        endpoint: "${AZURE_SEARCH_ENDPOINT}"
+        api_key_ref: azure-search-key
+        options:
+          index_name: "ossa-knowledge"
+          semantic_config: "default"
+    connectors:
+      text_embedding:
+        provider: azure_openai
+        model_id: text-embedding-ada-002
+        endpoint: "${AZURE_OPENAI_ENDPOINT}"
+        api_key_ref: azure-openai-key
+        dimensions: 1536
+```
+
+### Vector Store Options
+
+```yaml
+extensions:
+  semanticKernel:
+    memory_store:
+      # Qdrant
+      type: qdrant
+      collection: "agent-memory"
+      connection:
+        endpoint: "http://localhost:6333"
+        options:
+          vector_size: 1536
+          distance: Cosine
+
+      # Chroma
+      type: chroma
+      collection: "agent-memory"
+      connection:
+        endpoint: "http://localhost:8000"
+
+      # Pinecone
+      type: pinecone
+      collection: "agent-memory"
+      connection:
+        api_key_ref: pinecone-key
+        options:
+          environment: "us-east1-gcp"
+          index_name: "ossa-index"
+
+      # Redis
+      type: redis
+      collection: "agent-memory"
+      connection:
+        endpoint: "redis://localhost:6379"
+        options:
+          prefix: "ossa:memory:"
+
+      # PostgreSQL with pgvector
+      type: postgres
+      collection: "agent_memory"
+      connection:
+        endpoint: "postgresql://localhost:5432/ossa"
+        options:
+          schema: "semantic_kernel"
+          table: "embeddings"
+```
+
+## Filter Configuration
+
+### Function Filters for Safety
+
+Semantic Kernel filters:
+
+```csharp
+public class SafetyFilter : IFunctionFilter
+{
+    public async Task OnFunctionInvokedAsync(FunctionInvokedContext context)
+    {
+        // Log invocation
+        // Check result safety
+    }
+
+    public async Task OnFunctionInvokingAsync(FunctionInvokingContext context)
+    {
+        // Validate inputs
+        // Check permissions
+    }
+}
+```
+
+OSSA equivalent:
+
+```yaml
+apiVersion: ossa/v0.3.3
+kind: Agent
+metadata:
+  name: safe-agent
+  version: 1.0.0
+
+spec:
+  role: "Agent with safety filters"
+
+  llm:
+    provider: azure_openai
+    model: gpt-4
+
+  safety:
+    guardrails:
+      enabled: true
+      policies:
+        - name: input_validation
+          type: pre_execution
+          config:
+            max_input_length: 10000
+            prohibited_patterns:
+              - "password"
+              - "secret"
+        - name: output_safety
+          type: post_execution
+          config:
+            content_filter: true
+            pii_detection: true
+
+extensions:
+  semanticKernel:
+    enabled: true
+    filters:
+      function_filters:
+        - name: safety-filter
+          type: both
+          handler: "SafetyFilters.SafetyFilter"
+          config:
+            log_invocations: true
+            validate_inputs: true
+            check_permissions: true
+
+        - name: rate-limiter
+          type: pre
+          handler: "SafetyFilters.RateLimiter"
+          config:
+            max_calls_per_minute: 60
+
+      prompt_filters:
+        - name: content-filter
+          type: post_render
+          handler: "SafetyFilters.ContentFilter"
+
+      auto_invoke_filters:
+        - name: dangerous-function-guard
+          handler: "SafetyFilters.DangerousFunctionGuard"
+          terminate_on_match: true
+```
+
+## Connector Configuration
+
+### Multi-Service Connectors
+
+```yaml
+extensions:
+  semanticKernel:
+    enabled: true
+    connectors:
+      chat_completion:
+        service_id: "primary"
+        provider: azure_openai
+        model_id: gpt-4
+        endpoint: "${AZURE_OPENAI_ENDPOINT}"
+        deployment_name: "gpt-4-deployment"
+        api_key_ref: azure-openai-key
+        options:
+          temperature: 0.7
+          max_tokens: 4096
+          top_p: 0.95
+
+      text_embedding:
+        service_id: "embeddings"
+        provider: azure_openai
+        model_id: text-embedding-ada-002
+        endpoint: "${AZURE_OPENAI_ENDPOINT}"
+        api_key_ref: azure-openai-key
+        dimensions: 1536
+
+      image_generation:
+        service_id: "images"
+        provider: azure_openai
+        model_id: dall-e-3
+        options:
+          size: "1024x1024"
+          quality: "hd"
+
+      audio_to_text:
+        service_id: "transcription"
+        provider: azure_openai
+        model_id: whisper
+
+      text_to_audio:
+        service_id: "speech"
+        provider: azure_openai
+        model_id: tts-1
+```
+
+## Agent Configuration (ChatCompletionAgent)
+
+### Single Agent
+
+```yaml
+apiVersion: ossa/v0.3.3
+kind: Agent
+metadata:
+  name: code-assistant
+  version: 1.0.0
+
+spec:
+  role: "Expert coding assistant"
+
+  llm:
+    provider: azure_openai
+    model: gpt-4
+
+  tools:
+    - name: execute_code
+      description: "Execute Python code"
+    - name: search_docs
+      description: "Search documentation"
+
+extensions:
+  semanticKernel:
+    enabled: true
+    agent_config:
+      type: chat_completion
+      name: "CodeAssistant"
+      instructions: |
+        You are an expert coding assistant. Help users write,
+        debug, and optimize code. Use tools when needed.
+      execution_settings:
+        max_iterations: 10
+        tool_choice: auto
+```
+
+### Agent Group Chat (Multi-Agent)
+
+```yaml
+apiVersion: ossa/v0.3.3
+kind: Workflow
+metadata:
+  name: review-workflow
+  version: 1.0.0
+  description: "Multi-agent code review"
+
+spec:
+  type: dag
+
+  agents:
+    - ref: agents/code-analyzer
+      role: analyzer
+    - ref: agents/security-reviewer
+      role: security
+    - ref: agents/summarizer
+      role: reporter
+
+  orchestration:
+    type: round_robin
+    max_turns: 10
+    termination:
+      type: consensus
+      required_agreement: 2
+
+extensions:
+  semanticKernel:
+    enabled: true
+    agent_config:
+      type: chat_completion
+      execution_settings:
+        max_iterations: 10
+    planner_type: none  # Agents coordinate via chat
+```
+
+## Complete Example
+
+### Full-Featured OSSA Agent with Semantic Kernel
+
+```yaml
+apiVersion: ossa/v0.3.3
+kind: Agent
+metadata:
+  name: enterprise-assistant
+  version: 1.0.0
+  description: "Enterprise AI assistant with full Semantic Kernel integration"
+  labels:
+    team: platform
+    environment: production
+    tier: tier_2_write_limited
+
+spec:
+  role: |
+    You are an enterprise AI assistant with access to company knowledge,
+    document generation, and workflow automation capabilities.
+
+  type: worker
+
+  llm:
+    provider: azure_openai
+    model: gpt-4
+    temperature: 0.7
+    max_tokens: 4096
+
+  tools:
+    - name: search_knowledge
+      description: "Search company knowledge base"
+      input_schema:
+        type: object
+        properties:
+          query: { type: string }
+          collection: { type: string, default: "general" }
+
+    - name: create_document
+      description: "Generate business documents"
+      input_schema:
+        type: object
+        properties:
+          type: { enum: [report, memo, proposal] }
+          content: { type: string }
+
+    - name: send_notification
+      description: "Send team notification"
+      input_schema:
+        type: object
+        properties:
+          channel: { type: string }
+          message: { type: string }
+
+  autonomy:
+    level: supervised
+    max_iterations: 15
+    requires_approval: true
+    approval_timeout_seconds: 300
+
+  constraints:
+    max_iterations: 15
+    timeout_seconds: 600
+    max_tokens_per_turn: 4096
+
+  state:
+    type: semantic
+    memory:
+      backend: azure_cognitive_search
+      collection: enterprise_knowledge
+      embedding_model: text-embedding-ada-002
+
+  safety:
+    guardrails:
+      enabled: true
+      max_tool_calls: 20
+      policies:
+        - name: pii_filter
+          type: post_execution
+        - name: content_moderation
+          type: pre_execution
+
+  access:
+    tier: tier_2_write_limited
+    permissions:
+      - read_code
+      - read_docs
+      - write_docs
+      - create_issues
+
+  observability:
+    tracing:
+      enabled: true
+      sampler: always
+    metrics:
+      enabled: true
+      interval: 60
+    logging:
+      level: info
+      format: json
+
+extensions:
+  semanticKernel:
+    enabled: true
+
+    plugins:
+      - name: Knowledge
+        type: native
+        source: "EnterprisePlugins.KnowledgePlugin"
+        functions:
+          - name: Search
+            description: "Search knowledge base"
+          - name: Store
+            description: "Store new knowledge"
+
+      - name: Documents
+        type: native
+        source: "EnterprisePlugins.DocumentPlugin"
+        functions:
+          - name: Generate
+            description: "Generate document"
+          - name: Template
+            description: "Apply template"
+
+      - name: Summarize
+        type: semantic
+        source: "./prompts/Summarize"
+
+    planner_type: function_calling
+    planner_options:
+      max_iterations: 15
+      max_tokens: 4096
+      excluded_plugins:
+        - "AdminPlugin"
+      semantic_memory_config:
+        relevance_threshold: 0.8
+        max_results: 10
+
+    memory_store:
+      type: azure_cognitive_search
+      collection: enterprise_knowledge
+      connection:
+        endpoint: "${AZURE_SEARCH_ENDPOINT}"
+        api_key_ref: azure-search-key
+        options:
+          semantic_config: "enterprise-semantic"
+
+    connectors:
+      chat_completion:
+        service_id: primary
+        provider: azure_openai
+        model_id: gpt-4
+        endpoint: "${AZURE_OPENAI_ENDPOINT}"
+        deployment_name: "gpt-4-turbo"
+        api_key_ref: azure-openai-key
+        options:
+          temperature: 0.7
+          max_tokens: 4096
+
+      text_embedding:
+        service_id: embeddings
+        provider: azure_openai
+        model_id: text-embedding-ada-002
+        endpoint: "${AZURE_OPENAI_ENDPOINT}"
+        api_key_ref: azure-openai-key
+        dimensions: 1536
+
+    filters:
+      function_filters:
+        - name: audit-logger
+          type: both
+          handler: "EnterpriseFilters.AuditLogger"
+          config:
+            log_inputs: true
+            log_outputs: false
+
+        - name: permission-checker
+          type: pre
+          handler: "EnterpriseFilters.PermissionChecker"
+
+      prompt_filters:
+        - name: pii-redactor
+          type: pre_render
+          handler: "EnterpriseFilters.PIIRedactor"
+
+      auto_invoke_filters:
+        - name: cost-limiter
+          handler: "EnterpriseFilters.CostLimiter"
+          terminate_on_match: true
+
+    agent_config:
+      type: chat_completion
+      name: "EnterpriseAssistant"
+      instructions: |
+        You are an enterprise AI assistant. Follow company policies,
+        protect sensitive information, and help users accomplish tasks.
+      execution_settings:
+        max_iterations: 15
+        tool_choice: auto
+
+    telemetry:
+      enabled: true
+      activity_source_name: "Enterprise.SemanticKernel"
+      meter_name: "Enterprise.SemanticKernel"
+      log_function_invocations: true
+      log_prompt_template_content: false
+      log_function_results: false
+
+runtime:
+  bindings:
+    search_knowledge:
+      capability: knowledge_search
+      binding: azure_cognitive_search
+      config:
+        index: enterprise_knowledge
+    create_document:
+      capability: document_generation
+      binding: document_service
+    send_notification:
+      capability: notifications
+      binding: teams_webhook
+```
+
+## OpenAPI Plugin Integration
+
+### Import OpenAPI Spec as Plugin
+
+```yaml
+extensions:
+  semanticKernel:
+    plugins:
+      - name: GitHubAPI
+        type: openapi
+        source: "https://api.github.com/openapi.json"
+        functions:
+          - name: ListRepos
+            operationId: "repos/list-for-authenticated-user"
+          - name: CreateIssue
+            operationId: "issues/create"
+
+      - name: InternalAPI
+        type: openapi
+        source: "./specs/internal-api.yaml"
+        authentication:
+          type: bearer
+          token_ref: internal-api-token
+```
+
+## Zod Validation Schema
+
+For TypeScript/JavaScript runtimes, use this Zod schema for validation:
+
+```typescript
+import { z } from 'zod';
+
+const SemanticKernelPluginSchema = z.object({
+  name: z.string(),
+  type: z.enum(['native', 'semantic', 'openapi', 'grpc']),
+  source: z.string().optional(),
+  functions: z.array(z.object({
+    name: z.string(),
+    description: z.string().optional(),
+    parameters: z.record(z.any()).optional(),
+    returnType: z.string().optional(),
+  })).optional(),
+});
+
+const SemanticKernelMemoryStoreSchema = z.object({
+  type: z.enum([
+    'volatile',
+    'azure_cognitive_search',
+    'qdrant',
+    'chroma',
+    'pinecone',
+    'redis',
+    'postgres',
+    'sqlite'
+  ]),
+  collection: z.string().optional(),
+  connection: z.object({
+    endpoint: z.string().url().optional(),
+    api_key_ref: z.string().optional(),
+    options: z.record(z.any()).optional(),
+  }).optional(),
+});
+
+const SemanticKernelConnectorSchema = z.object({
+  service_id: z.string().default('default'),
+  provider: z.enum([
+    'azure_openai',
+    'openai',
+    'huggingface',
+    'ollama',
+    'anthropic',
+    'google',
+    'mistral'
+  ]),
+  model_id: z.string().optional(),
+  endpoint: z.string().url().optional(),
+  api_key_ref: z.string().optional(),
+  deployment_name: z.string().optional(),
+  dimensions: z.number().int().positive().optional(),
+  options: z.object({
+    temperature: z.number().min(0).max(2).optional(),
+    max_tokens: z.number().int().positive().optional(),
+    top_p: z.number().min(0).max(1).optional(),
+  }).optional(),
+});
+
+const SemanticKernelFilterSchema = z.object({
+  name: z.string(),
+  type: z.enum(['pre', 'post', 'both', 'pre_render', 'post_render']).optional(),
+  handler: z.string(),
+  config: z.record(z.any()).optional(),
+  terminate_on_match: z.boolean().optional(),
+});
+
+const SemanticKernelExtensionSchema = z.object({
+  enabled: z.boolean().default(true),
+  plugins: z.array(SemanticKernelPluginSchema).optional(),
+  planner_type: z.enum([
+    'sequential',
+    'stepwise',
+    'action',
+    'handlebars',
+    'function_calling',
+    'none'
+  ]).default('function_calling'),
+  planner_options: z.object({
+    max_iterations: z.number().int().positive().default(10),
+    max_tokens: z.number().int().positive().default(4096),
+    allow_loops: z.boolean().default(false),
+    excluded_plugins: z.array(z.string()).optional(),
+    excluded_functions: z.array(z.string()).optional(),
+    semantic_memory_config: z.object({
+      relevance_threshold: z.number().min(0).max(1).default(0.7),
+      max_results: z.number().int().positive().default(5),
+    }).optional(),
+  }).optional(),
+  memory_store: SemanticKernelMemoryStoreSchema.optional(),
+  connectors: z.object({
+    chat_completion: SemanticKernelConnectorSchema.optional(),
+    text_embedding: SemanticKernelConnectorSchema.optional(),
+    image_generation: SemanticKernelConnectorSchema.optional(),
+    audio_to_text: SemanticKernelConnectorSchema.optional(),
+    text_to_audio: SemanticKernelConnectorSchema.optional(),
+  }).optional(),
+  filters: z.object({
+    function_filters: z.array(SemanticKernelFilterSchema).optional(),
+    prompt_filters: z.array(SemanticKernelFilterSchema).optional(),
+    auto_invoke_filters: z.array(SemanticKernelFilterSchema).optional(),
+  }).optional(),
+  agent_config: z.object({
+    type: z.enum(['chat_completion', 'openai_assistant', 'azure_assistant']).default('chat_completion'),
+    instructions: z.string().optional(),
+    name: z.string().optional(),
+    description: z.string().optional(),
+    execution_settings: z.object({
+      max_iterations: z.number().int().positive().default(10),
+      enable_code_interpreter: z.boolean().default(false),
+      enable_file_search: z.boolean().default(false),
+      tool_choice: z.enum(['auto', 'required', 'none']).default('auto'),
+    }).optional(),
+  }).optional(),
+  telemetry: z.object({
+    enabled: z.boolean().default(true),
+    activity_source_name: z.string().default('Microsoft.SemanticKernel'),
+    meter_name: z.string().default('Microsoft.SemanticKernel'),
+    log_function_invocations: z.boolean().default(true),
+    log_prompt_template_content: z.boolean().default(false),
+    log_function_results: z.boolean().default(false),
+  }).optional(),
+});
+
+export { SemanticKernelExtensionSchema };
+```
+
+## Migration Guide
+
+### From Semantic Kernel to OSSA
+
+1. **Export plugins**: Convert native/semantic plugins to OSSA Tasks/Agents
+2. **Map planners**: Convert planner usage to OSSA Workflows
+3. **Configure memory**: Map memory stores to OSSA state configuration
+4. **Add extension**: Include `extensions.semanticKernel` for bidirectional sync
+
+### From OSSA to Semantic Kernel
+
+1. **Generate kernel config**: Use OSSA manifest to configure Kernel
+2. **Import plugins**: Convert OSSA capabilities to SK plugins
+3. **Configure services**: Map runtime bindings to SK connectors
+4. **Apply filters**: Convert safety policies to SK filters
+
+## Validation
+
+Validate your manifest using the OSSA CLI:
+
+```bash
+# Validate manifest with SK extension
+ossa validate agent.yaml --extension semanticKernel
+
+# Generate SK configuration from OSSA
+ossa export --format semantic-kernel agent.yaml > kernel-config.json
+
+# Import SK plugin as OSSA
+ossa import --from semantic-kernel ./plugins/MyPlugin > tasks/my-plugin.yaml
+```
+
+## Best Practices
+
+1. **Use function_calling planner**: Preferred for modern GPT-4 models
+2. **Configure memory wisely**: Use volatile for development, persistent for production
+3. **Apply filters for safety**: Always use function filters for production agents
+4. **Monitor with telemetry**: Enable OpenTelemetry for observability
+5. **Version your prompts**: Use prompt versioning for semantic functions
+6. **Test planners thoroughly**: Validate planner output before production
+7. **Secure credentials**: Use api_key_ref, never inline secrets
+8. **Set appropriate limits**: Configure max_iterations and timeouts
+
+## Related
+
+- [Microsoft Semantic Kernel Documentation](https://learn.microsoft.com/en-us/semantic-kernel/)
+- [Semantic Kernel GitHub](https://github.com/microsoft/semantic-kernel)
+- [OSSA Manifest Schema](../ossa-0.3.3.schema.json)
+- [OSSA Runtime Bindings](../runtime/bindings.yaml)
+- [OSSA Safety Configuration](../schemas/safety.schema.json)