Skip to content

Architecture

Every adapter implements llm.LLM: a model you send one request to and get back one complete response, or a stream of partial responses followed by a complete one. Its request and response types copy ADK’s model package field for field. The only exception is ADK’s tool map, which no adapter needs: the tool declarations a provider sends travel in the request’s genai config.

Mirroring rather than importing ADK is deliberate. Each ADK major’s model interface has the same shape but is a different Go type, so a library that imported one major could not serve a consumer on another. When core-agent was on ADK v1 and mast on ADK v2, that is what let one core serve both.

ModuleDepends onUsed by
github.com/go-steer/core-modelsgenai and the vendor SDKs, never ADKeverything below
github.com/go-steer/core-models/adkv2the core, google.golang.org/adk/v2mast and core-agent. Wrap adapts an llm.LLM to ADK, and GroundingProjection turns Gemini’s Google Search grounding into session events

The adapter module converts by copying fields. It has two functions:

  • Wrap turns a core-models model into an ADK model.LLM.
  • FromADK goes the other way, so a decorator written against core-models can sit in front of a model ADK built.

Their tests compare the mirror against ADK’s own types with reflection, so an ADK upgrade that adds a field fails the build instead of losing the field silently.

A presubmit protects this layout: core module imports no ADK fails if any package in the core module reaches an ADK major, directly or through a dependency. A future ADK major gets its own adapter module beside adkv2.

In core-modelsIn each product
Provider adapters, one per wire formatWhich model each tier gets
Provider profiles: endpoint, credentials, capabilitiesWhere operators write profiles, and CLI flags
The usage recordBudgets, meters and usage trackers
Retry at the HTTP layer, where rate-limit headers are still visibleWhat to do after the library gives up
The price catalog (later)Price file locations and refresh policy

The full design covers the parts not built yet.