# Translation Layer

> Insert a typed boundary between the agent's clean domain model and a messy legacy API — vendor schema churn stays outside, agent reasoning stays clean.

- **Category**: Agentic AI
- **Subcategory**: Tool Use & Environment
- **Canonical URL**: https://designpattern.fyi/patterns/translation_layer/

---

## Description
**Intent**: Let the agent reason in its own domain model while backends stay messy.

**Context**: Your agent needs to reason in clean domain concepts while the actual data lives in vendor-specific schemas, legacy APIs with awkward field names, or third-party formats designed for entirely different purposes years ago.

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


## Use Cases
- The agent reasons in one shape (its domain) but data lives in another (vendor schemas).
- Vendor API churn would otherwise leak into the agent's context and reasoning.
- A typed boundary can be maintained between the agent and upstream APIs.





## Trade-offs


### Advantages

- Multiple backends can be swapped behind one tool surface — zero agent changes.

- Domain evolution is decoupled from vendor schema changes.




### Considerations & Drawbacks

- Mapping logic is its own maintenance burden — every schema change needs a mapping update.

- Lossy mappings silently degrade write fidelity if not explicitly flagged.







---
**Reference**: [Original Source](https://www.agentpatternscatalog.org/patterns/translation-layer/)