liveBook · Manning

Adapter

As explained in Designing AI Systems

The adapter pattern is a design pattern that translates one interface into another interface expected by clients.

An adapter translates between an interface clients expect and an external system’s interface. In a Model Service, a common provider contract lets applications request inference without implementing each provider’s message formats, API calls, and response parsing. Adding a provider requires a new adapter rather than changes to application code. section 3.2.2 section 3.10

Keep the shared contract minimal: a ModelProvider exposes synchronous chat, streaming chat, and capability reporting. The Model Service selects an adapter and applies configured routing and fallback logic; the adapter handles provider-specific translation. Capability reporting matters because models differ in features such as vision, function calling, and context size. section 3.2.2

Listing 3.8 Provider adapter interface
from abc import ABC, abstractmethod
from typing import List, Iterator
 
class ModelProvider(ABC):
    """Abstract base class that all provider adapters implement"""
 
    @abstractmethod
    def chat(self, model: str, messages: List[ChatMessage],
             config: ChatConfig) -> ChatResponse:    #A
        """Generate a response synchronously"""
        pass
 
    @abstractmethod
    def chat_stream(self, model: str, messages: List[ChatMessage],
                    config: ChatConfig) -> Iterator[ChatChunk]:    #B
        """Generate a response with streaming tokens"""
        pass
 
    @abstractmethod
    def get_capabilities(self) -> List[ModelInfo]:    #C
        """Report what this provider supports"""
        pass

The abstract interface defines the operations every provider adapter must implement. section 3.2.2

A provider adapter handles the boundary in both directions:

  • Translate messages and parameters into the provider’s format, mapping supported options and ignoring options that do not apply. section 3.2.4
  • Normalize generated text, token counts, and finish reasons into the platform response; translate provider exceptions into consistent errors while retaining the original error for debugging. section 3.2.4
  • Translate structured-output requests to the provider’s mechanism and normalize streaming chunks as they arrive. section 3.2.4 section 3.3.1

Adapting an Anthropic request

The adapter splits system messages from the conversation because Anthropic expects the system prompt separately. It converts the remaining messages, calls the provider, and translates the response back. An OpenAI adapter can leave system messages in the array; a Google adapter restructures messages into parts. section 3.2.5 section 3.2.4

Listing 3.9 Anthropic provider adapter implementation
class AnthropicProvider(ModelProvider):
 
    def __init__(self, api_key: str):
        self.client = anthropic.Anthropic(api_key=api_key)
 
    def chat(
        self,
        model: str,
        messages: List[ChatMessage],
        config: ChatConfig
    ) -> ChatResponse:
 
        # Extract system prompt - Anthropic requires it as separate 
➥parameter
        system_prompt, conversation = self._split_system_message(
            messages
        )    #A
 
        # Convert to Anthropic's expected format
        anthropic_messages = [
            {"role": m.role, "content": m.content}
            for m in conversation
        ]
 
        response = self.client.messages.create(
            model=model,
            system=system_prompt,    #B
            messages=anthropic_messages,
            max_tokens=config.max_tokens,
            temperature=config.temperature
        )
 
        # Normalize response to platform format
        return ChatResponse(
            content="".join(b.text for b in 
➥response.content if b.type == "text"),    #C
            model=response.model,
            provider="anthropic",
            usage=TokenUsage(
                prompt_tokens=response.usage.input_tokens,
                completion_tokens=response.usage.output_tokens,
                total_tokens=(
                    response.usage.input_tokens
                    + response.usage.output_tokens
                )
            ),
            finish_reason=response.stop_reason
        )

The implementation excerpt shows request translation at the Anthropic API boundary. section 3.2.5

Adapting an external tool

An Epic adapter accepts appointment arguments from the Tool Service, obtains a token, builds a FHIR query, and simplifies the response. Applications use the tool interface instead of calling the EHR API directly, so an API version change can be contained within the adapter. section 6.3.1

Adapters also affect operations. A streaming adapter normalizes provider chunks before the Model Service forwards them through gRPC and the gateway converts them to SSE. For tool execution, isolation bounds the impact of failures such as an adapter loop or an oversized external response. section 3.3.1 section 6.5

How Designing AI Systems covers it

How deep it goes
Defines a shared interface and translation responsibilities, then walks through an implementation excerpt rather than a complete provider adapter.
Examples
Uses Anthropic message translation and an Epic appointment adapter with OAuth and FHIR to illustrate provider and tool boundaries.
What you can do after
Evaluate/understand how to structure adapters that translate requests and responses across provider or external-system boundaries.
How it connects
Connects adapters to routing, fallback chains, streaming, structured output, and execution isolation.

Also explained in

Compare how 17 books explain adapter →

Related concepts

This explainer was generated by Manning's knowledge graph from the text of Designing AI Systems. The section links point to the parts of the book it draws on.