Context at Every Level

How Amplifier's A2A bundle keeps agents scoped

The Problem

One shared context window drowns a workspace full of agents

A busy Amplifier workspace runs many specialist agents that each need their own right-sized context. Force them all through one "do everything" window and it pollutes every agent and bloats every call.

amplifier-bundle-a2a answers this by scoping context at every level — and wiring the specialists together.

Global install — installed once, everywhere
Per-directory identity — each directory gets its own scope
Per-request child — every remote request gets a bounded session

Proof

This is real, shipped Microsoft code — and it's green

amplifier-bundle-a2a is a Microsoft-org bundle: 2,328 non-test lines across two modules, with a passing suite at HEAD 14e5cc6 (2026-06-15).

So what are those two modules? That's the shape of the whole argument.

Status: Shipped · HEAD 14e5cc6

2,328

non-test module LOC (two modules)

308

tests collected — 307 passed, 1 skipped

2

inline modules: CLIENT + SERVER

The Two Modules

A CLIENT that sends and a SERVER that receives

The bundle ships exactly two inline modules. tool-a2a is the CLIENT — 14 operations for sending messages to remote agents. hooks-a2a-server is the SERVER — aiohttp on default port 8222, receiving messages from remote agents.

Installed globally, though, that server would try to run everywhere.

14

tool-a2a CLIENT operations (agents, card, send, status, discover…)

8222

hooks-a2a-server SERVER default port

The Risk

Installed globally, the server stays inert until you opt in

A global install could mean a server running in every directory. Instead the hook checks if not config.get("enabled", False): skip — enabled defaults to false, so no HTTP and no mDNS start until a directory sets it true.

That opt-in switch is written per directory — which is where context gets scoped.

# hooks-a2a-server __init__.py:35
if not config.get("enabled", False):
    # "A2A server not enabled — skipping."
    return

# Master switch defaults to false.
# Install globally, opt in per directory.

Per-Directory Scope

Each directory gets its own a2a identity, port, and contacts

A directory opts in by writing an override into its own .amplifier/settings.yaml. Per the README, "each directory gets its own a2a identity, port, and contacts" — and the behavior injects only its scoped context via context.include, not a monolith.

With directories scoped, the specialists inside them can start talking to each other.

Override lives in .amplifier/settings.yaml per directory
Own identity, port, and contacts per directory
Context injected via context.include: a2a:context/a2a-instructions.md

Agents Talk

Scoped specialists query each other over real localhost HTTP

Integration tests start the A2AServer on 127.0.0.1 with an OS-assigned port and do real aiohttp round-trips against /.well-known/agent.json and /a2a/v1/tasks. The communication is real HTTP, over localhost.

Which raises the sharp question: what is a remote agent actually allowed to touch?

Discover

Server default port 8222; peers found over mDNS

Round-trip

Real aiohttp GET /.well-known/agent.json

Task

Real POST to /a2a/v1/tasks on 127.0.0.1

The Payoff

A remote request spawns a child session with a bounded blast radius

When a trusted peer asks, the server spawns a CHILD AmplifierSession with tools filtered by trust tier — and deliberately NO a2a hooks ("child doesn't need a2a server"). Context stays scoped, and no recursive server or port collision can happen.

Trust tiers bound exactly what that child may touch.

Child session — parent providers + tier-filtered tools, no a2a hooks
trusted tier → "*" (all parent tools)
known tier → [tool-filesystem, tool-search] (read-only)
spawn.exclude_hooks keeps the server out of delegated sub-agents

The Pattern

Context at every level is how you scale many agents

Global install, per-directory identity, per-request child session — three nested scopes so no single context window drowns a workspace full of specialists, all covered by 308 tests.

Sources

Research Methodology

Repository: microsoft/amplifier-bundle-a2a — git@github.com:microsoft/amplifier-bundle-a2a.git

Data as of: HEAD 14e5cc6ad9821ccd78548c10d70874e8176ead33 (2026-06-15). Clone at /tmp/a2a-src.

Feature status: Shipped as a Microsoft-org bundle; full suite green (307 passed / 1 skipped).

Commands run:

Modules: ls modules; README Architecture section sed -n '230,257p' README.md
Line counts: find modules -name '*.py' -not -path '*/tests/*' | xargs wc -l | tail -1 (2328 non-test LOC)
Test suite: uv run pytest --collect-only -q; uv run pytest -q (308 collected; 307 passed, 1 skipped)
Operations: grep -cn 'operation ==' modules/tool-a2a/.../__init__.py (14)
Opt-in gate: sed -n '29,40p' modules/hooks-a2a-server/.../__init__.py (enabled defaults false)
Behavior compose: cat behaviors/a2a.yaml (tool + server hook port 8222 + context.include)
Child session: sed -n '237,254p' .../server.py; trust tiers sed -n '216,235p' .../server.py
Integration: grep -n 'port|127.0.0.1|A2AServer' tests/test_integration.py (localhost round-trip)
Timeline: git log --reverse --format='%ci %s'; contributors git log --format='%an' | sort | uniq -c | sort -rn

Gaps: The 8222/8223 pairing is documentation example, not a running pair — 8222 is the server default, 8223 appears only as an example peer URL. Integration tests use an OS-assigned port on 127.0.0.1. No gh API calls were made.

Primary contributors: Brian Krabach (25 commits), Salil Das (3 commits).