Skip to main content

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:

FileClassRole
<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 : AIProviderModelsModel catalog and capability mappings. Models and capabilities
<Name>ProviderSettings.cs<Name>ProviderSettings : AIProviderSettingsSettings descriptors + secrets handling. Provider settings
<Name>ProviderFactory.cs<Name>ProviderFactory : IAIProviderFactoryDiscovery 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​

BaseWhen
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: resolve Endpoint, HttpMethod, Authentication and Headers on the supplied detached copy (e.g. DeepSeek injects a reasoning-effort parameter here). The public PreCallAsync entry detaches the caller's request via CreateExecutionCopy before invoking your override, so wire fields never leak into caller state.
  • PostCall(IAIReturn) — adjust the decoded result.
  • CreateStreamingAdapter() (protected) — return an AIProviderStreamingAdapter to enable streaming; DeepSeek wires one that parses SSE deltas.
  • GetExtraDescriptors() — extra UI descriptors beyond SettingDescriptors.
  • 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 (CallApi is internal to AIProvider)
  • 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:

MemberDescription
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.