Skip to content

Developer Guide

Start here for building Amplifier modules.

This guide covers creating custom modules that extend Amplifier's capabilities: providers, tools, hooks, orchestrators, and context managers. Each contract document explains:

  1. What it is - Purpose and responsibilities
  2. Protocol reference - Link to interfaces.py with exact line numbers
  3. Entry point pattern - How modules are discovered and loaded
  4. Configuration - Mount Plan integration
  5. Canonical example - Reference implementation
  6. Validation - How to verify your module works

Module Types

Module Type Contract Purpose
Provider Provider Contract LLM backend integration
Tool Tool Contract Agent capabilities
Hook Hook Contract Lifecycle observation and control
Orchestrator Orchestrator Contract Agent loop execution strategy
Context Context Contract Conversation memory management

Quick Start Pattern

All modules follow this pattern:

# 1. Implement the Protocol from interfaces.py
class MyModule:
    # ... implement required methods
    pass

# 2. Provide mount() function
async def mount(coordinator, config):
    """Initialize and register module."""
    instance = MyModule(config)
    await coordinator.mount("category", instance, name="my-module")
    return instance  # or cleanup function

# 3. Register entry point in pyproject.toml
# [project.entry-points."amplifier.modules"]
# my-module = "my_package:mount"

Source of Truth

Protocols are in code, not docs:

  • Protocol definitions: python/amplifier_core/interfaces.py
  • Data models: python/amplifier_core/models.py
  • Message models: python/amplifier_core/message_models.py (Pydantic models for request/response envelopes)
  • Content models: python/amplifier_core/content_models.py (dataclass types for events and streaming)
  • Rust traits: crates/amplifier-core/src/traits.rs (Rust-side trait definitions)
  • Rust/Python type mapping: CONTRACTS.md (authoritative cross-boundary reference)

These contract documents provide guidance that code cannot express. Always read the code docstrings first.

Validation

Verify your module before release:

# Structural validation
amplifier module validate ./my-module

See individual contract documents for type-specific validation requirements.

For ecosystem overview: amplifier