Struct AgentLoopConfig 

pub struct AgentLoopConfig {

    pub model_id: String,
    pub system_prompt: Option<String>,
    pub temperature: f32,
    pub max_tokens: u32,
    pub tool_execution: ToolExecutionMode,
    pub compaction_strategy: CompactionStrategy,
    pub context_window: usize,
    pub compaction_instruction: Option<String>,
    pub compactor: Option<Arc<dyn Compactor>>,
    pub session_id: Option<String>,
    pub transport: Option<String>,
    pub compact_on_start: bool,
    pub max_retry_delay_ms: Option<u64>,
    pub auto_retry_enabled: bool,
    pub auto_retry_max_attempts: usize,
    pub auto_retry_base_delay_ms: u64,
    pub workspace_dir: Option<PathBuf>,
    pub provider_options: Option<ProviderOptions>,
    pub on_compaction: Option<Arc<dyn Fn(CompactedContext) -> Pin<Box<dyn Future<Output = Result<(), Error>> + Send>> + Send + Sync>>,
    pub snapshot_store: Option<Arc<dyn SnapshotStore>>,
    pub memory: Option<Arc<dyn MemoryBackend>>,
    pub url_resolver: Option<Arc<dyn UrlResolver>>,
    pub todo: Option<Arc<dyn TodoStateProvider>>,
    pub agent_pool: Option<Arc<dyn AgentPoolProvider>>,
    pub lsp: Option<Arc<dyn LspProvider>>,
    pub ttsr_engine: Option<Arc<TtsrEngine>>,
    pub subagent_runner: Option<Arc<dyn SubagentRunner>>,
    pub subagent_depth: u8,
    pub max_tool_result_bytes: Option<usize>,
    pub thinking_loop_detection: bool,
    pub tool_call_loop_guard: ToolCallLoopGuardOptions,
    pub approval_config: ApprovalConfig,
    pub mode: Mode,
    pub soft_requirements: Vec<SoftRequirement>,
    pub harmony_leak_detection: bool,
    pub dialect: Option<Dialect>,
    pub circuit_breaker: Option<Arc<dyn CircuitBreaker>>,
}

Stable since 0.63.0

Configuration for an [`crate::AgentLoop`] instance.

Fields

model_id: String

Model identifier in provider/model format.

system_prompt: Option<String>

Optional system prompt prepended to every request.

temperature: f32

Sampling temperature (0.0 – 2.0).

max_tokens: u32

Maximum tokens the model may generate per request.

tool_execution: ToolExecutionMode

Whether tool calls run in parallel or sequentially.

compaction_strategy: CompactionStrategy

Compaction strategy for managing context window usage.

context_window: usize

Approximate context window size in tokens.

compaction_instruction: Option<String>

Optional instruction injected into the compaction prompt.

compactor: Option<Arc<dyn Compactor>>

Custom compactor injected at loop construction.

When Some, this replaces the default LLM compactor (the CompactionManager has a single compactor slot — set_compactor overwrites). None (default) preserves the existing behavior: an LlmCompactor is built from the resolved model when the strategy is not Disabled.

SDK consumers set this via AgentBuilder::with_compactor (e.g. with the oxicode_sdk::snapcompact_compactor::SnapcompactCompactor in oxicode-sdk).

session_id: Option<String>

Optional session identifier for logging and tracing.

transport: Option<String>

Optional transport override (e.g. “sse”, “stdio”).

compact_on_start: bool

Whether to trigger compaction before the first turn.

max_retry_delay_ms: Option<u64>

Optional cap on retry back-off delay (milliseconds).

auto_retry_enabled: bool

Enable automatic retry on retryable assistant errors.

auto_retry_max_attempts: usize

Maximum number of auto-retry attempts.

auto_retry_base_delay_ms: u64

Base delay in milliseconds for auto-retry exponential back-off.

workspace_dir: Option<PathBuf>

Working directory for file tools. Defaults to current directory if None.

provider_options: Option<ProviderOptions>

Per-provider options for fine-grained control.

Passed through to oxicode_ai::StreamOptions::provider_options so the provider can read provider-specific settings.

on_compaction: Option<Arc<dyn Fn(CompactedContext) -> Pin<Box<dyn Future<Output = Result<(), Error>> + Send>> + Send + Sync>>

Async hook invoked after context compaction completes.

Unlike the Compaction event in the Fn callback, this hook is async and its future is awaited within the agent loop. Errors are logged at WARN level but don’t fail the loop.

Use this for side effects that require async I/O (e.g., persisting compaction summaries to a memory store) without resorting to tokio::spawn fire-and-forget.

snapshot_store: Option<Arc<dyn SnapshotStore>>

Snapshot store for hashline edit mode.

memory: Option<Arc<dyn MemoryBackend>>

Memory backend for memory tools.

url_resolver: Option<Arc<dyn UrlResolver>>

URL resolver for internal protocol schemes.

todo: Option<Arc<dyn TodoStateProvider>>

Todo state provider for the todo tool.

agent_pool: Option<Arc<dyn AgentPoolProvider>>

Agent pool for Hub display.

lsp: Option<Arc<dyn LspProvider>>

LSP provider for the lsp tool.

ttsr_engine: Option<Arc<TtsrEngine>>

TTSR engine for stream rule checking.

subagent_runner: Option<Arc<dyn SubagentRunner>>

In-process sub-agent runner (issue #28 gap 3). When Some, the subagent tool prefers an in-process isolated run over shelling out to the CLI. Library consumers set this so delegation works without an oxicode subprocess.

subagent_depth: u8

Current sub-agent nesting depth (issue #28 gap 3).

The CLI backend uses env vars (OXICODE_SUBAGENT_DEPTH) for this, which is safe because each subprocess has its own env. The in-process backend cannot use env vars (concurrent set_var is UB; state leaks between forks), so it reads this field instead. Default 0 (top-level). The subagent tool increments this when creating a forked AgentLoopConfig, and the fork checks it against the agent definition’s max_subagent_depth to cap recursion.

max_tool_result_bytes: Option<usize>

Maximum size (in bytes) of a single tool result’s text content before it is truncated (issue #28 gap 1).

When set, tool results exceeding this limit are truncated to the limit and a marker is appended: "... [truncated: N bytes omitted]". This prevents a single large tool output (e.g. reading a huge file, verbose bash output) from consuming the entire context window.

None (default) = no limit. Opt-in — existing behavior is preserved.

thinking_loop_detection: bool

Enable thinking-loop detection in the streaming layer. When true, each ThinkingDelta is fed to a detector that recognises verbatim tail repetition, near-duplicate paragraph clusters, and progress-lexicon stalls. On detection the stream is aborted with a transient error so the retry layer resamples.

Default: true. Set to false to disable (e.g. for tests that exercise specific failure modes).

tool_call_loop_guard: ToolCallLoopGuardOptions

Settings for the cross-turn tool-call loop guard. When the same single-tool call repeats past the threshold, the agent emits a steering message to break the loop. Default: threshold 5, with read/ls/grep exempt.

approval_config: ApprovalConfig

Approval/tier configuration for gating tool execution.

When configured, tool calls at tiers in require_approval_for are checked against the approval hook before execution. Default: no approval gating (all tools allowed without check).

mode: Mode

Autonomy mode — threaded from crate::config::AgentConfig::mode. In crate::config::Mode::Auto the agent runs without user interaction (the ask tool is short-circuited). Default: crate::config::Mode::Default.

soft_requirements: Vec<SoftRequirement>

Soft tool requirements: tools the agent should call.

On the first turn where a soft-required tool is missing, the loop injects a reminder steering message. On the second consecutive miss, it escalates. Default: empty (no soft requirements).

harmony_leak_detection: bool

Enable GPT-5 Harmony protocol leak detection.

When true, each text delta is scanned for Harmony markers (to=functions.xxx, <|start|>, etc.). On detection, the stream is aborted, a HarmonyLeakDetected event is emitted, and the turn is restarted. Default: false.

dialect: Option<Dialect>

Owned (in-band) tool-calling dialect.

When Some, the loop targets models without native tool support: it sends no native tools, injects the tool catalog into the system prompt, re-encodes prior tool calls/results as text in the history, and parses the model’s text output back into canonical tool calls. Mirrors omp’s AgentLoopConfig.dialect / PI_DIALECT.

None (default) keeps provider-native tool calling.

circuit_breaker: Option<Arc<dyn CircuitBreaker>>

Optional circuit breaker for provider calls. When Some, the agent loop’s retry path consults the breaker before each provider attempt (breaker.check()); an open circuit short-circuits the retry loop and returns immediately (the breaker’s whole purpose is to stop hammering a failing upstream). On every successful call the breaker records success; on every error it records failure. When None, no circuit breaking occurs (default — preserves existing behavior).

This is the SDK-owned behavior trait + reference impl; consumers implement oxicode_ai::circuit_breaker::CircuitBreaker for their domain profile (A2A, HTTP, etc.) and pass the impl here. See docs/oxicode-sdk-ownership.md §3.

Trait Implementations

impl Clone for AgentLoopConfig

fn clone(&self) -> AgentLoopConfig

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Default for AgentLoopConfig

fn default() -> AgentLoopConfig

Returns the “default value” for a type.