Add agent framework API router and service skeletons

Introduces the main FastAPI router for agent framework v3, including endpoints for team management, plan creation, approval, agent messaging, and configuration upload. Adds callback handlers for agent responses and streaming, global debug access, and service skeletons for agents, base API, foundry, MCP, and team management. These files establish the backend structure for multi-agent orchestration and extensible service integration.

Author: Fr4nc3

src/backend/af/__init__.py

@@ -0,0 +1 @@
+# Callbacks package for handling agent responses and streaming

src/backend/af/api/router.py

@@ -0,0 +1,14 @@
+class DebugGlobalAccess:
+    """Class to manage global access to the Magentic orchestration manager."""
+
+    _managers = []
+
+    @classmethod
+    def add_manager(cls, manager):
+        """Add a new manager to the global list."""
+        cls._managers.append(manager)
+
+    @classmethod
+    def get_managers(cls):
+        """Get the list of all managers."""
+        return cls._managers

src/backend/af/callbacks/__init__.py

@@ -0,0 +1,206 @@
+"""
+Agent Framework response callbacks for employee onboarding / multi-agent system.
+Replaces Semantic Kernel message types with agent_framework ChatResponseUpdate handling.
+"""
+
+import asyncio
+import json
+import logging
+import re
+import time
+from typing import Optional
+
+from agent_framework import (
+    ChatResponseUpdate,
+    FunctionCallContent,
+    UsageContent,
+    Role,
+    TextContent,
+)
+
+from af.config.settings import connection_config
+from af.models.messages import (
+    AgentMessage,
+    AgentMessageStreaming,
+    AgentToolCall,
+    AgentToolMessage,
+    WebsocketMessageType,
+)
+
+logger = logging.getLogger(__name__)
+
+
+# ---------------------------------------------------------------------------
+# Utility
+# ---------------------------------------------------------------------------
+
+_CITATION_PATTERNS = [
+    (r"\[\d+:\d+\|source\]", ""),        # [9:0|source]
+    (r"\[\s*source\s*\]", ""),           # [source]
+    (r"\[\d+\]", ""),                    # [12]
+    (r"【[^】]*】", ""),                  # Unicode bracket citations
+    (r"\(source:[^)]*\)", ""),           # (source: xyz)
+    (r"\[source:[^\]]*\]", ""),          # [source: xyz]
+]
+
+
+def clean_citations(text: str) -> str:
+    """Remove citation markers from agent responses while preserving formatting."""
+    if not text:
+        return text
+    for pattern, repl in _CITATION_PATTERNS:
+        text = re.sub(pattern, repl, text, flags=re.IGNORECASE)
+    return text
+
+
+def _parse_function_arguments(arg_value: Optional[str | dict]) -> dict:
+    """Best-effort parse for function call arguments (stringified JSON or dict)."""
+    if arg_value is None:
+        return {}
+    if isinstance(arg_value, dict):
+        return arg_value
+    if isinstance(arg_value, str):
+        try:
+            return json.loads(arg_value)
+        except Exception:  # noqa: BLE001
+            return {"raw": arg_value}
+    return {"raw": str(arg_value)}
+
+
+# ---------------------------------------------------------------------------
+# Core handlers
+# ---------------------------------------------------------------------------
+
+def agent_framework_update_callback(
+    update: ChatResponseUpdate,
+    user_id: Optional[str] = None,
+) -> None:
+    """
+    Handle a non-streaming perspective of updates (tool calls, intermediate steps, final usage).
+    This can be called for each ChatResponseUpdate; it will route tool calls and standard text
+    messages to WebSocket.
+    """
+    agent_name = getattr(update, "model_id", None) or "Agent"
+    # Use Role or fallback
+    role = getattr(update, "role", Role.ASSISTANT)
+
+    # Detect tool/function calls
+    function_call_contents = [
+        c for c in (update.contents or [])
+        if isinstance(c, FunctionCallContent)
+    ]
+
+    if user_id is None:
+        return
+
+    try:
+        if function_call_contents:
+            # Build tool message
+            tool_message = AgentToolMessage(agent_name=agent_name)
+            for fc in function_call_contents:
+                args = _parse_function_arguments(getattr(fc, "arguments", None))
+                tool_message.tool_calls.append(
+                    AgentToolCall(
+                        tool_name=getattr(fc, "name", "unknown_tool"),
+                        arguments=args,
+                    )
+                )
+            asyncio.create_task(
+                connection_config.send_status_update_async(
+                    tool_message,
+                    user_id,
+                    message_type=WebsocketMessageType.AGENT_TOOL_MESSAGE,
+                )
+            )
+            logger.info("Function call(s) dispatched: %s", tool_message)
+            return
+
+        # Ignore pure usage or empty updates (handled as final in streaming handler)
+        if any(isinstance(c, UsageContent) for c in (update.contents or [])):
+            # We'll treat this as a final token accounting event; no standard message needed.
+            logger.debug("UsageContent received (final accounting); skipping text dispatch.")
+            return
+
+        # Standard assistant/user message (non-stream delta)
+        if update.text:
+            final_message = AgentMessage(
+                agent_name=agent_name,
+                timestamp=str(time.time()),
+                content=clean_citations(update.text),
+            )
+            asyncio.create_task(
+                connection_config.send_status_update_async(
+                    final_message,
+                    user_id,
+                    message_type=WebsocketMessageType.AGENT_MESSAGE,
+                )
+            )
+            logger.info("%s message: %s", role.name.capitalize(), final_message)
+
+    except Exception as e:  # noqa: BLE001
+        logger.error("agent_framework_update_callback: Error sending WebSocket message: %s", e)
+
+
+async def streaming_agent_framework_callback(
+    update: ChatResponseUpdate,
+    user_id: Optional[str] = None,
+) -> None:
+    """
+    Handle streaming deltas. For each update with text, forward a streaming message.
+    Mark is_final=True when a UsageContent is observed (end of run).
+    """
+    if user_id is None:
+        return
+
+    try:
+        # Determine if this update marks the end
+        is_final = any(isinstance(c, UsageContent) for c in (update.contents or []))
+
+        # Streaming text can appear either in update.text or inside TextContent entries.
+        pieces: list[str] = []
+        if update.text:
+            pieces.append(update.text)
+        # Some events may provide TextContent objects without setting update.text
+        for c in (update.contents or []):
+            if isinstance(c, TextContent) and getattr(c, "text", None):
+                pieces.append(c.text)
+
+        if not pieces:
+            return
+
+        streaming_message = AgentMessageStreaming(
+            agent_name=getattr(update, "model_id", None) or "Agent",
+            content=clean_citations("".join(pieces)),
+            is_final=is_final,
+        )
+
+        await connection_config.send_status_update_async(
+            streaming_message,
+            user_id,
+            message_type=WebsocketMessageType.AGENT_MESSAGE_STREAMING,
+        )
+
+        if is_final:
+            logger.info("Final streaming chunk sent for agent '%s'", streaming_message.agent_name)
+
+    except Exception as e:  # noqa: BLE001
+        logger.error("streaming_agent_framework_callback: Error sending streaming WebSocket message: %s", e)
+
+
+# ---------------------------------------------------------------------------
+# Convenience wrappers (optional)
+# ---------------------------------------------------------------------------
+
+def handle_update(update: ChatResponseUpdate, user_id: Optional[str]) -> None:
+    """
+    Unified entry point if caller doesn't distinguish streaming vs non-streaming.
+    You can call this once per update. It will:
+    - Forward streaming text increments
+    - Forward tool calls
+    - Skip purely usage-only events (except marking final in streaming)
+    """
+    # Send streaming chunk first (async context)
+    asyncio.create_task(streaming_agent_framework_callback(update, user_id))
+    # Then send non-stream items (tool calls or discrete messages)
+    agent_framework_update_callback(update, user_id)
+

src/backend/af/callbacks/global_debug.py

@@ -0,0 +1,19 @@
+"""Service abstractions for v3.
+
+Exports:
+- BaseAPIService: minimal async HTTP wrapper using endpoints from AppConfig
+- MCPService: service targeting a local/remote MCP server
+- FoundryService: helper around Azure AI Foundry (AIProjectClient)
+"""
+
+from .agents_service import AgentsService
+from .base_api_service import BaseAPIService
+from .foundry_service import FoundryService
+from .mcp_service import MCPService
+
+__all__ = [
+    "BaseAPIService",
+    "MCPService",
+    "FoundryService",
+    "AgentsService",
+]

src/backend/af/callbacks/response_handlers.py

@@ -0,0 +1,121 @@
+"""
+AgentsService (skeleton)
+
+Lightweight service that receives a TeamService instance and exposes helper
+methods to convert a TeamConfiguration into a list/array of agent descriptors.
+
+This is intentionally a simple skeleton — the user will later provide the
+implementation that wires these descriptors into Semantic Kernel / Foundry
+agent instances.
+"""
+
+import logging
+from typing import Any, Dict, List, Union
+
+from common.models.messages_kernel import TeamAgent, TeamConfiguration
+from v3.common.services.team_service import TeamService
+
+
+class AgentsService:
+    """Service for building agent descriptors from a team configuration.
+
+    Responsibilities (skeleton):
+    - Receive a TeamService instance on construction (can be used for validation
+      or lookups when needed).
+    - Expose a method that accepts a TeamConfiguration (or raw dict) and
+      returns a list of agent descriptors. Descriptors are plain dicts that
+      contain the fields required to later instantiate runtime agents.
+
+    The concrete instantiation logic (semantic kernel / foundry) is intentionally
+    left out and should be implemented by the user later (see
+    `instantiate_agents` placeholder).
+    """
+
+    def __init__(self, team_service: TeamService):
+        self.team_service = team_service
+        self.logger = logging.getLogger(__name__)
+
+    async def get_agents_from_team_config(
+        self, team_config: Union[TeamConfiguration, Dict[str, Any]]
+    ) -> List[Dict[str, Any]]:
+        """Return a list of lightweight agent descriptors derived from a
+        TeamConfiguration or a raw dict.
+
+        Each descriptor contains the basic fields from the team config and a
+        placeholder where a future runtime/agent object can be attached.
+
+        Args:
+            team_config: TeamConfiguration model instance or a raw dict
+
+        Returns:
+            List[dict] -- each dict contains keys like:
+                - input_key, type, name, system_message, description, icon,
+                  index_name, agent_obj (placeholder)
+        """
+        if not team_config:
+            return []
+
+        # Accept either the pydantic TeamConfiguration or a raw dictionary
+        if hasattr(team_config, "agents"):
+            agents_raw = team_config.agents or []
+        elif isinstance(team_config, dict):
+            agents_raw = team_config.get("agents", [])
+        else:
+            # Unknown type; try to coerce to a list
+            try:
+                agents_raw = list(team_config)
+            except Exception:
+                agents_raw = []
+
+        descriptors: List[Dict[str, Any]] = []
+        for a in agents_raw:
+            if isinstance(a, TeamAgent):
+                desc = {
+                    "input_key": a.input_key,
+                    "type": a.type,
+                    "name": a.name,
+                    "system_message": getattr(a, "system_message", ""),
+                    "description": getattr(a, "description", ""),
+                    "icon": getattr(a, "icon", ""),
+                    "index_name": getattr(a, "index_name", ""),
+                    "use_rag": getattr(a, "use_rag", False),
+                    "use_mcp": getattr(a, "use_mcp", False),
+                    "coding_tools": getattr(a, "coding_tools", False),
+                    # Placeholder for later wiring to a runtime/agent instance
+                    "agent_obj": None,
+                }
+            elif isinstance(a, dict):
+                desc = {
+                    "input_key": a.get("input_key"),
+                    "type": a.get("type"),
+                    "name": a.get("name"),
+                    "system_message": a.get("system_message") or a.get("instructions"),
+                    "description": a.get("description"),
+                    "icon": a.get("icon"),
+                    "index_name": a.get("index_name"),
+                    "use_rag": a.get("use_rag", False),
+                    "use_mcp": a.get("use_mcp", False),
+                    "coding_tools": a.get("coding_tools", False),
+                    "agent_obj": None,
+                }
+            else:
+                # Fallback: keep raw object for later introspection
+                desc = {"raw": a, "agent_obj": None}
+
+            descriptors.append(desc)
+
+        return descriptors
+
+    async def instantiate_agents(self, agent_descriptors: List[Dict[str, Any]]):
+        """Placeholder for instantiating runtime agent objects from descriptors.
+
+        The real implementation should create Semantic Kernel / Foundry agents
+        and attach them to each descriptor under the key `agent_obj` or return a
+        list of instantiated agents.
+
+        Raises:
+            NotImplementedError -- this is only a skeleton.
+        """
+        raise NotImplementedError(
+            "Agent instantiation is not implemented in the skeleton"
+        )