Active
Onboarding Guide

Amplifier
Ecosystem Architecture

A Linux kernel-inspired, modular AI agent framework

New Contributor Guide | February 2026
The Challenge

Monolithic agent frameworks
don't scale

When everything is hardcoded, teams fight over the same codebase. Every change risks breaking everything else. Different teams need different behaviors but share the same code.

1
Codebase to rule them all
N
Teams with different needs
0
Good outcomes
The Insight

Linux solved this
~35 years ago

A minimal, stable kernel provides mechanisms. Replaceable modules implement all policies. Different distributions serve different needs from the same foundation.

Kernel (Mechanism)
Modules (Policy)
Module loading
Which modules to load
Event emission
What to log, where
Session lifecycle
Orchestration strategy
Hook registration
Security policies
Architecture

Three Layers, Clear Boundaries

APPLICATIONS amplifier-app-cli, custom apps User experience, config merging, interfaces | | uses v FOUNDATION amplifier-foundation Bundles, @mentions, agents, module resolution | | builds on v KERNEL amplifier-core (8,134 lines) Module loading, sessions, events, protocols | | defines contracts for v MODULES provider-*, tool-*, hooks-*, etc. LLM backends, capabilities, observability
The Kernel

amplifier-core

Ultra-thin, stable, boring. Changes rarely, backward-compatible always.

8,134
Lines of Python
click pydantic tomli pyyaml typing-extensions

5 runtime dependencies. No LLM SDKs. No business logic.

Key Components
AmplifierSession - Main entry point (474 lines)

ModuleCoordinator - Infrastructure context (606 lines)

ModuleLoader - Discovery & loading (598 lines)

HookRegistry - Event system

Protocols - 6 module contracts
Module Types

Six Protocols, Six Contracts

Provider
ChatRequest → ChatResponse
LLM backends: Anthropic, OpenAI, Azure, Ollama
Tool
execute(input) → ToolResult
Capabilities: filesystem, bash, web, search
Orchestrator
execute(prompt, ...) → str
Execution strategy: loops, streaming, events
ContextManager
add/get/compact messages
Memory: simple context, persistent, compacted
HookHandler
(event, data) → HookResult
Observability: logging, redaction, approval
ApprovalProvider
request_approval() → bool
Human-in-loop: gated actions, safety checks
Contracts

Protocol Definitions

# Provider Protocol class Provider(Protocol): @property def name(self) -> str: ... def get_info(self) -> ProviderInfo: ... async def complete( self, request: ChatRequest ) -> ChatResponse: ...
# HookHandler Protocol class HookHandler(Protocol): @property def name(self) -> str: ... @property def events(self) -> list[str]: ... async def handle( self, event: str, data: dict ) -> HookResult: ...

Implement the protocol. Register with the coordinator. Done.

Foundation

amplifier-foundation

The library layer that makes composition possible.

Bundle System
Composable configurations in Markdown + YAML. Include other bundles. Merge intelligently.
@Mention Resolution
Reference context files with @bundle:path syntax. Loaded on demand. Namespaced cleanly.
Agent Definitions
Agents are bundles with descriptions. Spawned as child sessions with focused context.
Module Sources
Resolve modules from git URLs, local paths, or installed packages.
PreparedBundle
Downloads modules, activates them, creates ready-to-run sessions.
spawn()
Create child sessions for agent delegation with context control.
Composition

Bundles: Composable Configuration

# bundle.md - Thin bundle pattern --- bundle: name: my-capability version: 1.0.0 includes: - bundle: foundation - bundle: my-cap:behaviors/core tools: - module: tool-special source: ./modules/tool-special agents: include: - my-cap:agents/expert --- # System Instructions You are an AI assistant with... @my-cap:context/guidelines.md

Merge Rules

SectionRule
sessionDeep merge
providers, tools, hooksMerge by module ID
agentsReplace by name
contextAccumulate with namespace
instruction (body)Replace (later wins)
Configuration

Mount Plan: The Session Contract

# The mount plan consumed by AmplifierSession { "session": { "orchestrator": "loop-streaming", # Required "context": "context-simple" # Required }, "providers": [ {"module": "provider-anthropic", "config": {"model": "claude-sonnet-4-20250514"}} ], "tools": [ {"module": "tool-filesystem"}, {"module": "tool-bash"} ], "hooks": [ {"module": "hooks-logging", "config": {"level": "info"}} ], "agents": { ... } # Pass-through data for applications }
Bundle
bundle.md
→
Mount Plan
to_mount_plan()
→
Session
AmplifierSession
Philosophy

The Litmus Test

"Could two teams want different behavior?"
If yes → Module, not kernel

Kernel DOES
• Load modules
• Emit events
• Manage session lifecycle
• Register hooks
• Validate mount plans
Kernel NEVER
• Selects providers or models
• Decides orchestration strategy
• Chooses tool behavior
• Formats output
• Picks logging destination
Ecosystem

Repository Landscape

Repository Role When to Contribute
amplifier Main entry point Documentation, installation guides
amplifier-core The kernel New protocols, core bug fixes (rare)
amplifier-foundation Library layer Bundle system, @mentions, agents
amplifier-app-cli Reference CLI User experience, config features
amplifier-module-* Runtime modules New providers, tools, hooks (most common)
amplifier-bundle-* Bundles New capabilities, agent behaviors
Patterns

Key Architecture Patterns

Thin Bundle Pattern
Inherit from foundation, add only unique capabilities. Never duplicate tools/session/hooks that foundation provides.
includes: - bundle: foundation - bundle: mine:behaviors/x
Context Sink Pattern
Heavy docs live in agent files (loaded only when spawned). Behaviors stay thin with awareness pointers.
# Behavior: 30 lines awareness # Agent: @bundle:docs/GUIDE.md # Loads only when spawned!
Agent Delegation
Spawn child sessions for focused tasks. Control context depth and scope. Parent awaits result.
await bundle.spawn( child_bundle, instruction="..." )
Philosophy

Seven Principles

1
Mechanism, Not Policy Kernel provides capabilities; modules decide behavior
2
Ruthless Simplicity As simple as possible, but no simpler
3
Small, Stable, Boring Kernel Changes rarely, backward-compatible always
4
Bricks & Studs Self-contained modules with clear interfaces
5
Event-First Observability If it's important, emit an event
6
Text-First Human-readable, diffable configurations
7
Two-Implementation Rule Prove at edges before promoting to kernel
Velocity

Development at a Glance

134
Commits
8,134
Lines of Python
5
Dependencies
6
Protocol Contracts

Primary author: Brian Krabach (130 of 134 commits, ~97%)
Contributors: Samuel Lee, Sam Schillace, Marc Goodner, Diego Colombo
Timeline: October 8, 2025 – February 17, 2026 (~4 months)

Sources

Research Methodology

Data as of: February 20, 2026

Feature status: Active

Repository: microsoft/amplifier-core (local clone)

Research performed:

  • find amplifier_core -name "*.py" | xargs wc -l → 8,134 lines total
  • find amplifier_core -maxdepth 1 -name "*.py" | xargs wc -l → 4,752 lines kernel-proper
  • git log --oneline | wc -l → 134 commits
  • git log --format="%an" | sort | uniq -c | sort -rn → 5 contributors
  • grep -n "class.*Protocol" amplifier_core/interfaces.py → 6 protocols
  • cat pyproject.toml | grep -A 20 "dependencies" → 5 runtime deps
  • git log --reverse --format="%ai" | head -1 → first commit 2025-10-08
  • find amplifier_core -name "*.py" -exec wc -l {} | sort -rn | head -10 → top files

Gaps: Foundation and module repo line counts not included (kernel repo only).

Primary contributor: Brian Krabach (130/134 commits, ~97%)

Next Steps

Start Contributing

New to Amplifier?
Clone amplifier repo
Run the CLI
Read DESIGN_PHILOSOPHY.md
Building a Module?
Check amplifier-core/docs/contracts/
Study existing modules
Implement the protocol
Creating a Bundle?
Start with amplifier-foundation
Use the thin bundle pattern
Compose, don't duplicate
Questions? Ask in #amplifier-dev
1 / 17
← → or click to navigate
More Amplifier Stories