ModelSettings

ModelSettings reference: tune temperature, max tokens, top-p, and other LLM generation parameters when configuring an Agentor agent.

Overview

ModelSettings controls how the model generates text — temperature, token limits, and the rest. Pass one to the Agentor class to tune responses.

It is provider-neutral on purpose: the parameters below are understood everywhere, and anything else you pass is forwarded to the provider untouched. That means a provider-specific parameter needs no support from Agentor.

Import

from agentor import ModelSettings

Usage

from agentor import Agentor, ModelSettings

model_settings = ModelSettings(
    temperature=0.7,
    max_tokens=1000,
    top_p=0.9
)

agent = Agentor(
    name="Assistant",
    model="gpt-4o",
    model_settings=model_settings
)

Common Parameters

Every parameter defaults to unset, and unset parameters are left out of the request entirely — so the provider’s own default applies.

temperature · float · default: "unset"

Controls randomness in outputs. Lower values (0.0-0.3) make outputs more focused and deterministic. Higher values (0.7-1.0) make outputs more creative and varied.

• 0.0-0.3: Precise, consistent, factual responses
• 0.4-0.6: Balanced creativity and consistency
• 0.7-1.0: Creative, diverse, exploratory responses

max_tokens · int · default: "Model-dependent"

Maximum number of tokens to generate in the response. Limits the length of the model’s output.

top_p · float · default: "1.0"

Nucleus sampling parameter. Controls diversity by limiting cumulative probability. Alternative to temperature.

• 0.1-0.5: More focused, deterministic
• 0.9-1.0: More diverse outputs

presence_penalty · float · default: "0.0"

Penalizes tokens based on whether they appear in the text so far. Range: -2.0 to 2.0.

• Positive values encourage new topics
• Negative values encourage staying on topic

frequency_penalty · float · default: "0.0"

Penalizes tokens based on their frequency in the text. Range: -2.0 to 2.0.

• Positive values reduce repetition
• Negative values allow more repetition

stop · str | List[str] · default: "None"

Sequences where the model will stop generating. Maximum of 4 sequences.

seed · int · default: "None"

Ask the provider for reproducible sampling. Support varies by provider.

tool_choice · str | dict · default: "None"

Force or forbid tool use: "auto", "none", "required", or a specific tool.

parallel_tool_calls · bool · default: "None"

Allow the model to request several tools in one turn. Agentor runs them concurrently.

reasoning_effort · str · default: "None"

For reasoning models: how much thinking to do before answering.

verbosity · str · default: "None"

For models that support it: how long the answer should be.

top_logprobs · int · default: "None"

Number of most-likely tokens to return log probabilities for.

metadata · dict · default: "None"

Arbitrary key/value pairs attached to the provider request.

extra · dict · default: "{}"

Extra request parameters, passed through verbatim. Unrecognised keyword arguments land here automatically, so ModelSettings(some_provider_flag=True) works without listing it.

A handful of parameters from the pre-0.1.0 settings type have no chat-completions equivalent — truncation, retry, context_management, include_usage, prompt_cache_options, prompt_cache_retention, response_include. They are accepted and dropped with a warning rather than sent and rejected.

Examples

Creative Writing

from agentor import Agentor, ModelSettings

creative_settings = ModelSettings(
    temperature=0.9,
    top_p=0.95,
    max_tokens=2000,
    presence_penalty=0.6
)

agent = Agentor(
    name="Creative Writer",
    model="gpt-4o",
    model_settings=creative_settings,
    instructions="You are a creative storytelling assistant."
)

result = agent.run("Write a short story about a time traveler")

Precise Technical Responses

from agentor import Agentor, ModelSettings

precise_settings = ModelSettings(
    temperature=0.2,
    top_p=0.1,
    max_tokens=1500
)

agent = Agentor(
    name="Code Assistant",
    model="gpt-4o",
    model_settings=precise_settings,
    instructions="You are a precise coding assistant."
)

result = agent.run("Explain how to implement a binary search tree")

Concise Responses

from agentor import Agentor, ModelSettings

concise_settings = ModelSettings(
    temperature=0.3,
    max_tokens=100,
    stop=["\n\n"]  # Stop at double newline
)

agent = Agentor(
    name="Concise Assistant",
    model="gpt-4o",
    model_settings=concise_settings,
    instructions="Provide brief, single-paragraph answers."
)

Reducing Repetition

from agentor import Agentor, ModelSettings

varied_settings = ModelSettings(
    temperature=0.7,
    frequency_penalty=0.5,
    presence_penalty=0.3
)

agent = Agentor(
    name="Varied Assistant",
    model="gpt-4o",
    model_settings=varied_settings
)

From Markdown File

You can also specify temperature in markdown frontmatter:

---
name: Research Agent
model: gpt-4o
temperature: 0.5
tools: ["current_datetime"]
---

You are a research assistant that provides accurate information.

from agentor import Agentor, ModelSettings

# Temperature from markdown will be merged
additional_settings = ModelSettings(
    max_tokens=2000,
    top_p=0.9
)

agent = Agentor.from_md(
    "research_agent.md",
    model_settings=additional_settings
)

Parameter Selection Guide

By Use Case

Use Case	Temperature	Top P	Max Tokens	Notes
Code generation	0.0-0.2	0.1	2000+	Deterministic, precise
Technical writing	0.3-0.5	0.5	1500	Balanced, accurate
Creative writing	0.8-1.0	0.95	2000+	Diverse, imaginative
Summarization	0.3-0.5	0.5	500	Concise, factual
Conversation	0.7-0.9	0.9	1000	Natural, engaging
Data extraction	0.0-0.1	0.1	500	Consistent, accurate

Combining Parameters

from agentor import ModelSettings

# Balanced configuration
balanced = ModelSettings(
    temperature=0.7,
    top_p=0.9,
    max_tokens=1500,
    frequency_penalty=0.0,
    presence_penalty=0.0
)

# High creativity
creative = ModelSettings(
    temperature=0.9,
    top_p=0.95,
    max_tokens=2000,
    presence_penalty=0.6,
    frequency_penalty=0.3
)

# Maximum precision
precise = ModelSettings(
    temperature=0.0,
    top_p=0.1,
    max_tokens=1000,
    frequency_penalty=0.0,
    presence_penalty=0.0
)

Notes

• Import it from agentor directly: from agentor import ModelSettings
• If you pass nothing, no generation parameters are sent and the provider’s defaults apply
• Temperature and top_p are alternative sampling methods — adjust one or the other, not both
• Different models interpret these parameters differently, and not every provider supports every one

Related

• Agentor - Main agent class that uses ModelSettings
• Model providers - Reach any OpenAI-compatible endpoint
• LLM - Lightweight LLM client