Core Amplifier concepts — kernel architecture, five module types, orchestrators as the main engine, session lifecycle, hooks and events, tool-vs-hook distinction, and kernel-vs-module philosophy.
Use this skill when you need to understand how Amplifier is structured before making a change, implementing a module, or debugging unexpected session behavior.
amplifier-foundation/docs/CONCEPTS.md — Bundle model, mount plan, session lifecycleamplifier/docs/MODULES.mdamplifier-module-resolution — SPECIFICATION.md — Module protocol contractsExpert agents for volatile details:
core:core-expert — Kernel contracts, module protocol compliancefoundation:foundation-expert — Bundle model, session API, Foundation libraryamplifier-core is an ultra-thin kernel. Its entire job is to define contracts — the
interfaces that modules must implement. It has almost no implementation of its own.
What the kernel defines:
What the kernel does NOT do:
Everything else is in modules or in amplifier-foundation (the library layer for apps).
Modules implement the kernel's contracts. There are exactly five types:
| Type | What it does | Key examples |
|---|---|---|
| Orchestrator | Controls the agent execution loop — when to call the model, how to handle tool calls, when to stop | loop-basic, loop-streaming, loop-events |
| Provider | Connects to an AI model backend — translates the kernel's messages protocol to a specific API | provider-anthropic, provider-openai, provider-gemini, provider-mock |
| Tool | Gives the agent a capability it can invoke — the agent calls tools by name with parameters | tool-filesystem, tool-bash, tool-web, tool-task |
| Context Manager | Manages conversation history — compaction strategy, persistence, retrieval | context-simple, context-persistent |
| Hook | Observes and intercepts session lifecycle events — logging, redaction, approval gates, streaming UI | hooks-logging, hooks-approval, hooks-streaming-ui |
The orchestrator is the most important module. It is the execution loop that drives everything else.
An orchestrator's responsibilities:
Orchestrators fire hooks at key lifecycle events. This is what enables streaming UIs, logging, approval gates, and cost-aware scheduling — the orchestrator doesn't implement any of that, it just fires events that hooks handle.
Rule: If session behavior is unexpected, start by understanding which orchestrator is loaded and what events it fires.
PREPARE → load bundle → resolve modules → download from git URLs → return PreparedBundle
CREATE → PreparedBundle.create_session(...) → activates modules → returns AmplifierSession
EXECUTE → session.execute(prompt) → orchestrator loop → tool dispatch → response
CLOSE → session.close() → teardown hooks → release resources
PreparedBundle is the expensive singleton. prepare() downloads modules from git URLs.
Do it once at application startup. create_session() is cheap — do it per-request.
Session ID is persistent identity. Reusing a session ID across close/recreate lets context-persistent modules restore history while the configuration changes.
These are often confused. They are fundamentally different:
| Tool | Hook | |
|---|---|---|
| Who calls it | The AI model (agent) | The orchestrator (lifecycle events) |
| When | When the model decides to use a capability | At fixed lifecycle events (before call, after call, on error, etc.) |
| Purpose | Give the agent something it can do | Observe, modify, or intercept the execution flow |
| Examples | Read a file, run bash, search the web | Log events, redact secrets, show streaming UI, ask for approval |
| Return value | Tool result returned to the model | Hook return can modify or intercept the event |
Mental model: Tools are what the agent does. Hooks are what happens around the agent.
Modules are loaded by the kernel from source URIs at prepare() time.
Source types:
git+https://github.com/...@main — Git URL (standard production pattern)file:///path/to/module — Local path (workspace/settings.yaml pattern)AMPLIFIER_MODULE_<ID> env var — Development override (clears on terminal close)Module ID must match the [project.entry-points."amplifier.modules"] key in the module's
pyproject.toml. If they don't match, the module fails to load.
For module resolution internals and edge cases, consult core:core-expert or the
amplifier-module-resolution SPECIFICATION.md.
| Mistake | Fix |
|---|---|
Importing amplifier-foundation in a runtime module | Modules depend only on amplifier-core |
| Confusing tools and hooks | Tools are agent capabilities; hooks observe lifecycle events |
| Putting implementation logic in the kernel | The kernel only defines contracts; implementation belongs in modules |
| Treating orchestrators as interchangeable | Different orchestrators fire different events and have different streaming behavior |
Calling prepare() per request | prepare() is expensive — call it once at startup |