Reasoning models

Some models can generate an internal chain of thought before producing their answer. Flux exposes this through a single parameter, reasoning_effort, that works across Anthropic, OpenAI, Google, and Ollama. Each provider maps the setting differently under the hood.

The reasoning_effort parameter

Pass reasoning_effort to agent() to enable thinking on supported models. The accepted values are "low", "medium", "high", or None (the default, which disables thinking entirely).

from flux import workflow, ExecutionContext
from flux.tasks.ai import agent

@workflow
async def deep_analysis(ctx: ExecutionContext):
    analyst = await agent(
        "You are a research analyst. Think carefully before drawing conclusions.",
        model="anthropic/claude-sonnet-4-20250514",
        reasoning_effort="high",
    )
    return await analyst(ctx.input["question"])

Passing any value other than "low", "medium", "high", or None raises a ValueError before reaching the provider.

Per-provider behavior

"low", "medium", and "high" map to different API features depending on the provider, and those differences have real cost and latency consequences.

Anthropic

Flux passes thinking={"type": "adaptive"} and output_config={"effort": <value>} to the Anthropic Messages API. The model decides how many thinking tokens to generate, within the constraint the effort level implies. Thinking blocks appear in the event log as reasoning messages in working memory, with the encrypted signature field preserved for multi-turn conversations.

assistant = await agent(
    "You are a financial analyst.",
    model="anthropic/claude-sonnet-4-20250514",
    reasoning_effort="medium",
)

OpenAI

For o-series models, Flux passes reasoning_effort directly as a Chat Completions parameter. The value is forwarded without modification; OpenAI handles the mapping from low | medium | high to internal compute allocation.

assistant = await agent(
    "You are a code reviewer.",
    model="openai/o3-mini",
    reasoning_effort="low",
)

Standard GPT models do not support reasoning_effort. Use o-series models (o1, o3, o3-mini, o4-mini) when setting this parameter with OpenAI.

Google Gemini

Flux maps the three levels to a ThinkingConfig token budget:

assistant = await agent(
    "You are a scientific reasoning assistant.",
    model="google/gemini-2.5-flash",
    reasoning_effort="high",
    max_tokens=8192,
)

The budget caps how many tokens Gemini can spend on internal thought before generating its response. Higher budgets improve output quality on complex tasks but increase latency and cost proportionally.

Ollama

Flux passes the chosen effort level through to Ollama’s think setting, preserving the "low", "medium", and "high" distinction. Models that accept a thinking level map each value to its corresponding depth; models that support only an on/off thinking toggle fall back to enabling thinking.

assistant = await agent(
    "You are a research assistant. Think carefully before acting.",
    model="ollama/qwen3",
    reasoning_effort="high",  # passed through to Ollama's think setting
)

Thinking traces are still captured in working memory as reasoning role messages, so you can inspect them after the agent returns.

Thinking traces in working memory

When reasoning is enabled, the internal chain of thought is stored in working memory alongside the conversation. You can read it back after the agent completes:

from flux import workflow, ExecutionContext, task
from flux.tasks.ai import agent
from flux.tasks.ai.memory import working_memory
import asyncio, json

@task
async def search_topic(topic: str) -> str:
    """Search for information about a topic."""
    await asyncio.sleep(0.1)
    return f"Research results for: {topic}"

@workflow
async def reasoning_agent(ctx: ExecutionContext):
    input_data = ctx.input or {}
    question = input_data.get("question", "Explain how transformers work")
    model = input_data.get("model", "ollama/qwen3")
    effort = input_data.get("reasoning_effort", "high")

    wm = working_memory(max_tokens=50_000)

    assistant = await agent(
        "You are a research assistant. Think carefully before acting. "
        "Use search_topic to gather information before answering.",
        model=model,
        tools=[search_topic],
        working_memory=wm,
        reasoning_effort=effort,
        max_tool_calls=10,
        stream=False,
    )

    answer = await assistant(question)

    wm_messages = wm.recall()
    reasoning_messages = [m for m in wm_messages if m["role"] == "reasoning"]

    return {
        "answer": answer,
        "thinking_count": len(reasoning_messages),
        "thinking_traces": [
            json.loads(m["content"]).get("text", "") for m in reasoning_messages
        ],
    }

The reasoning role messages contain JSON. The text field holds the thinking text; Anthropic responses also include an opaque field with the raw thinking block (including the signature needed for multi-turn continuity).

Cost and latency

Reasoning tokens cost more than output tokens on every provider that charges for them.

Reach for "low" on routing, classification, and similar lookups where speed matters more than exhaustive analysis. "medium" is a reasonable default; the model works through a problem without spending heavily on deep search. Use "high" on code generation, multi-step planning, or formal analysis where correctness justifies the added latency. Omit reasoning_effort (or pass None) for conversational agents and structured extraction, where extended thinking adds nothing.

Flux does not expose thinking token counts in the response. Check your provider dashboard directly to see thinking token usage.

Running the example

The examples/ai/reasoning_agent_ollama.py file in the Flux source demonstrates a reasoning agent with tool calling over Ollama:

# Pull a model that supports thinking
ollama pull qwen3

# Run inline
python examples/ai/reasoning_agent_ollama.py

# Or via the server
flux start server
flux start worker
flux workflow register examples/ai/reasoning_agent_ollama.py
flux workflow run reasoning_agent '{"question": "Compare Python and Rust for web APIs", "reasoning_effort": "high"}'

The workflow returns the answer, a count of thinking blocks, and the raw thinking traces for inspection.

Next steps

• Memory: store conversation history and long-term facts across agent calls.
• Planning: pair reasoning models with structured plans for multi-step tasks.
• Sub-agents: delegate to specialized agents from a coordinating agent.