Skip to main content
AgentConfig is an immutable dataclass that controls every aspect of agent behavior. Pass it when creating an agent, or use the defaults.

​
Basic Configuration

from definable.agents import Agent, AgentConfig
from definable.models import OpenAIChat

config = AgentConfig(
    agent_name="Support Agent",
    max_iterations=15,
    max_retries=3,
)

agent = Agent(
    model=OpenAIChat(id="gpt-4o"),
    instructions="You are a customer support agent.",
    config=config,
)

​
Configuration Reference

​
Identity

​
agent_id
str
Unique identifier for the agent. Auto-generated UUID if not set.
​
agent_name
str
Human-readable name used in logs and traces.

​
Execution

​
max_iterations
int
default:"10"
Maximum number of model-call-then-tool-execution loops before stopping. Prevents infinite loops when the model keeps calling tools.
​
max_tokens
int
Token limit per run. Stops execution if exceeded.
​
stream_timeout_seconds
float
default:"300.0"
Timeout in seconds for streaming responses.

​
Reliability

​
retry_transient_errors
bool
default:"true"
Automatically retry on transient network errors.
​
max_retries
int
default:"3"
Maximum number of retry attempts for transient errors.
​
validate_tool_args
bool
default:"true"
Validate tool arguments against their schema before execution.

​
State & Dependencies

​
session_state
Dict[str, Any]
Default session state available to tools. Merged with per-run state.
​
dependencies
Dict[str, Any]
Dependencies injected into tools that declare them (e.g., database connections, API clients).

​
Tracing

​
tracing
TracingConfig
Tracing configuration. See Tracing for details.

​
Knowledge

​
knowledge
KnowledgeConfig
RAG configuration for automatic knowledge retrieval. See Agent Integration.

​
Compression

​
compression
CompressionConfig
Tool result compression to reduce token usage on long tool outputs.

​
Readers

​
readers
ReadersConfig
File reader configuration for processing attached files. See File Readers.

​
Immutable Updates

AgentConfig is frozen after creation. Use with_updates() to create a modified copy: 
base_config = AgentConfig(
    agent_name="Base Agent",
    max_iterations=10,
    max_retries=3,
)

# Create a variant with a different name and higher iteration limit
custom_config = base_config.with_updates(
    agent_name="Custom Agent",
    max_iterations=20,
)
The original base_config is unchanged. This pattern makes it safe to share configs across agents.

​
Compression Config

Compress large tool results to save tokens: 
from definable.agents import AgentConfig, CompressionConfig

config = AgentConfig(
    compression=CompressionConfig(
        enabled=True,
        tool_results_limit=5000,   # Compress results over 5000 chars
        token_limit=2000,          # Target compressed token count
        instructions="Preserve key facts and data. Remove formatting.",
    ),
)
Compression uses a separate model call to summarize tool output. This adds a small amount of latency but can significantly reduce total token usage for tools that return large results.

​
Readers Config

Configure file reader behavior for processing attached files: 
from definable.agents import AgentConfig, ReadersConfig

config = AgentConfig(
    readers=ReadersConfig(
        enabled=True,
        registry=None,                     # None = auto-create with built-in readers
        max_total_content_length=None,     # Limit total injected content (None = unlimited)
        context_format="xml",              # "xml" or "markdown"
    ),
)
​
readers.enabled
bool
default:"true"
Enable or disable file reading.
​
readers.registry
BaseReader
Custom reader instance. When None, a default BaseReader with all available built-in parsers is created.
​
readers.max_total_content_length
int
Maximum total character length of all extracted file content. When None, no limit is applied.
​
readers.context_format
str
default:"xml"
Format for injecting file content into the prompt. "xml" wraps content in XML tags, "markdown" uses code blocks.