@bluefly/openstandardagents 0.3.3 → 0.3.6

package/spec/v0.3.3/extensions/autogen.md

@@ -1,1124 +0,0 @@
-# Microsoft AutoGen Extension for OSSA v0.3.3
-
-## Overview
-
-The `extensions.autogen` schema provides comprehensive bidirectional mapping between Microsoft AutoGen's multi-agent conversation framework and OSSA v0.3.3 manifests. This extension enables seamless interoperability between AutoGen agent patterns and OSSA's standardized agent specifications.
-
-AutoGen is Microsoft's open-source framework for building AI agents that can converse with each other to solve tasks. It supports conversable agents, group chats, code execution, function calling, and nested agent architectures.
-
-## Schema Definition
-
-```yaml
-extensions:
-  autogen:
-    type: object
-    description: "Microsoft AutoGen multi-agent framework extension for OSSA v0.3.3"
-    properties:
-      agent_type:
-        type: string
-        enum:
-          - conversable_agent
-          - assistant_agent
-          - user_proxy_agent
-          - group_chat_manager
-          - teachable_agent
-          - reasoning_agent
-          - captain_agent
-          - custom_agent
-        description: "AutoGen agent class type - determines base behavior and capabilities"
-        examples:
-          - "assistant_agent"
-          - "user_proxy_agent"
-          - "group_chat_manager"
-
-      llm_config:
-        type: object
-        description: "LLM configuration for the agent (mirrors AutoGen's llm_config)"
-        properties:
-          config_list:
-            type: array
-            description: "List of LLM configurations (model, api_key reference, base_url)"
-            items:
-              type: object
-              properties:
-                model:
-                  type: string
-                  description: "Model identifier (e.g., gpt-4, claude-3-opus)"
-                  examples:
-                    - "gpt-4-turbo"
-                    - "gpt-4o"
-                    - "claude-3-opus"
-                api_key_env:
-                  type: string
-                  description: "Environment variable containing API key (never store keys directly)"
-                  pattern: "^[A-Z][A-Z0-9_]*$"
-                  examples:
-                    - "OPENAI_API_KEY"
-                    - "AZURE_OPENAI_API_KEY"
-                base_url:
-                  type: string
-                  format: uri
-                  description: "Custom API endpoint (for Azure, local models, etc.)"
-                api_type:
-                  type: string
-                  enum: [openai, azure, anthropic, ollama, litellm]
-                  description: "API provider type"
-                api_version:
-                  type: string
-                  description: "API version (required for Azure)"
-          temperature:
-            type: number
-            minimum: 0
-            maximum: 2
-            default: 0.7
-            description: "Sampling temperature"
-          timeout:
-            type: integer
-            minimum: 1
-            default: 600
-            description: "Request timeout in seconds"
-          cache_seed:
-            oneOf:
-              - type: integer
-              - type: "null"
-            description: "Seed for response caching (null disables caching)"
-
-      human_input_mode:
-        type: string
-        enum:
-          - ALWAYS
-          - NEVER
-          - TERMINATE
-        default: NEVER
-        description: "When to request human input during conversation"
-
-      code_execution_config:
-        oneOf:
-          - type: object
-            description: "Code execution sandbox configuration"
-            properties:
-              work_dir:
-                type: string
-                description: "Working directory for code execution"
-                default: "workspace"
-              use_docker:
-                oneOf:
-                  - type: boolean
-                  - type: string
-                description: "Docker image for sandboxed execution (true, false, or image name)"
-                default: false
-              timeout:
-                type: integer
-                minimum: 1
-                default: 60
-                description: "Code execution timeout in seconds"
-              last_n_messages:
-                type: integer
-                minimum: 1
-                description: "Number of messages to scan for code blocks"
-                default: 1
-              executor_type:
-                type: string
-                enum:
-                  - local_command_line
-                  - docker_command_line
-                  - jupyter
-                  - azure_container_instance
-                default: local_command_line
-                description: "Type of code executor to use"
-              allowed_languages:
-                type: array
-                items:
-                  type: string
-                  enum:
-                    - python
-                    - bash
-                    - shell
-                    - javascript
-                    - powershell
-                description: "Languages allowed for code execution"
-                default: ["python", "bash"]
-          - type: boolean
-            const: false
-            description: "Disable code execution"
-
-      max_consecutive_auto_reply:
-        type: integer
-        minimum: 0
-        description: "Maximum auto-replies before requiring human input"
-        default: 10
-
-      termination_config:
-        type: object
-        description: "Conversation termination settings"
-        properties:
-          is_termination_msg:
-            type: string
-            description: "Python lambda or function reference to check for termination"
-            examples:
-              - "lambda msg: 'TERMINATE' in msg.get('content', '')"
-          termination_keywords:
-            type: array
-            items:
-              type: string
-            description: "Keywords that trigger conversation termination"
-            default: ["TERMINATE"]
-          max_turns:
-            type: integer
-            minimum: 1
-            description: "Maximum conversation turns before termination"
-
-      group_chat_config:
-        type: object
-        description: "GroupChat configuration (for multi-agent orchestration)"
-        properties:
-          agents:
-            type: array
-            description: "References to agents participating in group chat"
-            items:
-              type: string
-              description: "OSSA agent name reference"
-          max_round:
-            type: integer
-            minimum: 1
-            default: 10
-            description: "Maximum conversation rounds"
-          admin_name:
-            type: string
-            description: "Name of the admin agent"
-            default: "Admin"
-          speaker_selection_method:
-            type: string
-            enum:
-              - auto
-              - manual
-              - random
-              - round_robin
-              - custom
-            default: auto
-            description: "Method for selecting next speaker"
-          custom_speaker_selection_func:
-            type: string
-            description: "Reference to custom speaker selection function"
-          allow_repeat_speaker:
-            oneOf:
-              - type: boolean
-              - type: array
-                items:
-                  type: string
-            default: true
-            description: "Allow same speaker consecutive turns"
-          send_introductions:
-            type: boolean
-            default: false
-            description: "Send agent introductions at start"
-
-      function_map:
-        type: object
-        description: "Mapping of function names to implementations"
-        additionalProperties:
-          type: string
-          description: "Function reference (module.function or class.method)"
-
-      register_for_llm:
-        type: array
-        description: "Functions registered for LLM to call (tool definitions)"
-        items:
-          type: object
-          properties:
-            name:
-              type: string
-              description: "Function name"
-            description:
-              type: string
-              description: "Function description for LLM"
-            parameters:
-              $ref: "#/definitions/JSONSchemaDefinition"
-              description: "Function parameter schema"
-
-      register_for_execution:
-        type: array
-        description: "Functions registered for execution by this agent"
-        items:
-          type: string
-          description: "Function name that this agent can execute"
-
-      nested_chat_config:
-        type: object
-        description: "Configuration for nested agent conversations"
-        properties:
-          enabled:
-            type: boolean
-            default: false
-            description: "Enable nested chat delegation"
-          inner_agents:
-            type: array
-            description: "Agents that can be delegated to"
-            items:
-              type: object
-              properties:
-                agent_ref:
-                  type: string
-                  description: "Reference to inner OSSA agent"
-                trigger:
-                  type: string
-                  description: "Trigger condition for delegation"
-                max_turns:
-                  type: integer
-                  description: "Max turns for nested conversation"
-          message_transformer:
-            type: string
-            description: "Function to transform messages between outer/inner chats"
-
-      system_message:
-        type: string
-        description: "System message/prompt for the agent (maps to OSSA spec.instructions)"
-
-      description:
-        type: string
-        description: "Short description for speaker selection in group chat"
-
-      teachability_config:
-        type: object
-        description: "Configuration for TeachableAgent learning capabilities"
-        properties:
-          enabled:
-            type: boolean
-            default: false
-          verbosity:
-            type: integer
-            minimum: 0
-            maximum: 3
-            default: 0
-          reset_db:
-            type: boolean
-            default: false
-          path_to_db_dir:
-            type: string
-            description: "Path to teachability database"
-          recall_threshold:
-            type: number
-            minimum: 0
-            maximum: 1
-            default: 1.5
-```
-
-## Bidirectional Mapping Tables
-
-### AutoGen Agent Types to OSSA
-
-| AutoGen Type | OSSA Kind | OSSA Spec Fields | Notes |
-|-------------|-----------|------------------|-------|
-| `ConversableAgent` | `Agent` | `spec.model`, `spec.instructions` | Base agent with LLM and messaging |
-| `AssistantAgent` | `Agent` | `spec.model`, `spec.capabilities` | LLM-powered assistant with tools |
-| `UserProxyAgent` | `Agent` | `spec.humanInLoop.enabled: true` | Human-in-the-loop agent |
-| `GroupChatManager` | `Workflow` | `spec.orchestration`, `spec.steps` | Multi-agent orchestrator |
-| `TeachableAgent` | `Agent` | `spec.memory.type: "vector"` | Agent with learning capability |
-| `ReasoningAgent` | `Agent` | `spec.model.reasoning: true` | Agent with chain-of-thought |
-| `CaptainAgent` | `Agent` | `spec.delegation.enabled: true` | Agent that spawns sub-agents |
-
-### OSSA to AutoGen Mapping
-
-| OSSA Concept | AutoGen Equivalent | Mapping |
-|-------------|-------------------|---------|
-| `spec.model.provider` | `llm_config.config_list[].api_type` | Direct mapping |
-| `spec.model.name` | `llm_config.config_list[].model` | Direct mapping |
-| `spec.instructions` | `system_message` | Full prompt text |
-| `spec.capabilities` | `register_for_llm` + `function_map` | Tool definitions |
-| `spec.humanInLoop.enabled` | `human_input_mode: ALWAYS` | When true |
-| `spec.humanInLoop.triggers` | `is_termination_msg` | Custom termination logic |
-| `spec.sandboxConfig` | `code_execution_config` | Execution sandbox |
-| `spec.orchestration.pattern` | `speaker_selection_method` | Group chat selection |
-| `spec.steps` | `group_chat_config.agents` | Agent sequence |
-| `spec.delegation` | `nested_chat_config` | Agent delegation |
-| `spec.memory.type: "vector"` | `teachability_config` | Learning memory |
-
-### Capability Mapping
-
-| OSSA Capability | AutoGen Feature | Implementation |
-|-----------------|-----------------|----------------|
-| `code_execution` | `code_execution_config` | Enable with work_dir |
-| `file_access` | `work_dir` + permissions | Sandbox directory |
-| `tool_call` | `register_for_llm` | Function registration |
-| `human_approval` | `human_input_mode: TERMINATE` | Terminate for approval |
-| `agent_delegation` | `nested_chat_config` | Inner agent calls |
-| `memory_persistence` | `teachability_config` | Vector DB storage |
-
-### Access Tier Mapping
-
-| OSSA Access Tier | AutoGen Pattern | Recommended Config |
-|------------------|-----------------|-------------------|
-| `tier_1_read` | `AssistantAgent` | `code_execution_config: false` |
-| `tier_2_write_limited` | `AssistantAgent` | `use_docker: true`, limited tools |
-| `tier_3_write_elevated` | `UserProxyAgent` | `human_input_mode: TERMINATE` |
-| `tier_4_policy` | `GroupChatManager` | Speaker selection control |
-
-## Use Cases
-
-### 1. Basic Assistant Agent
-
-An OSSA agent mapped to AutoGen's AssistantAgent:
-
-```yaml
-apiVersion: ossa/v0.3.3
-kind: Agent
-metadata:
-  name: code-assistant
-  version: 1.0.0
-  description: "Helpful coding assistant"
-
-spec:
-  model:
-    provider: openai
-    name: gpt-4-turbo
-  instructions: |
-    You are a helpful coding assistant. You help users write, debug,
-    and explain code. Always provide clear explanations with your code.
-  capabilities:
-    - code_generation
-    - code_explanation
-    - debugging
-
-extensions:
-  autogen:
-    agent_type: assistant_agent
-    llm_config:
-      config_list:
-        - model: gpt-4-turbo
-          api_key_env: OPENAI_API_KEY
-      temperature: 0.7
-    human_input_mode: NEVER
-    max_consecutive_auto_reply: 10
-    system_message: |
-      You are a helpful coding assistant. You help users write, debug,
-      and explain code. Always provide clear explanations with your code.
-```
-
-### 2. User Proxy Agent with Code Execution
-
-An OSSA agent with human-in-the-loop and code execution:
-
-```yaml
-apiVersion: ossa/v0.3.3
-kind: Agent
-metadata:
-  name: code-executor
-  version: 1.0.0
-  description: "User proxy that executes code in sandbox"
-
-spec:
-  model:
-    provider: none
-  instructions: "Execute code provided by other agents"
-  humanInLoop:
-    enabled: true
-    triggers:
-      - "before_execution"
-      - "on_error"
-  sandboxConfig:
-    enabled: true
-    type: docker
-    image: python:3.11-slim
-
-extensions:
-  autogen:
-    agent_type: user_proxy_agent
-    human_input_mode: TERMINATE
-    code_execution_config:
-      work_dir: workspace
-      use_docker: python:3.11-slim
-      timeout: 120
-      last_n_messages: 3
-      executor_type: docker_command_line
-      allowed_languages:
-        - python
-        - bash
-    max_consecutive_auto_reply: 0
-    termination_config:
-      termination_keywords:
-        - TERMINATE
-        - TASK_COMPLETE
-```
-
-### 3. Group Chat with Manager
-
-An OSSA Workflow implementing AutoGen GroupChat:
-
-```yaml
-apiVersion: ossa/v0.3.3
-kind: Workflow
-metadata:
-  name: research-team
-  version: 1.0.0
-  description: "Multi-agent research team with manager"
-
-spec:
-  orchestration:
-    pattern: group_chat
-    manager: research-manager
-  steps:
-    - name: researcher
-      agentRef: research-agent
-    - name: critic
-      agentRef: critic-agent
-    - name: writer
-      agentRef: writer-agent
-  output:
-    type: aggregated
-    format: markdown
-
-extensions:
-  autogen:
-    agent_type: group_chat_manager
-    group_chat_config:
-      agents:
-        - research-agent
-        - critic-agent
-        - writer-agent
-      max_round: 20
-      admin_name: research-manager
-      speaker_selection_method: auto
-      allow_repeat_speaker: false
-      send_introductions: true
-    llm_config:
-      config_list:
-        - model: gpt-4-turbo
-          api_key_env: OPENAI_API_KEY
-      temperature: 0.3
-    termination_config:
-      termination_keywords:
-        - RESEARCH_COMPLETE
-        - TERMINATE
-      max_turns: 50
-```
-
-### 4. Agent with Function Calling
-
-An OSSA agent with registered tools/functions:
-
-```yaml
-apiVersion: ossa/v0.3.3
-kind: Agent
-metadata:
-  name: data-analyst
-  version: 1.0.0
-  description: "Data analysis agent with database access"
-
-spec:
-  model:
-    provider: openai
-    name: gpt-4-turbo
-  instructions: |
-    You are a data analyst. Use the provided tools to query databases
-    and analyze data. Always explain your findings.
-  capabilities:
-    - query_database
-    - analyze_data
-    - generate_report
-
-extensions:
-  autogen:
-    agent_type: assistant_agent
-    llm_config:
-      config_list:
-        - model: gpt-4-turbo
-          api_key_env: OPENAI_API_KEY
-      temperature: 0.2
-    register_for_llm:
-      - name: query_database
-        description: "Execute SQL query on the analytics database"
-        parameters:
-          type: object
-          properties:
-            query:
-              type: string
-              description: "SQL query to execute"
-            database:
-              type: string
-              enum: [analytics, reporting, warehouse]
-              description: "Target database"
-          required: [query, database]
-      - name: analyze_data
-        description: "Perform statistical analysis on a dataset"
-        parameters:
-          type: object
-          properties:
-            data_path:
-              type: string
-              description: "Path to data file"
-            analysis_type:
-              type: string
-              enum: [descriptive, correlation, regression]
-          required: [data_path, analysis_type]
-    function_map:
-      query_database: "data_tools.database.execute_query"
-      analyze_data: "data_tools.analysis.run_analysis"
-    register_for_execution:
-      - query_database
-      - analyze_data
-```
-
-### 5. Nested Chat / Delegation Pattern
-
-An OSSA agent that delegates to specialized sub-agents:
-
-```yaml
-apiVersion: ossa/v0.3.3
-kind: Agent
-metadata:
-  name: project-coordinator
-  version: 1.0.0
-  description: "Coordinator that delegates to specialized agents"
-
-spec:
-  model:
-    provider: openai
-    name: gpt-4-turbo
-  instructions: |
-    You coordinate complex projects by delegating tasks to specialized agents.
-    Break down requests and route to appropriate specialists.
-  delegation:
-    enabled: true
-    targets:
-      - frontend-specialist
-      - backend-specialist
-      - devops-specialist
-
-extensions:
-  autogen:
-    agent_type: assistant_agent
-    llm_config:
-      config_list:
-        - model: gpt-4-turbo
-          api_key_env: OPENAI_API_KEY
-    nested_chat_config:
-      enabled: true
-      inner_agents:
-        - agent_ref: frontend-specialist
-          trigger: "frontend|react|css|ui|ux"
-          max_turns: 10
-        - agent_ref: backend-specialist
-          trigger: "backend|api|database|server"
-          max_turns: 10
-        - agent_ref: devops-specialist
-          trigger: "deploy|ci|cd|docker|kubernetes"
-          max_turns: 10
-      message_transformer: "delegation.transform_context"
-```
-
-### 6. Teachable Agent with Memory
-
-An OSSA agent that learns from interactions:
-
-```yaml
-apiVersion: ossa/v0.3.3
-kind: Agent
-metadata:
-  name: learning-assistant
-  version: 1.0.0
-  description: "Agent that learns and remembers user preferences"
-
-spec:
-  model:
-    provider: openai
-    name: gpt-4-turbo
-  instructions: |
-    You are a helpful assistant that learns from our conversations.
-    Remember user preferences and apply them to future interactions.
-  memory:
-    type: vector
-    provider: chromadb
-    config:
-      collection: user_preferences
-      persist_directory: ./teachable_db
-
-extensions:
-  autogen:
-    agent_type: teachable_agent
-    llm_config:
-      config_list:
-        - model: gpt-4-turbo
-          api_key_env: OPENAI_API_KEY
-    teachability_config:
-      enabled: true
-      verbosity: 1
-      reset_db: false
-      path_to_db_dir: "./teachable_db"
-      recall_threshold: 1.5
-```
-
-### 7. Custom Speaker Selection Group Chat
-
-Advanced group chat with custom routing:
-
-```yaml
-apiVersion: ossa/v0.3.3
-kind: Workflow
-metadata:
-  name: review-pipeline
-  version: 1.0.0
-  description: "Code review pipeline with role-based routing"
-
-spec:
-  orchestration:
-    pattern: group_chat
-    selection: custom
-  steps:
-    - name: security-reviewer
-      agentRef: security-agent
-      tags: [security]
-    - name: performance-reviewer
-      agentRef: performance-agent
-      tags: [performance]
-    - name: style-reviewer
-      agentRef: style-agent
-      tags: [style]
-
-extensions:
-  autogen:
-    agent_type: group_chat_manager
-    group_chat_config:
-      agents:
-        - security-agent
-        - performance-agent
-        - style-agent
-      max_round: 15
-      speaker_selection_method: custom
-      custom_speaker_selection_func: "review_pipeline.select_reviewer"
-      allow_repeat_speaker:
-        - security-agent  # Security can speak multiple times
-      send_introductions: true
-    llm_config:
-      config_list:
-        - model: gpt-4-turbo
-          api_key_env: OPENAI_API_KEY
-      temperature: 0.1
-```
-
-## Conversion Functions
-
-### OSSA to AutoGen Python
-
-```python
-from autogen import ConversableAgent, AssistantAgent, UserProxyAgent, GroupChat, GroupChatManager
-import yaml
-
-def ossa_to_autogen(manifest_path: str):
-    """Convert OSSA manifest to AutoGen agent configuration."""
-    with open(manifest_path) as f:
-        manifest = yaml.safe_load(f)
-
-    autogen_ext = manifest.get('extensions', {}).get('autogen', {})
-    spec = manifest.get('spec', {})
-
-    agent_type = autogen_ext.get('agent_type', 'assistant_agent')
-
-    # Build llm_config
-    llm_config = autogen_ext.get('llm_config', {})
-    if not llm_config and spec.get('model'):
-        llm_config = {
-            'config_list': [{
-                'model': spec['model'].get('name', 'gpt-4'),
-                'api_key': os.environ.get('OPENAI_API_KEY'),
-            }]
-        }
-
-    # Map agent type to class
-    agent_classes = {
-        'conversable_agent': ConversableAgent,
-        'assistant_agent': AssistantAgent,
-        'user_proxy_agent': UserProxyAgent,
-    }
-
-    AgentClass = agent_classes.get(agent_type, AssistantAgent)
-
-    # Build agent kwargs
-    kwargs = {
-        'name': manifest['metadata']['name'],
-        'llm_config': llm_config,
-        'system_message': autogen_ext.get('system_message', spec.get('instructions', '')),
-        'human_input_mode': autogen_ext.get('human_input_mode', 'NEVER'),
-        'max_consecutive_auto_reply': autogen_ext.get('max_consecutive_auto_reply', 10),
-    }
-
-    # Add code execution config for UserProxyAgent
-    if agent_type == 'user_proxy_agent':
-        code_exec = autogen_ext.get('code_execution_config', False)
-        kwargs['code_execution_config'] = code_exec
-
-    return AgentClass(**kwargs)
-```
-
-### AutoGen to OSSA Manifest
-
-```python
-def autogen_to_ossa(agent, version: str = "1.0.0") -> dict:
-    """Convert AutoGen agent to OSSA manifest."""
-    manifest = {
-        'apiVersion': 'ossa/v0.3.3',
-        'kind': 'Agent',
-        'metadata': {
-            'name': agent.name.lower().replace(' ', '-'),
-            'version': version,
-            'description': agent.description if hasattr(agent, 'description') else '',
-        },
-        'spec': {
-            'instructions': agent.system_message or '',
-        },
-        'extensions': {
-            'autogen': {
-                'human_input_mode': agent.human_input_mode,
-                'max_consecutive_auto_reply': agent.max_consecutive_auto_reply,
-            }
-        }
-    }
-
-    # Determine agent type
-    if isinstance(agent, UserProxyAgent):
-        manifest['extensions']['autogen']['agent_type'] = 'user_proxy_agent'
-        if agent.code_execution_config:
-            manifest['extensions']['autogen']['code_execution_config'] = agent.code_execution_config
-    elif isinstance(agent, AssistantAgent):
-        manifest['extensions']['autogen']['agent_type'] = 'assistant_agent'
-    else:
-        manifest['extensions']['autogen']['agent_type'] = 'conversable_agent'
-
-    # Add llm_config
-    if agent.llm_config:
-        # Sanitize - remove actual API keys
-        safe_config = {
-            'config_list': [
-                {k: v for k, v in config.items() if k != 'api_key'}
-                for config in agent.llm_config.get('config_list', [])
-            ],
-            'temperature': agent.llm_config.get('temperature'),
-        }
-        manifest['extensions']['autogen']['llm_config'] = safe_config
-
-        # Map to OSSA spec.model
-        if safe_config['config_list']:
-            manifest['spec']['model'] = {
-                'name': safe_config['config_list'][0].get('model'),
-                'provider': safe_config['config_list'][0].get('api_type', 'openai'),
-            }
-
-    return manifest
-```
-
-## OpenAPI Integration
-
-### AutoGen Agent Endpoint
-
-```yaml
-openapi: 3.1.0
-paths:
-  /api/v1/agents/autogen:
-    post:
-      operationId: createAutoGenAgent
-      summary: Create agent from AutoGen configuration
-      requestBody:
-        required: true
-        content:
-          application/json:
-            schema:
-              $ref: '#/components/schemas/AutoGenAgentRequest'
-      responses:
-        '201':
-          description: Agent created successfully
-          content:
-            application/json:
-              schema:
-                $ref: '#/components/schemas/OSSAManifest'
-
-  /api/v1/agents/{agentId}/autogen/export:
-    get:
-      operationId: exportToAutoGen
-      summary: Export OSSA agent as AutoGen configuration
-      parameters:
-        - name: agentId
-          in: path
-          required: true
-          schema:
-            type: string
-      responses:
-        '200':
-          description: AutoGen configuration
-          content:
-            application/json:
-              schema:
-                $ref: '#/components/schemas/AutoGenConfig'
-
-components:
-  schemas:
-    AutoGenAgentRequest:
-      type: object
-      required:
-        - name
-        - agent_type
-      properties:
-        name:
-          type: string
-        agent_type:
-          type: string
-          enum: [conversable_agent, assistant_agent, user_proxy_agent, group_chat_manager]
-        llm_config:
-          $ref: '#/components/schemas/LLMConfig'
-        human_input_mode:
-          type: string
-          enum: [ALWAYS, NEVER, TERMINATE]
-        code_execution_config:
-          $ref: '#/components/schemas/CodeExecutionConfig'
-
-    AutoGenConfig:
-      type: object
-      properties:
-        agent_type:
-          type: string
-        llm_config:
-          $ref: '#/components/schemas/LLMConfig'
-        human_input_mode:
-          type: string
-        code_execution_config:
-          $ref: '#/components/schemas/CodeExecutionConfig'
-        group_chat_config:
-          $ref: '#/components/schemas/GroupChatConfig'
-```
-
-## Zod Validation Schema
-
-```typescript
-import { z } from 'zod';
-
-export const LLMConfigSchema = z.object({
-  config_list: z.array(z.object({
-    model: z.string(),
-    api_key_env: z.string().regex(/^[A-Z][A-Z0-9_]*$/).optional(),
-    base_url: z.string().url().optional(),
-    api_type: z.enum(['openai', 'azure', 'anthropic', 'ollama', 'litellm']).optional(),
-    api_version: z.string().optional(),
-  })),
-  temperature: z.number().min(0).max(2).default(0.7),
-  timeout: z.number().int().min(1).default(600),
-  cache_seed: z.number().int().nullable().optional(),
-});
-
-export const CodeExecutionConfigSchema = z.union([
-  z.object({
-    work_dir: z.string().default('workspace'),
-    use_docker: z.union([z.boolean(), z.string()]).default(false),
-    timeout: z.number().int().min(1).default(60),
-    last_n_messages: z.number().int().min(1).default(1),
-    executor_type: z.enum([
-      'local_command_line',
-      'docker_command_line',
-      'jupyter',
-      'azure_container_instance'
-    ]).default('local_command_line'),
-    allowed_languages: z.array(
-      z.enum(['python', 'bash', 'shell', 'javascript', 'powershell'])
-    ).default(['python', 'bash']),
-  }),
-  z.literal(false),
-]);
-
-export const GroupChatConfigSchema = z.object({
-  agents: z.array(z.string()),
-  max_round: z.number().int().min(1).default(10),
-  admin_name: z.string().default('Admin'),
-  speaker_selection_method: z.enum([
-    'auto', 'manual', 'random', 'round_robin', 'custom'
-  ]).default('auto'),
-  custom_speaker_selection_func: z.string().optional(),
-  allow_repeat_speaker: z.union([
-    z.boolean(),
-    z.array(z.string())
-  ]).default(true),
-  send_introductions: z.boolean().default(false),
-});
-
-export const TerminationConfigSchema = z.object({
-  is_termination_msg: z.string().optional(),
-  termination_keywords: z.array(z.string()).default(['TERMINATE']),
-  max_turns: z.number().int().min(1).optional(),
-});
-
-export const NestedChatConfigSchema = z.object({
-  enabled: z.boolean().default(false),
-  inner_agents: z.array(z.object({
-    agent_ref: z.string(),
-    trigger: z.string(),
-    max_turns: z.number().int().optional(),
-  })).optional(),
-  message_transformer: z.string().optional(),
-});
-
-export const TeachabilityConfigSchema = z.object({
-  enabled: z.boolean().default(false),
-  verbosity: z.number().int().min(0).max(3).default(0),
-  reset_db: z.boolean().default(false),
-  path_to_db_dir: z.string().optional(),
-  recall_threshold: z.number().min(0).max(1).default(1.5),
-});
-
-export const AutoGenExtensionSchema = z.object({
-  agent_type: z.enum([
-    'conversable_agent',
-    'assistant_agent',
-    'user_proxy_agent',
-    'group_chat_manager',
-    'teachable_agent',
-    'reasoning_agent',
-    'captain_agent',
-    'custom_agent'
-  ]),
-  llm_config: LLMConfigSchema.optional(),
-  human_input_mode: z.enum(['ALWAYS', 'NEVER', 'TERMINATE']).default('NEVER'),
-  code_execution_config: CodeExecutionConfigSchema.optional(),
-  max_consecutive_auto_reply: z.number().int().min(0).default(10),
-  termination_config: TerminationConfigSchema.optional(),
-  group_chat_config: GroupChatConfigSchema.optional(),
-  function_map: z.record(z.string()).optional(),
-  register_for_llm: z.array(z.object({
-    name: z.string(),
-    description: z.string(),
-    parameters: z.record(z.unknown()),
-  })).optional(),
-  register_for_execution: z.array(z.string()).optional(),
-  nested_chat_config: NestedChatConfigSchema.optional(),
-  system_message: z.string().optional(),
-  description: z.string().optional(),
-  teachability_config: TeachabilityConfigSchema.optional(),
-});
-
-// Validate AutoGen extension
-export function validateAutoGenExtension(data: unknown) {
-  return AutoGenExtensionSchema.safeParse(data);
-}
-```
-
-## Human Input Modes
-
-### `ALWAYS`
-
-Human input is requested after every agent response:
-
-```
-Agent receives message -> Agent responds -> WAIT for human input -> Repeat
-```
-
-Use case: Interactive tutoring, sensitive operations requiring approval.
-
-### `NEVER`
-
-Fully autonomous operation - no human input requested:
-
-```
-Agent receives message -> Agent responds -> Continue automatically
-```
-
-Use case: Automated pipelines, background processing.
-
-### `TERMINATE`
-
-Human input requested only on termination conditions:
-
-```
-Agent receives message -> Agent responds -> Check termination -> If terminate: WAIT for human
-```
-
-Use case: Human approval for final results, error handling.
-
-## Code Execution Security
-
-### Docker Isolation (Recommended)
-
-```yaml
-code_execution_config:
-  use_docker: python:3.11-slim
-  timeout: 60
-  allowed_languages:
-    - python
-```
-
-Docker provides:
-- File system isolation
-- Network isolation (configurable)
-- Resource limits
-- Clean environment per execution
-
-### Local Execution (Development Only)
-
-```yaml
-code_execution_config:
-  use_docker: false
-  work_dir: ./sandbox
-  timeout: 30
-```
-
-**Warning**: Local execution can access host system. Use only in trusted environments.
-
-### OSSA Sandbox Mapping
-
-| OSSA sandboxConfig | AutoGen Equivalent |
-|-------------------|-------------------|
-| `type: docker` | `use_docker: true` |
-| `image: python:3.11` | `use_docker: "python:3.11"` |
-| `timeout: 60` | `timeout: 60` |
-| `network: none` | Docker network config |
-| `memory_limit: "512m"` | Docker resource config |
-
-## Integration Patterns
-
-### Pattern 1: Two-Agent Conversation
-
-```python
-# OSSA defines agents, AutoGen runs conversation
-assistant = ossa_to_autogen('assistant.ossa.yaml')
-user_proxy = ossa_to_autogen('user_proxy.ossa.yaml')
-
-user_proxy.initiate_chat(
-    assistant,
-    message="Write a Python function to calculate fibonacci numbers"
-)
-```
-
-### Pattern 2: Group Chat Workflow
-
-```python
-# OSSA Workflow -> AutoGen GroupChat
-workflow = load_ossa_workflow('research-team.ossa.yaml')
-agents = [ossa_to_autogen(ref) for ref in workflow.spec.steps]
-
-groupchat = GroupChat(
-    agents=agents,
-    **workflow.extensions.autogen.group_chat_config
-)
-manager = GroupChatManager(groupchat=groupchat)
-```
-
-### Pattern 3: Nested Delegation
-
-```python
-# Coordinator delegates to specialists via nested chat
-coordinator = ossa_to_autogen('coordinator.ossa.yaml')
-specialists = {
-    'frontend': ossa_to_autogen('frontend.ossa.yaml'),
-    'backend': ossa_to_autogen('backend.ossa.yaml'),
-}
-
-# Register nested chat handlers
-for name, agent in specialists.items():
-    coordinator.register_nested_chats(
-        trigger=lambda x: name in x['content'].lower(),
-        chat_queue=[agent],
-    )
-```
-
-## Related
-
-- [Microsoft AutoGen Documentation](https://microsoft.github.io/autogen/)
-- [AutoGen GitHub Repository](https://github.com/microsoft/autogen)
-- [OSSA v0.3.3 Schema](../ossa-0.3.3.schema.json)
-- [Agent-to-Agent Messaging Extension](./agent-identity.yaml)
-- [Drupal Extension](./drupal.md)
-- [MCP Extension](#/definitions/MCPExtension)