ModelSettings

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.

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

int

default:"Model-dependent"

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

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

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

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

str | List[str]

default:"None"

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

int

default:"None"

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

str | dict

default:"None"

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

bool

default:"None"

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

str

default:"None"

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

str

default:"None"

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

int

default:"None"

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

dict

default:"None"

Arbitrary key/value pairs attached to the provider request.

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

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

Celesto CLI

SmolVM API

SmolVM CLI

Agentor API

Overview

Import

Usage

Common Parameters

Examples

Creative Writing

Precise Technical Responses

Concise Responses

Reducing Repetition

From Markdown File

Parameter Selection Guide

By Use Case

Combining Parameters

Notes

​Overview

​Import

​Usage

​Common Parameters

​Examples

​Creative Writing

​Precise Technical Responses

​Concise Responses

​Reducing Repetition

​From Markdown File

​Parameter Selection Guide

​By Use Case

​Combining Parameters

​Notes

​Related

Overview

Import

Usage

Common Parameters

Examples

Creative Writing

Precise Technical Responses

Concise Responses

Reducing Repetition

From Markdown File

Parameter Selection Guide

By Use Case

Combining Parameters

Notes

Related