III · Tool Use & EnvironmentMature★★

Translation Layer

also known as Anti-Corruption Layer, Adapter Pattern (Agentic), API Façade

Insert a typed boundary between the agent's clean domain model and a messy or legacy external API.

This pattern helps complete certain larger patterns —

  • used-byProvider-String Routing★— Select the model and provider for a request through a single namespaced string (`provider/model`) backed by env-var credentials, so the caller specifies what to run with one parameter rather than a typed provider object.
  • used-byUnified Voice Interface★— Expose text-to-speech, speech-to-text, and real-time speech-to-speech through a single interface so a voice agent can swap providers without rewriting the loop.

Context

A team is building an agent that needs to reason in one shape — a clean domain model that matches the concepts the agent works with — while the underlying data lives in another shape entirely. The real data sits in vendor-specific schemas, legacy APIs with awkward field names, or third-party formats whose structure was decided years ago by another team for entirely different reasons.

Problem

If the agent sees the raw vendor shape, every prompt fills with field names and structure that have nothing to do with the agent's actual task. Tokens are wasted on irrelevant fields, the model's reasoning gets contaminated by vendor-specific terminology, and any churn in the upstream schema ripples directly into the agent's behaviour. The team needs a typed boundary that translates between the agent-friendly domain model and the vendor shape on each call, so that the agent reasons in clean concepts while the storage layer keeps its existing format.

Forces

  • The legacy shape is authoritative for storage but bad for reasoning.
  • Translation must be reversible to write back without data loss.
  • Round-tripping costs latency and complexity.

Example

An agent integrates with a legacy ERP whose API returns 47-field nested objects with vendor-specific casing and undocumented enums. Letting these shapes leak into the agent's context wastes tokens and ties the agent's reasoning to upstream churn. The team puts a translation layer between the agent's tool palette and the ERP: inbound vendor JSON maps to a clean domain shape, outbound domain edits become signed vendor calls. The agent sees a small typed surface and the ERP can re-shape its API without breaking the agent.

Diagram

Solution

Therefore:

A translation module sits between the agent's tool palette and the upstream API. Inbound: vendor JSON is mapped into the domain shape. Outbound: domain edits become signed vendor calls. The agent sees one consistent shape regardless of how many backends sit behind it.

What this pattern forbids. Tools see only the domain shape; the vendor shape never reaches the model.

And the patterns that stand alongside it, or against it —

  • complementsPolymorphic Record★★— Represent a family of related entities in a single core schema with type-specific extensions.
  • composes-withModel Context Protocol★★— Standardise how agents discover and call tools so that a tool written once is usable by any conformant agent.
  • complementsSchema Extensibility★★— Build schemas that evolve without breaking old clients via reserved namespaces and extension blocks.
  • complementsMultilingual Voice Agent Stack★— Compose a voice agent as a tightly co-located pipeline of speech-to-text, language-aware LLM reasoning, and text-to-speech, where one vendor owns all three so language and dialect propagate cleanly across stages.
  • alternative-toCode-Switching-Aware Agent★— Treat mixed-language input (e.g. Hinglish in Roman script) as the expected shape, and design tokenisation, language tagging, and tool routing to handle it natively without forcing the user to commit to one language.

Neighbourhood

Click any neighbour to follow the language. Scroll to zoom, drag to pan.

References

Provenance