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.

Audience

Building a module that plugs into Amplifier (Provider, Tool, Hook, Orchestrator, Context)? You're in the right place. For building an application with Amplifier, see Foundation Guide.

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.

Mount Plan Specification - Configuration contract
Module Source Protocol - Module loading mechanism
Contribution Channels - Module contribution pattern
Design Philosophy - Kernel design principles

Validation¶

Verify your module before release:

# Structural validation
amplifier module validate ./my-module

See individual contract documents for type-specific validation requirements.

Next Steps¶

Choose a module type - Pick from the table above
Read the contract - Understand the protocol requirements
Study examples - Review canonical implementations
Build and test - Implement and validate your module
Publish - Share with the ecosystem

Resources¶

amplifier-core - Module contracts and protocols
Example modules - Study existing provider, tool, and hook implementations
Community - Join discussions and get help