Amplifier Application Integration

The Protocol Boundary

One line that makes Amplifier apps clean

The Wall

You know bundles — the wall is wiring Amplifier into a real app

Tools, hooks, the prepare/session lifecycle: you have all of that. But FastAPI, WebSockets, Slack, and voice are exactly where projects stall — the gap between “I understand bundles” and “I’ve built a production app with Amplifier.”

That gap has a shipped answer.

The Answer, Shipped

The gap has a single, verified document behind it

One 903-line Application Integration Guide, generated with Amplifier itself, added in a single commit by Brian Krabach on 2026-02-21.

So why do so many apps still get it wrong?

903

lines, one guide (APPLICATION_INTEGRATION_GUIDE.md)

1

commit — 862a814c, 2026-02-21

Brian
Krabach

author; co-authored by Amplifier

The Failure Mode

Skip the guide and you hand-roll a tool loop

Calling the provider directly in a while-loop — Anti-Pattern #3 — produces apps that look like Amplifier but get none of its benefits.

The fix is one architectural idea.

You throw away

Hooks & observability, context continuity, streaming, error recovery, cancellation.

You give up the freedom

To swap orchestrators, providers, and tools.

The guide names it twice

Anti-Pattern #3 (Hand-Rolled Tool Loops) and #1 (Direct API Calls Bypassing the Session) — six anti-patterns in all.

The Single Most Important Idea

Your app owns the edges; Amplifier owns the session

The Protocol Boundary is the one concept the guide calls the single most important. Your app owns HTTP, WebSockets, audio, and Slack; Amplifier owns session lifecycle, tool dispatch, and provider/hook/context management.

They meet at a thin bridge — and that bridge is countable.

Your App

HTTP / WebSocket / audio / Slack

Amplifier

Session lifecycle, tool dispatch, providers, hooks, context

meet at a thin bridge — mechanism (kernel) vs policy (app)

The Bridge Is Real Code

The bridge is exactly four protocol points

ApprovalSystem, DisplaySystem, StreamingHook, and Spawn Capability. ApprovalSystem and DisplaySystem are real Protocol classes in amplifier-core: the kernel provides mechanism, the app layer provides policy.

One boundary; now how does every app type plug in?

ApprovalSystem

Protocol at approval.py:18

DisplaySystem

Protocol at display.py:12

StreamingHook

Realized via hooks.register('*', ...)

Spawn Capability

App-layer policy via register_capability('spawn', ...)

One Shape, Every App

One seven-step lifecycle drives five session patterns

LOAD → COMPOSE → PREPARE → CREATE → MOUNT → HOOK → EXECUTE. That single universal shape maps to five patterns: per-request, per-conversation, singleton, voice/realtime bridge, and multi-session manager.

Follow it and the payoff is concrete.

1LOADload_bundle(source)

2COMPOSEbundle.compose(overlays)

3PREPAREawait bundle.prepare()

4CREATEcreate_session(...)

5MOUNTcoordinator.mount('tools', tool)

6HOOKcoordinator.hooks.register(...)

7EXECUTEawait session.execute(prompt)

The Payoff

The same session runs behind web, voice, CLI, and Slack — unchanged

Respect the boundary and you get four wins for free, straight from the guide (lines 51–54).

One rule carries all of it.

Testability

Mock either side independently.

Portability

Same session behind web, voice, CLI, Slack.

Clarity

Know which side to debug.

Evolvability

Swap the web framework without touching Amplifier — and vice versa.

The Rule To Keep

Don’t hand-roll the loop — keep both sides on their side of the boundary

Your app owns HTTP, WebSockets, audio, and Slack. Amplifier owns the session. Keep each on its side and the integration stays clean as providers, tools, and hooks evolve.

One principle plus a small pattern set — that’s the whole guide.

Sources

Research Methodology

Data as of: 2026-04-09 (amplifier-foundation HEAD 0965a343) SHIPPED

Primary source: microsoft/amplifier-foundation — docs/APPLICATION_INTEGRATION_GUIDE.md. Contract types in amplifier-core (approval.py, display.py, coordinator.py, hooks.py).

Commands run:

wc -l amplifier-foundation/docs/APPLICATION_INTEGRATION_GUIDE.md → 903 lines
git log --diff-filter=A --date=short -- docs/APPLICATION_INTEGRATION_GUIDE.md → commit 862a814c, Brian Krabach, 2026-02-21
git show 862a814c | head -12 → “Generated with Amplifier ... Co-Authored-By: Amplifier”
sed -n '32,44p' / '62,72p' docs/APPLICATION_INTEGRATION_GUIDE.md → four protocol points; seven lifecycle steps
grep -n '^### Pattern [A-E]:' docs/APPLICATION_INTEGRATION_GUIDE.md → five session patterns (A–E)
grep -n '^### [0-9]\. ' docs/APPLICATION_INTEGRATION_GUIDE.md → six anti-patterns
grep -rn 'class ApprovalSystem\|class DisplaySystem' amplifier-core/amplifier_core/ → approval.py:18, display.py:12
grep -rl -i 'pythonnet|colombod' /home/ramparte/dev/ANext → zero Amplifier hits (source hint refuted)

Gaps: End-user adoption/readership numbers are not measurable from the repo and are omitted. Illustrative example classes (WebSocketStreamingHook, VoiceBridge, LifelineApp, SessionManager) live inside the doc and are not shipped importable modules. The guide’s two “Suggested New Examples” (Web/FastAPI, Voice) are proposed, not yet shipped.

Primary contributor: Brian Krabach (sole author across all commits touching the guide and related docs), co-authored by the Amplifier bot.