When to reach for it
- APIs are inconsistent or unstable.
- Agents require simple tool contracts.
- Security or error logic must be encapsulated.
Adapter Pattern.
Wrap the messy API in a clean tool the model can call.
A wrapper translates a messy or unstable external API into a small, stable, agent-friendly tool contract — so the model sees one clean function while the adapter absorbs auth, pagination, error handling, and schema drift behind it.
In practiceAn HR agent wraps a 15-year-old SOAP payroll API in an adapter that exposes a single `get_employee_salary(id)` function, shielding the model from XML envelope details.
When it backfires
- Native SDKs already provide suitable interfaces.
- The adapter merely passes data without adding value.
- The abstraction hides important semantics.
The tradeoff
More stable agent interfaces are gained against the cost of maintaining an additional code layer.
What it actually does.
An adapter translates between mismatched interfaces.
Two ways this pattern will hurt you.
The adapter hides the failure mode it should surface
The wrapper swallows a 429 or a partial result and returns a clean shape. The agent reasons against the clean shape and acts as if the call succeeded.
Fix · Pass through structured errors with category (rate limit, partial, fatal). Let the agent or the harness decide how to react — never let the adapter quietly normalise away signal.
The upstream changes and the adapter passes it through
The wrapped API changes a field or its semantics. The adapter has no contract test, so the drift flows straight to the model, which reasons against a contract that quietly moved.
Fix · Contract-test the adapter against the live API and version it; pin the agent to an adapter version so an upstream change fails the test rather than the run.
Where Adapter Pattern is native.
Microsoft Agent Frameworkcustom toolsAdaptable
Keep going