Models

Purpose and Scope

Models are the part of a Flue harness that decide what kind of language-model work an agent can perform. Providers are the connection layer that lets the application reach those models, authenticate requests, and apply service-specific transport settings. In practice, you choose both at the same time: an agent points at a model specifier, and Flue resolves the provider prefix in that specifier to the provider configuration registered for the runtime. This page helps you understand those names before you wire them into agents, prompts, skills, tasks, or Cloudflare deployments.

Sources: apps/docs/src/content/docs/guide/models.md

The Models guide is intentionally placed in the authoring flow between agent construction and provider API reference material. It explains model selection for addressable agents, points workflow authors to the Workflows guide for finite orchestration, and directs API readers to the Agent API and Provider API for operation-level inputs, results, and registration signatures. That means this page should be read as a practical configuration guide rather than a provider catalog: it teaches the naming convention and the behavior Flue applies when a model or reasoning setting is selected.

Relevant Source Files

• apps/docs/src/content/docs/guide/models.md — First-party guide source for model specifiers, provider IDs, model IDs, default agent model configuration, thinkingLevel, and provider-selection terminology.

Core Primitives

A model specifier is the unique string Flue uses to refer to a concrete model across providers. It is composed of a provider ID followed by a slash and the provider-recognized model ID. For example, anthropic/claude-sonnet-4-6 uses anthropic as the provider ID and claude-sonnet-4-6 as the model ID, while cloudflare/@cf/moonshotai/kimi-k2.6 uses cloudflare as the provider ID and @cf/moonshotai/kimi-k2.6 as the model ID. The distinction matters because responses preserve the chosen model as { provider, id }, keeping the routing prefix separate from the model identifier.

Sources: apps/docs/src/content/docs/guide/models.md

Use model specifiers anywhere Flue lets you choose a default or override a model-driven operation. The guide shows the common case first: an agent module exports defineAgent(() => ({ model: 'anthropic/claude-sonnet-4-6' })), making that model the agent’s default. The same naming scheme can also be supplied by reusable profiles and subagents, or used to override the default for an individual prompt, skill, or task operation. This lets a broad agent run on one model while a specialized step uses another provider or model family.

import { defineAgent } from '@flue/runtime';
 
export default defineAgent(() => ({
  model: 'anthropic/claude-sonnet-4-6',
}));

Reasoning Effort

thinkingLevel is Flue’s model-reasoning effort setting. It controls how much additional reasoning Flue asks the selected model to perform when that provider path supports the capability. The supported values are 'off', 'minimal', 'low', 'medium', 'high', and 'xhigh'. The guide defines 'medium' as the default balance between reasoning effort and cost, with lower values favoring cost or latency and higher values requesting more careful reasoning. Treat this as a request to the provider path, not as a guarantee that every model endpoint exposes identical reasoning controls.

Sources: apps/docs/src/content/docs/guide/models.md

Configure ordinary reasoning effort next to the model when the whole agent should prefer a given reasoning style. Like the model specifier itself, thinkingLevel can also come from a reusable profile or be overridden for a prompt, skill, or task operation. That layering gives teams a simple default while still allowing critical operations, such as review or diagnosis, to request a higher effort tier. Unsupported paths ignore the setting, so applications should not depend on the presence of hidden reasoning output as part of their correctness model.

import { defineAgent } from '@flue/runtime';
 
export default defineAgent(() => ({
  model: 'anthropic/claude-sonnet-4-6',
  thinkingLevel: 'high',
}));

Providers and Selection

A provider is the service through which Flue reaches a model. Some models are available through their native provider, through routing gateways, or through platform bindings, so the provider ID in the specifier is more than a label. It selects the connection path that owns authentication, base URL behavior, headers, model metadata, and any transport-specific options. In a simple application, this may just mean using anthropic/... or openai/...; in a platform deployment, it may mean routing model calls through cloudflare/... so the runtime can use Cloudflare-specific capabilities.

Sources: apps/docs/src/content/docs/guide/models.md

Provider registration is the extension point for changing how a provider ID resolves at runtime. The Provider API documentation defines registerProvider(providerId, registration) for provider IDs used in model specifiers, and ordinary HTTP registrations can include fields such as API type, base URL, API key, headers, context window, maximum tokens, and model definitions. When the provider ID is already known by Flue’s catalog, registration layers your options on top of catalog defaults. When the provider ID is new, registration supplies the connection information needed to make specifiers like ollama/llama3.1:8b usable.

Cloudflare Workers AI

Cloudflare is a special provider path because Cloudflare-target applications can run agents and workflows inside Workers and Durable Objects. In that environment, Workers AI can be reached through Cloudflare bindings rather than ordinary provider API keys. The model specifier still uses the same Flue convention, but the provider ID is cloudflare, and the model ID can refer either to a native Workers AI model such as @cf/moonshotai/kimi-k2.6 or to a routed model ID such as openai/gpt-5.5. This keeps agent code portable while allowing deployment-specific provider resolution.

Sources: apps/docs/src/content/docs/guide/models.md

When using the Cloudflare target, model choice sits alongside other platform constraints. Generated agents and workflows run inside Cloudflare Durable Objects, and the target integrates with Worker primitives where appropriate. That means a Cloudflare-hosted harness can combine durable agent state, Workers AI model calls, and Cloudflare sandbox options without forcing application code to manage separate long-lived process infrastructure. For local development or non-Cloudflare deployment, the same agent-level model field still expresses intent; only provider registration and runtime target details change.

Compact Reference

Implementation Guidance

Start with the work the agent must perform, then choose a model and provider path that fit that work. A support triage agent may value cost and speed for routine classification, while a code-review or incident-analysis agent may need a stronger model and a higher thinkingLevel. Keep the provider prefix explicit in source code so readers can see whether the application expects Anthropic, OpenAI, OpenRouter, Cloudflare Workers AI, or another registered provider. If you later move through a gateway, update provider registration rather than hiding the provider choice in unrelated application code.

Sources: apps/docs/src/content/docs/guide/models.md

For production projects, separate three concerns: agent defaults, per-operation overrides, and provider registration. Agent modules should state the normal model and reasoning posture for that resource. Operations should override only when they have a concrete reason, such as a specialized skill or high-stakes task. Provider setup should live where the runtime can initialize it consistently for the chosen target. After model selection is working, read the Provider API for registration signatures, Building Agents for harness composition, Subagents for delegation-specific defaults, and the Cloudflare target guide if you plan to use Workers AI bindings.