Model and provider

Runiq agents use a provider/model string.

model: "openai/gpt-5"

The provider part selects a supported provider strategy. The model part is passed to that provider client.

Supported provider names

The current implementation validates provider names against these defaults:

The model name is not a closed enum in the Agent constructor. It is the string after the first slash and is sent to the selected provider.

Examples

new Agent(
    id: "weather-agent",
    name: "Weather Agent",
    instructions: "Answer weather-aware planning questions.",
    model: "openai/gpt-5",
    apiKey: builder.Configuration["OpenAI:ApiKey"]);

new Agent(
    id: "local-agent",
    name: "Local Agent",
    instructions: "Answer using a local model.",
    model: "ollama/llama3.2");

Custom provider options

An agent can receive ProviderOptions for provider-specific runtime settings.

using Runiq.Agents;
using Runiq.Agents.Configuration;

new Agent(
    id: "custom-openai-compatible-agent",
    name: "Custom OpenAI Compatible Agent",
    instructions: "Answer concise application support questions.",
    model: "openai/gpt-5",
    apiKey: builder.Configuration["OpenAI:ApiKey"],
    provider: new ProviderOptions
    {
        Url = "https://api.openai.com/v1",
        Timeout = TimeSpan.FromSeconds(60)
    });

ProviderOptions.Url overrides the provider's default URL. ProviderOptions.Timeout is present in the options model, but timeout behavior depends on the provider client implementation.

API key behavior

The apiKey constructor parameter is optional at the type level.

At runtime, provider requirements still apply. If an agent uses a provider default endpoint that requires a key and apiKey is missing, execution fails with ApiKeyMissing.

OpenAI with the default endpoint needs a valid key:

apiKey: builder.Configuration["OpenAI:ApiKey"]

Ollama is currently configured as a local provider that does not require an API key:

model: "ollama/llama3.2"

Reasoning effort and verbosity

The Agent constructor supports two runtime behavior values:

new Agent(
    id: "analysis-agent",
    name: "Analysis Agent",
    instructions: "Analyze the request and return a concise answer.",
    model: "openai/gpt-5",
    apiKey: builder.Configuration["OpenAI:ApiKey"],
    reasoningEffort: "minimal",
    verbosity: "low");

reasoningEffort accepts:

minimal
low
medium
high

verbosity accepts:

low
medium
high

The constructor defaults are reasoningEffort: "minimal" and verbosity: "low".

For dashboard and playground testing, those defaults are usually a good starting point because they keep responses fast and focused. Increase them only when the agent needs deeper analysis or more detailed output.