Multi-Agent Foundation Models Demo

This project demonstrates the advanced capabilities of Apple's Foundation Models framework, specifically showcasing how to use tool calling to create multi-agent LLM architectures. The system includes two distinct modes: Normal (direct LLM interaction) and Agentic (multi-agent orchestration).

Architecture Overview

The system implements two distinct architectures that showcase different LLM capabilities:

1. Normal Mode

Direct LLM interaction without orchestration:

• Simple prompt → response flow
• Useful for baseline comparison with the multi-agent approaches
• Full call history tracking for performance analysis

2. Agentic Mode

A coordinator-based architecture where a root LLM orchestrates tasks between specialized sub-agents:

1. Coordinator Agent - The main orchestrator that manages the flow between agents
2. Planner Agent - Breaks down complex tasks into manageable subtasks
3. Worker Agent - Executes individual subtasks (can run multiple instances in parallel)
4. Synthesizer Agent - Combines all worker outputs into a coherent final result

Key Features

Tool Calling

• Each agent is implemented as a Tool conforming to the Foundation Models Tool protocol
• Tools use @Generable for structured input/output with guided generation
• The coordinator can call multiple worker tools in parallel for efficient execution

Guided Generation

• Uses @Guide annotations to constrain parameters (ranges, values, maximum counts)
• Structured output formats ensure consistent agent communication
• Type-safe argument passing between agents

Error Handling

• Comprehensive error handling with custom AgentError types
• Graceful degradation when models are unavailable
• Detailed error reporting through the transcript system

UI Features

• Execute Tab: Input tasks and view results with mode selection (Normal, Agentic)
• History Tab: Hierarchical view of all LLM calls with parent-child relationships
• Model Info Tab: System status and architecture overview

Implementation Details

Agentic Mode Tools

• PlannerTool (task_planner): Takes a task description and breaks it into subtasks with dependencies
• WorkerTool (task_worker): Executes individual subtasks with time tracking
• SynthesizerTool (result_synthesizer): Combines worker results with quality scoring and insights

Response Types

All response types use @Generable for structured generation:

• Agentic Mode: TaskPlan, WorkerResult, SynthesisResult

Requirements

• macOS 26.0+ or iOS 26.0+
• Device with Apple Intelligence support
• Apple Intelligence enabled in Settings
• Xcode 26.0+

Usage

1. Open the app and ensure the model status shows "Available"
2. Select a mode using the segmented control:
   • Normal Mode: Direct LLM response (default)
   • Agentic Mode: Multi-agent orchestration
3. Enter a task description in the main interface
4. Click "Execute Task" to see the selected architecture in action
5. View the History tab to see the hierarchical call structure

Example Tasks

• "Explain quantum-computing"
• "What is recursion in programming?"
• "Create a plan for a trip to Morocco"

Technical Highlights

This implementation demonstrates:

• Tool protocol implementation with async/await
• Concurrent tool execution capabilities
• Session management with role-specific instructions
• Call hierarchy tracking for debugging
• SwiftUI integration with ObservableObject agents
• Mode switching between two different architectures
• Tools as LLM instances (not just function calls)
• Structured output parsing with fallback handling
• Comparison framework for evaluating different approaches