Agent Configuration

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.agent import Agent, AgentConfig
from definable.model 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

str

Unique identifier for the agent. Auto-generated UUID if not set.

str

Human-readable name used in logs and traces.

Execution

int

default:"10"

Maximum number of model-call-then-tool-execution loops before stopping. Prevents infinite loops when the model keeps calling tools.

int

Token limit per run. Stops execution if exceeded.

float

default:"300.0"

Timeout in seconds for streaming responses.

Reliability

bool

default:"true"

Automatically retry on transient network errors.

int

default:"3"

Maximum number of retry attempts for transient errors.

bool

default:"true"

Validate tool arguments against their schema before execution.

State & Dependencies

Dict[str, Any]

Default session state available to tools. Merged with per-run state.

Dict[str, Any]

Dependencies injected into tools that declare them (e.g., database connections, API clients).

Tracing

Tracing configuration (backward compat). Prefer passing tracing=Tracing(...) directly to Agent. See Tracing for details.

Compression

Compression is configured directly on the Agent constructor (not in AgentConfig):

from definable.agent import Agent
from definable.agent.compression import Compression

# Defaults
agent = Agent(model="openai/gpt-4o", compression=True)

# Custom
agent = Agent(model="openai/gpt-4o", compression=Compression(tool_results_limit=5))

Readers

ReadersConfig

File reader configuration for processing attached files. See File Readers.

Memory

Memory is configured directly on the Agent constructor:

from definable.agent import Agent
from definable.memory import Memory, SQLiteStore

# Ephemeral in-memory store (useful for testing)
agent = Agent(model=model, memory=True)

# Persistent store via Memory
agent = Agent(
    model=model,
    memory=Memory(
        store=SQLiteStore("./memory.db"),
    ),
)

See Memory for full documentation.

Knowledge

Knowledge (RAG) is configured directly on the Agent constructor:

from definable.agent import Agent

# Auto-configures InMemoryVectorDB + OpenAIEmbedder + RecursiveChunker
# Recursively loads all supported files from the directory
agent = Agent(model=model, knowledge="./docs/")

from definable.agent import Agent
from definable.embedder import OpenAIEmbedder
from definable.knowledge import Knowledge
from definable.vectordb import InMemoryVectorDB

kb = Knowledge(
    vector_db=InMemoryVectorDB(),
    embedder=OpenAIEmbedder(),
    top_k=5,
    rerank=True,
    trigger="always",  # "always", "auto", or "never"
)
kb.add("Company policy: employees get 20 days PTO per year.")

agent = Agent(model=model, knowledge=kb)

Agent(knowledge=True) raises ValueError — unlike memory=True, knowledge requires explicit configuration. Use a path string or a Knowledge instance.

See Knowledge Agent Integration for full documentation.

Thinking

The thinking layer is configured directly on the Agent constructor (not in AgentConfig):

from definable.agent import Agent
from definable.agent.reasoning import Thinking

# Simple enable
agent = Agent(model=model, thinking=True)

# Custom configuration
agent = Agent(
    model=model,
    thinking=Thinking(
        model=thinking_model,           # Optional separate model
        instructions="Custom prompt",    # Optional custom prompt
    ),
)

See Thinking for full documentation.

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

Compress large tool results to save tokens:

from definable.agent import Agent
from definable.agent.compression import Compression

# Enable with defaults (compress after 3 uncompressed tool results)
agent = Agent(model="openai/gpt-4o", compression=True)

# Custom settings
agent = Agent(
    model="openai/gpt-4o",
    compression=Compression(
        tool_results_limit=3,      # Trigger compression after 3 uncompressed tool results
        token_limit=None,          # Or set a token threshold to trigger compression
        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.agent 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"
    ),
)

bool

default:"true"

Enable or disable file reading.

BaseReader

Custom reader instance. When None, a default BaseReader with all available built-in parsers is created.

int

Maximum total character length of all extracted file content. When None, no limit is applied.

str

default:"xml"

Format for injecting file content into the prompt. "xml" wraps content in XML tags, "markdown" uses code blocks.

Audio Transcription

The audio transcriber is configured directly on the Agent constructor. It automatically transcribes voice messages (from Telegram, Discord, or direct arun() calls) to text before the model sees them.

from definable.agent import Agent

# Simple enable (uses OpenAI Whisper)
agent = Agent(model=model, audio_transcriber=True)

# Custom configuration
from definable import OpenAITranscriber
agent = Agent(
    model=model,
    audio_transcriber=OpenAITranscriber(
        model="whisper-1",    # Whisper model
        language="en",        # Language hint (improves accuracy)
        api_key=None,         # Falls back to OPENAI_API_KEY env var
    ),
)

See Vision & Audio for full documentation.

How It Works

When audio_transcriber is set:

Before the pipeline runs, _transcribe_audio() iterates over messages with Audio attachments
Each audio clip is transcribed via the configured backend (Whisper by default)
The transcript text is appended to the message’s content field
The audio field is cleared from the message so non-audio models don’t receive raw input_audio blocks

Without audio_transcriber, voice messages from interfaces arrive as raw Audio objects. Most models (GPT-4o-mini, Claude, DeepSeek) will reject input_audio blocks — only gpt-4o-audio-preview supports them natively.

Security

Security features are configured directly on the Agent constructor:

from definable.agent import Agent
from definable.agent.security import SecurityConfig, ToolPolicy

# Simple enable (default config)
agent = Agent(model=model, security=True)

# Full configuration
agent = Agent(
    model=model,
    security=SecurityConfig(
        tool_policy=ToolPolicy(mode="allowlist", allowed_tools={"search_web"}),
    ),
)

# Security audit
report = await agent.security_audit()
print(f"Score: {report.score}/100")

See Security for full documentation on tool policies, rate limiting, prompt injection detection, SSRF protection, and security audits.

Usage Tracking

Track token usage and estimated cost across agent runs:

from definable.agent import Agent

agent = Agent(model=model, usage=True)
output = await agent.arun("Hello")

print(agent.usage_tracker.session_total)  # Cumulative tokens + cost
print(agent.usage_tracker.last_run)       # Most recent run
print(agent.usage_tracker.run_count)      # Total runs tracked

Deep Research

The deep research layer is configured directly on the Agent constructor:

from definable.agent import Agent
from definable.agent.research import DeepResearchConfig

# Simple enable (standard depth, DuckDuckGo search)
agent = Agent(model=model, deep_research=True)

# Custom configuration
agent = Agent(
    model=model,
    deep_research=DeepResearchConfig(
        depth="deep",                    # "quick", "standard", or "deep"
        search_provider="duckduckgo",    # or "google", "serpapi"
        max_sources=30,
        max_waves=5,
        include_citations=True,
        context_format="xml",
    ),
)

See Deep Research for full documentation.

DeepResearchConfig Reference

str

default:"standard"

Research depth preset. "quick" (1 wave, 8 sources), "standard" (3 waves, 15 sources), "deep" (5 waves, 30 sources).

str

default:"duckduckgo"

Search backend name: "duckduckgo", "google", or "serpapi".

Dict[str, Any]

Backend-specific config (API keys, CSE ID, etc.). Required for Google CSE and SerpAPI.

Callable

Custom async search callable. Overrides search_provider when set.

Model

Model for CKU extraction (should be cheap/fast). Defaults to the agent’s model.

int

default:"15"

Maximum number of unique sources to read across all waves.

int

default:"3"

Maximum number of research waves.

int

default:"5"

Number of concurrent search queries per wave.

int

default:"10"

Number of concurrent page reads.

float

default:"0.3"

Minimum relevance score for CKU inclusion.

bool

default:"true"

Whether to include source citations in the research context.

bool

default:"true"

Whether to surface contradictions between sources.

str

default:"xml"

Format for the injected context: "xml" or "markdown".

int

default:"4000"

Approximate token budget for the research context block.

float

default:"0.2"

Stop when novelty ratio drops below this threshold between waves.

str

default:"always"

When to run research: "always" (every run), "auto" (model decides), "tool" (explicit tool call).

str

Description shown in the layer guide injected into the system prompt. If None, uses the default description.

Get Started

Basics

Capabilities

Advanced

Basic Configuration

Configuration Reference

Identity

Execution

Reliability

State & Dependencies

Tracing

Compression

Readers

Memory

Knowledge

Thinking

Immutable Updates

Compression

Readers Config

Audio Transcription

How It Works

Security

Usage Tracking

Deep Research

DeepResearchConfig Reference

​Basic Configuration

​Configuration Reference

​Identity

​Execution

​Reliability

​State & Dependencies

​Tracing

​Compression

​Readers

​Memory

​Knowledge

​Thinking

​Immutable Updates

​Compression

​Readers Config

​Audio Transcription

​How It Works

​Security

​Usage Tracking

​Deep Research

​DeepResearchConfig Reference

Basic Configuration

Configuration Reference

Identity

Execution

Reliability

State & Dependencies

Tracing

Compression

Readers

Memory

Knowledge

Thinking

Immutable Updates

Compression

Readers Config

Audio Transcription

How It Works

Security

Usage Tracking

Deep Research

DeepResearchConfig Reference