Writing a provider
In the ecosystem, providers are the bridge to external AI services — they translate between SmartHopper's generic AICall format and your vendor's wire protocol and back.
Structure of a provider
Each provider lives in its own project named SmartHopper.Providers.<Name> — the <Name> suffix is the provider identifier, used by discovery, the settings store, and GetFormattedTools. It compiles to SmartHopper.Providers.<Name>.dll, dropped next to SmartHopper.Infrastructure.dll.
A provider is four files — a schema shared by every shipped provider:
| File | Class | Role |
|---|---|---|
<Name>Provider.cs | <Name>Provider : AIProvider<T> | Required. The contract: metadata + Encode/Decode between AICall and the vendor wire format. This page. |
<Name>ProviderModels.cs | <Name>ProviderModels : AIProviderModels | Model catalog and capability mappings. Models and capabilities |
<Name>ProviderSettings.cs | <Name>ProviderSettings : AIProviderSettings | Settings descriptors + secrets handling. Provider settings |
<Name>ProviderFactory.cs | <Name>ProviderFactory : IAIProviderFactory | Discovery entry point — how the host instantiates you. Factory and packaging |
Plus the project file <Name>Provider.csproj with the assembly attributes (see packaging). The main class is the biggest of the four; the other three are short.
File structure: <Name>Provider.cs
This is the main class of the provider — it must inherit from AIProvider<T> (or the OpenAI-compatible variant) and implement the required members:
/// <summary>
/// Xyz provider implementation for SmartHopper.
/// </summary>
public sealed partial class XyzProvider : AIProvider<XyzProvider>
{
// Singleton — the host always goes through XyzProvider.Instance
private XyzProvider()
{
// Required: pass the models class to the base
this.Models = new XyzProviderModels(this);
}
public static XyzProvider Instance { get; } = new XyzProvider();
/// <summary>The name of the provider — matches the assembly id.</summary>
public override string Name => "Xyz";
/// <summary>Default server URL for the provider.</summary>
public override Uri DefaultServerUrl => new Uri("https://api.xyz.com");
/// <summary>Whether this provider is enabled and available for use.</summary>
public override bool IsEnabled => true;
/// <summary>Whether required settings (e.g. the API key) are in place.</summary>
public override bool IsConfigured => this.IsSettingConfigured("ApiKey");
/// <summary>The provider's icon.</summary>
public override Image Icon => this.LoadIconFromResources(Properties.Resources.xyz_icon);
/* Encode / Decode — the heart of the provider, covered below */
}
Pick a base class
| Base | When |
|---|---|
AIProvider<T> | Your API doesn't look like OpenAI's chat-completions format — implement Encode/Decode yourself. |
OpenAICompatibleProvider<T> | Your API is OpenAI-shaped (DeepSeek, MistralAI, OpenRouter, Ollama, LocalAI…). Message/role/tool/schema/metrics handling is done; you mostly tweak quirks. |
Both give you a singleton Instance (providers are singletons) and the helpers covered at the end of this page.
The contract
Beyond the five metadata members in the skeleton above, AIProvider has 3 more abstract members — the wire codec. This is the complete mandatory surface:
public override string Encode(AIRequestCall request) { /* AIBody → wire JSON */ }
public override string Encode(IAIInteraction interaction) { /* one interaction → JToken as string */ }
public override List<IAIInteraction> Decode(JObject response) { /* wire JSON → interactions */ }
Virtual members you override when needed:
PreCallCoreAsync(AIRequestCall outbound, CancellationToken)— protected virtual wire-preparation hook: resolveEndpoint,HttpMethod,AuthenticationandHeaderson the supplied detached copy (e.g. DeepSeek injects a reasoning-effort parameter here). The publicPreCallAsyncentry detaches the caller's request viaCreateExecutionCopybefore invoking your override, so wire fields never leak into caller state.PostCall(IAIReturn)— adjust the decoded result.CreateStreamingAdapter()(protected) — return anAIProviderStreamingAdapterto enable streaming; DeepSeek wires one that parses SSE deltas.GetExtraDescriptors()— extra UI descriptors beyondSettingDescriptors.Encode(List<IAIInteraction>)— batch encoding helper.
Encode: AIBody → wire JSON
Encode(AIRequestCall) receives the fully validated request. Read request.Body (interactions + filters), request.Model, provider settings via GetSetting<T>, and emit your API's JSON:
public override string Encode(AIRequestCall request)
{
var body = new JObject
{
["model"] = request.Model,
["messages"] = new JArray(
request.Body.Interactions.Select(i => JToken.Parse(this.Encode(i)))),
["max_tokens"] = this.GetSetting<int>("MaxTokens"),
};
// Structured output — request.Body.JsonOutputSchema is set when JsonOutput was requested.
if (!string.IsNullOrEmpty(request.Body.JsonOutputSchema))
{
body["response_format"] = AdaptSchema(request.Body.JsonOutputSchema);
}
// Tools — GetFormattedTools returns the catalog slice the ToolFilter allows,
// formatted for the request's surface (Direct vs. MCP).
var toolFilter = request.Body.ToolFilter;
if (!string.IsNullOrWhiteSpace(toolFilter) && toolFilter != "-*")
{
var tools = this.GetFormattedTools(toolFilter, request.ToolSurface);
if (tools?.Count > 0)
{
body["tools"] = tools;
}
}
return body.ToString(Formatting.None);
}
Encode(IAIInteraction) handles a single interaction — typically mapping AIAgent to your role strings and serializing text/image/audio/tool-call payloads. OpenAI-compatible providers get ready-made role/image/audio codecs from the SDK (OpenAICompatibleRoleMapper, OpenAICompatibleImageCodec, OpenAICompatibleAudioCodec).
Decode: wire JSON → interactions
Decode(JObject response) must return the reply as a list of IAIInteraction — AIInteractionText for content, AIInteractionToolCall for requested tool calls:
public override List<IAIInteraction> Decode(JObject response)
{
var interactions = new List<IAIInteraction>();
var message = response["choices"]?[0]?["message"] as JObject;
var content = message?["content"]?.ToString();
if (!string.IsNullOrEmpty(content))
{
interactions.Add(new AIInteractionText
{
Agent = AIAgent.Assistant,
Content = content,
Metrics = this.DecodeOpenAICompatibleMetrics(response), // tokens, finish reason, timing
});
}
if (message?["tool_calls"] is JArray toolCalls)
{
foreach (JObject tc in toolCalls)
{
var function = tc["function"] as JObject;
interactions.Add(new AIInteractionToolCall
{
Id = tc["id"]?.ToString(),
Name = function?["name"]?.ToString(),
Arguments = JObject.Parse(function?["arguments"]?.ToString() ?? "{}"),
});
}
}
return interactions;
}
Providers also map error bodies to AIInteractionRuntimeMessage (Severity + Content) instead of throwing — see how DeepSeek handles {"error": …} responses.
Always decode metrics — token counts and finish reason feed the metrics badges and cost tracking. On OpenAI-compatible APIs DecodeOpenAICompatibleMetrics(response) does it in one call.
What you do not write
The host already handles — don't duplicate:
- HTTP transport, headers, auth injection, timeouts (
CallApiis internal toAIProvider) - Model resolution and capability validation
- Context injection into the body
- The tool-call loop (executing tools and re-querying)
- Streaming orchestration and chunked coalescing
- Settings persistence and the settings dialog
Streaming (optional)
Override CreateStreamingAdapter() to return an AIProviderStreamingAdapter subclass that parses your vendor's SSE/delta format into interaction chunks. AIProviderSettings.EnableStreaming (default true) lets users toggle it per provider. If you don't provide an adapter, calls still work — they just return complete responses.
Assembly metadata
Discovery requires the provider-id attribute and SDK compatibility attributes — see Factory and packaging for the [assembly: …] block and .csproj setup.
What the base class gives you
AIProvider implements the plumbing common to every provider — you use and override the pieces you need:
| Member | Description |
|---|---|
GetSetting<T>(key) / SetSetting(key, value) | Read/write a persisted setting value (API keys, endpoints…). |
IsSettingConfigured(settingName) | Whether a required setting has a value — drives IsConfigured. |
GetFormattedTools(toolFilter, surface) | The tool catalog slice the filter allows, formatted for your request surface. |
GetDefaultModel(requiredCapability) | Resolve the provider's default model for a capability (e.g. AICapability.Text2Text). |
LoadIconFromResources(bytes) | Build the Image for Icon from an embedded resource. |
DecodeOpenAICompatibleMetrics(response) | OpenAI-compatible base only — token counts, finish reason, timing in one call. |
HTTP transport, auth injection, timeouts, model validation, context injection, and the tool-call loop are handled by the host — see what you do not write.
A real reference implementation
src/SmartHopper.Providers.DeepSeek/ is the cleanest example to copy: an OpenAI-compatible provider with a PreCallCoreAsync quirk (reasoning effort), schema adapter (DeepSeekJsonSchemaAdapter), streaming adapter, and the full four-file layout.