Skip to content

Foundation Developer Guide

This guide is for developers who want to work with the Amplifier foundation - the core kernel, libraries, and architectural components that power all Amplifier applications.

Who This Guide Is For

This guide is for you if you want to:

  • ✅ Build applications using amplifier-core (like building your own CLI, web UI, or automation tool)
  • ✅ Contribute to amplifier-core, amplifier-profiles, or other foundation libraries
  • ✅ Understand the kernel internals and how the foundation works
  • ✅ Use libraries (profiles, collections, config, module-resolution) in your applications

Not What You're Looking For?

Understanding the Architecture

Amplifier is built in layers, inspired by the Linux kernel model:

┌─────────────────────────────────────────────┐
│        Applications Layer                   │
│  (amplifier-app-cli, your-app, etc.)       │
│                                             │
│  • User interaction                         │
│  • Configuration resolution                 │
│  • Mount Plan creation                      │
│  • Uses libraries                           │
└──────────────┬──────────────────────────────┘
               │
               ▼
┌──────────────────────────────────────────────┐
│        Libraries Layer                       │
│  (amplifier-profiles, amplifier-collections, │
│   amplifier-config, amplifier-module-resolution) │
│                                              │
│  • Profile loading & inheritance            │
│  • Configuration management                 │
│  • Module resolution strategies             │
│  • NOT used by runtime modules              │
└──────────────┬───────────────────────────────┘
               │
               ▼
┌──────────────────────────────────────────────┐
│        Kernel Layer                          │
│  (amplifier-core ~2,600 lines)              │
│                                              │
│  • Session lifecycle                         │
│  • Mount Plan validation                     │
│  • Module discovery and loading             │
│  • Event emission                            │
│  • Coordinator infrastructure               │
│  • Mechanism, not policy                    │
└──────────────┬───────────────────────────────┘
               │
               ▼
┌──────────────────────────────────────────────┐
│        Modules Layer                         │
│  (providers, tools, orchestrators, contexts, │
│   hooks - loaded at runtime)                │
│                                              │
│  • Only depend on amplifier-core            │
│  • Implement specific capabilities          │
│  • Swappable at runtime                     │
└──────────────────────────────────────────────┘

Key Principle: Separation of Concerns

  • Kernel (amplifier-core): Provides mechanisms, not policy. Small, stable, boring.
  • Libraries: Application-layer concerns. Profile loading, config resolution, etc.
  • Applications: Build on kernel + libraries. Decide what gets loaded and when.
  • Modules: Extend capabilities. No dependencies on libraries.

Foundation Components

amplifier-core (The Kernel)

The heart of Amplifier. ~2,600 lines of mechanism-only code.

What it does: - Validates and loads Mount Plans - Manages session lifecycle - Emits canonical events - Provides coordinator infrastructure - Enforces contracts

What it doesn't do: - Choose which modules to load (applications do this) - Format output (applications do this) - Decide execution strategy (orchestrator modules do this) - Store configuration (libraries do this)

Repository: microsoft/amplifier-core

amplifier-profiles

Profile loading with inheritance and @mention support.

What it does: - Load profiles from multiple sources - Handle profile inheritance and overlays - Compile profiles to Mount Plans - Resolve @mentions in configuration

Used by: Applications (not modules)

Repository: microsoft/amplifier-profiles

amplifier-collections

Collection discovery and management.

What it does: - Discover collections from conventional locations - Load profiles, agents, and context from collections - @mention resolution for collection resources

Used by: Applications (not modules)

Repository: microsoft/amplifier-collections

amplifier-config

Three-scope configuration management.

What it does: - User scope: ~/.amplifier/settings.yaml - Project scope: .amplifier/settings.yaml - Local scope: .amplifier/settings.local.yaml - Deep merge semantics - Environment variable resolution

Used by: Applications (not modules)

Repository: microsoft/amplifier-config

amplifier-module-resolution

Module source resolution strategies.

What it does: - Resolve module IDs to sources - Git repository resolution - File path resolution - Package resolution - Source override management

Used by: Applications (not modules)

Repository: microsoft/amplifier-module-resolution

Quick Start: Using amplifier-core

Here's a minimal example of using amplifier-core directly:

from amplifier_core import AmplifierSession

# Define a Mount Plan
mount_plan = {
    "session": {
        "orchestrator": "loop-basic",
        "context": "context-simple"
    },
    "providers": [
        {
            "module": "provider-anthropic",
            "source": "git+https://github.com/microsoft/amplifier-module-provider-anthropic@main",
            "config": {
                "default_model": "claude-sonnet-4-5"
            }
        }
    ],
    "tools": [
        {
            "module": "tool-bash",
            "source": "git+https://github.com/microsoft/amplifier-module-tool-bash@main"
        }
    ]
}

# Create and use a session
async with AmplifierSession(mount_plan) as session:
    # Execute a prompt
    response = await session.execute("What is 2 + 2?")
    print(response)

That's it! The kernel handles: - Validating the mount plan - Loading the modules - Coordinating the execution - Emitting events

What's Next?

Building Applications

Learn how to build applications on amplifier-core. Session management, mount plans, and library integration.

Architecture Overview

Deep dive into the architecture, kernel philosophy, and design decisions.

Using Libraries

How to integrate amplifier-profiles, amplifier-collections, and other libraries in your application.

Contributing

Guidelines for contributing to amplifier-core, libraries, and the foundation.

Philosophy & Principles

When working with the foundation, keep these principles in mind:

1. Mechanism, Not Policy

The kernel provides capabilities, not decisions. If two teams could want different behavior, it's policy → belongs outside the kernel.

Example: - ✅ Kernel: "Emit a tool:pre event before tool execution" - ❌ Kernel: "Log tool execution to stdout in JSON format"

The first is mechanism (event emission). The second is policy (what to do with events).

2. Backward Compatibility is Sacred

Kernel interfaces must not break existing modules or applications. Evolution is additive only.

3. Small and Stable

The kernel is intentionally minimal (~2,600 lines). Changes are rare and boring. Innovation happens at the edges (modules), not in the kernel.

4. Test in Isolation

Mock the coordinator when testing. Modules and applications should be testable without running the full kernel.

5. Libraries are for Applications

Runtime modules never import libraries. Only applications use libraries. This keeps the module boundary clean.

# ✅ In your application
from amplifier_profiles import load_profile
from amplifier_config import ConfigManager

# ❌ In a module (provider, tool, etc.)
from amplifier_profiles import load_profile  # Never do this!

Resources

Getting Help