Skip to main content

​
Overview

ModelSettings is a configuration class from the agents library that controls LLM behavior including temperature, token limits, and other generation parameters. It’s used with the Agentor class to fine-tune model responses.

​
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

While ModelSettings is defined in the agents library, here are the commonly used parameters:
​
temperature
float
default:"1.0"
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
List[str]
default:"None"
Sequences where the model will stop generating. Maximum of 4 sequences.

​
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: ["web_search"]
---

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 CaseTemperatureTop PMax TokensNotes
Code generation0.0-0.20.12000+Deterministic, precise
Technical writing0.3-0.50.51500Balanced, accurate
Creative writing0.8-1.00.952000+Diverse, imaginative
Summarization0.3-0.50.5500Concise, factual
Conversation0.7-0.90.91000Natural, engaging
Data extraction0.0-0.10.1500Consistent, 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

  • ModelSettings is imported from the agents library but re-exported by agentor for convenience
  • If not provided, Agentor uses sensible defaults via get_default_model_settings()
  • Temperature and top_p are alternative sampling methods - typically you should adjust one or the other, not both
  • Different models may interpret these parameters differently
  • Some parameters may not be supported by all model providers
  • Agentor - Main agent class that uses ModelSettings
  • LLM - Lightweight LLM client
  • LitellmModel - Custom model wrapper
Last modified on March 4, 2026