Struct AgentConfig 

pub struct AgentConfig {

    pub name: String,
    pub model: Option<String>,
    pub provider_id: String,
    pub model_name: String,
    pub temperature: f32,
    pub max_tokens: i32,
    pub system_prompt_override: Option<String>,
    pub persona: Option<String>,
    pub max_react_iterations: Option<i32>,
    pub max_scratchpad_size: Option<i32>,
    pub max_retries: Option<i32>,
    pub max_concurrent_jobs: Option<usize>,
    pub supports_native_thinking: bool,
    pub frequency_penalty: Option<f32>,
    pub presence_penalty: Option<f32>,
    pub textual_feedback: bool,
    pub use_streaming: bool,
    pub merge_system_prompt: bool,
    pub unwrap_hallucinated_tool_calls: bool,
    pub repair_invalid_escapes: bool,
    pub scratchpad_limit: i32,
    pub scratchpad_squeeze_fraction: f64,
    pub compact_history_default_keep: usize,
    pub json_mode: bool,
    pub disable_native_tools: bool,
    pub context_window: i32,
    pub reasoning_effort: Option<String>,
    pub tool_format: Option<String>,
    pub input_price_per_mtok: Option<f64>,
    pub output_price_per_mtok: Option<f64>,
    pub chars_per_token: Option<f64>,
    pub orchestrators: Vec<OrchestratorEntry>,
    pub task_precision: Option<HashMap<String, TaskPrecision>>,
    pub failure_dumps: Option<String>,
    pub response_sla_secs: u64,
    pub propagate_payment_error: bool,
    pub capability_tags: Vec<String>,
    pub description: Option<String>,
    pub signing_schemes: Vec<String>,
    pub auto_stop: bool,
    pub exec: Option<ExecProviderConfig>,
    pub mcp: Option<McpProviderConfig>,
    pub claude: Option<ClaudeProviderConfig>,
    pub provider_config: HashMap<String, Value>,
    pub openrouter: Option<OpenRouterConfig>,
    pub builtin_tools: Vec<BuiltinToolGrant>,
    pub prompt_exposure_guard: bool,
    pub middleware: MiddlewareConfig,
    pub read_file_roots: Vec<PathBuf>,
}

Configuration for a specific agent.

Fields

name: String

model: Option<String>

Dotpath model reference: "provider_id.model_key". When set, resolves the provider and merges ModelDef fields into this agent at config load time (load_agent_from_config). Replaces the legacy provider_id + model_name + flat LLM field pattern.

provider_id: String

Legacy provider reference. When model is set, this is overwritten during resolution. Kept for backward compatibility.

model_name: String

temperature: f32

max_tokens: i32

system_prompt_override: Option<String>

persona: Option<String>

max_react_iterations: Option<i32>

max_scratchpad_size: Option<i32>

max_retries: Option<i32>

max_concurrent_jobs: Option<usize>

Max jobs this agent runs concurrently. Enforced as the pull consumer’s max_ack_pending, so the broker withholds the next task until an in-flight one finishes. Set to 1 for agents whose jobs mutate shared state (e.g. a git repo a middleware resets per job) to prevent races. None (default) leaves it unbounded.

supports_native_thinking: bool

frequency_penalty: Option<f32>

presence_penalty: Option<f32>

Presence penalty for the model. Defaults to Some(1.5) to encourage diverse vocabulary in multi-agent deliberation (reduces repetitive phrasing across rounds). Set to None or 0.0 in config to disable.

textual_feedback: bool

use_streaming: bool

merge_system_prompt: bool

unwrap_hallucinated_tool_calls: bool

repair_invalid_escapes: bool

scratchpad_limit: i32

scratchpad_squeeze_fraction: f64

Fraction of max_scratchpad_size at which compact_history also auto-squeezes the scratchpad. Default 0.95 — leaving 5% headroom keeps the next tool call from immediately tripping the persistence cap.

compact_history_default_keep: usize

Default value of compact_history(keep_last_n_calls) when the model omits the argument. Two recent tool results give the model enough context to reason while older results fold into the scratchpad summary.

json_mode: bool

disable_native_tools: bool

context_window: i32

reasoning_effort: Option<String>

tool_format: Option<String>

input_price_per_mtok: Option<f64>

USD per million input tokens. Used for cost estimation in budget reporting.

output_price_per_mtok: Option<f64>

USD per million output tokens. Used for cost estimation in budget reporting.

chars_per_token: Option<f64>

Characters per token for heuristic estimation when the provider doesn’t return usage stats. Deserialized as Option<f64> (None when absent in config). The runtime fallback of 4.0 (English approximation) is applied at the call site via .unwrap_or(4.0) in nsed_agent.rs; set lower (~1.5) for CJK/code.

orchestrators: Vec<OrchestratorEntry>

Per-agent orchestrator extensions (additive to the process-wide list). Only used at agent startup for connection resolution; never serialized over NATS since this is deployment topology, not agent behavior.

task_precision: Option<HashMap<String, TaskPrecision>>

Per-task-category precision parameters for the thermodynamic model. Map from task category (e.g. “supply”, “audit”, “quant”, “legal”) to { pg, pv } where pg = zero-shot generation precision, pv = verification precision. Used by the dashboard to compute the NSED utility function: U(t) = 1 - (1-pg) * exp(-Lambda*(pv-pg)t) - betat^2 If absent, the dashboard falls back to built-in MODEL_PRECISION defaults.

failure_dumps: Option<String>

Controls failure dump output when parse or API errors occur. Values: "on" (default — dump error + raw response), "full" (include system prompt, request body, and messages), "off" (disable). Dumps are written to failures/<session>_<agent>/. Can also be set globally via the NSED_FAILURE_DUMPS env var (1 = on, full = full). The config value takes precedence over the env var.

response_sla_secs: u64

Maximum seconds this agent needs to complete a single task (propose or evaluate). When > 0, this is a hard infrastructure constraint — the orchestrator will never give this agent less time than this value per phase. Set to 0 to opt out of SLA reporting (the field is omitted from heartbeats). Defaults to 3600s (1 hour).

propagate_payment_error: bool

Whether to propagate 402 Payment Required errors to the orchestrator. When true (default), an agent_error event is published immediately. When false, the agent silently pauses and lets the orchestrator timeout.

capability_tags: Vec<String>

Free-form capability tags (e.g., ["legal", "audit", "quantitative"]). Used for filtering in agent picker and directory.

description: Option<String>

Short description of the agent’s specialization. Shown in the agent directory and picker UI.

signing_schemes: Vec<String>

Signing schemes this agent supports (placeholder for #115). Values will be validated against SigningScheme enum when implemented. Empty means no signing support (legacy/internal agent).

auto_stop: bool

When true, buffer entries from this agent are created with stopped = true, preventing auto-release until an external system edits and explicitly releases them via POST /buffer/{id}/release. Used with stub providers for human-operated agents.

exec: Option<ExecProviderConfig>

Configuration for exec-based external agent providers. When provider_type is "exec", the agent spawns a subprocess instead of calling an LLM. See docs/exec-agent-protocol.md.

mcp: Option<McpProviderConfig>

Configuration for MCP-based external agent providers. When provider_type is "mcp", the agent spawns a subprocess and communicates via the Model Context Protocol (stdio transport). See docs/mcp-agent-protocol.md.

claude: Option<ClaudeProviderConfig>

Configuration for Claude CLI as an agent provider. When provider_type is "claude", automatically constructs claude CLI flags from AgentConfig fields (system prompt, model, session) plus Claude-specific options (permission mode, budget, MCP tools). See docs/mcp-agent-protocol.md#claude-provider.

provider_config: HashMap<String, Value>

Free-form provider config for third-party ProviderFactory implementations. Built-in providers (exec / mcp / claude) use their typed sections above; a custom provider.type reads its knobs from here, so registering a new provider needs no new field on this core struct.

Deserialize the whole map into a typed struct with AgentConfig::provider_config_as, or index the map directly.

openrouter: Option<OpenRouterConfig>

OpenRouter-specific request extensions (provider routing + ZDR). Injected into the request body as "provider": { ... } when the underlying base URL is OpenRouter. Non-OpenRouter providers will ignore or reject the block — only set this for OpenRouter agents.

builtin_tools: Vec<BuiltinToolGrant>

Per-agent grants for built-in sandboxed tools. Attached to an agent’s tool list only for the native-LLM provider branch; provider_type: claude / exec / mcp route their tools through provider-native channels (claude sub-agents, the exec subprocess’s own tool surface, MCP server) so grants configured on those agents are silently ignored at runtime (loaders are expected to warn). Use this to give native-LLM agents scoped runtime capabilities (e.g. read files confined to a specific filesystem root) without going through the user_tools NATS dispatcher pipeline.

Each grant becomes a tool in the agent’s tool list at startup. See crate::tools::scoped_read for the read_file implementation and its security model.

prompt_exposure_guard: bool

Enable the prompt_exposure safety guardrail on this agent’s LLM responses. When true, the agent scans every terminal tool-call content (proposal / batch evaluation) for internal-prompt leakage (XML scaffolding tags, canonical tool names, meta-protocol phrases) and forces a retry with a block-reason feedback message when a leak is detected. Defaults to false so existing deployments do not change behavior until explicitly opted in. See docs/middleware.md#prompt_exposure-config for the detection heuristics.

middleware: MiddlewareConfig

Agent middleware pipelines (before_prompt / on_provider_response / on_completion / before_release). Inert unless configured — the worker only runs a pipeline when it’s non-empty, so existing agents are unaffected. Deserialize-only (the config carries a non-serializable runtime moderation_model).

read_file_roots: Vec<PathBuf>

Per-agent filesystem roots for the sandboxed read_file tool. Each entry grants the agent permission to read any file under the canonical path of that root. Symlink targets that resolve outside the root are rejected. Empty (default) means the tool isn’t activated for this agent.

Skipped on serialization so host filesystem paths never travel over the wire (e.g. orchestrator capability advertisements). Loaded from YAML on the agent host only.

Implementations

impl AgentConfig

pub fn provider_config_as<T: DeserializeOwned>(&self) -> Result<T, Error>

Deserialize the whole provider_config map into a typed struct T. Third-party ProviderFactory impls use this to read their bespoke YAML config without adding a typed section to this core struct:

#[derive(serde::Deserialize)]
struct CodexConfig { permission_mode: String, sandbox: bool }
let cfg: CodexConfig = agent_config.provider_config_as()?;

An empty map deserializes to whatever T makes of an empty mapping (e.g. a struct whose fields all have #[serde(default)]).

pub fn validate_provider_sections( &self, resolved_provider_type: Option<&str>, ) -> Result<(), String>

Validate that at most one provider section is populated and, when resolved_provider_type is known, that it matches the populated section.

pub fn validate_compaction_knobs(&self) -> Result<(), String>

Validate compaction knobs land in usable ranges. A scratchpad_squeeze_fraction outside (0.0, 1.0] and a compact_history_default_keep of zero would silently produce degenerate compaction behavior.

Trait Implementations

impl Clone for AgentConfig

fn clone(&self) -> AgentConfig

Returns a duplicate of the value.

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

Performs copy-assignment from source.

impl ComposeSchema for AgentConfig

fn compose(generics: Vec<RefOr<Schema>>) -> RefOr<Schema>

impl Debug for AgentConfig

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl Default for AgentConfig

Manual Default implementation that matches the serde defaults. #[derive(Default)] would set response_sla_secs to 0 and propagate_payment_error to false, which differs from the documented serde defaults (3600s / 1 hour and true respectively).

fn default() -> Self

Returns the “default value” for a type.

impl<'de> Deserialize<'de> for AgentConfig

fn deserialize<__D>(__deserializer: __D) -> Result<Self, __D::Error>

where __D: Deserializer<'de>,

Deserialize this value from the given Serde deserializer.

impl Serialize for AgentConfig

fn serialize<__S>(&self, __serializer: __S) -> Result<__S::Ok, __S::Error>

where __S: Serializer,

Serialize this value into the given Serde serializer.

impl ToSchema for AgentConfig

fn name() -> Cow<'static, str>

Return name of the schema.

fn schemas(schemas: &mut Vec<(String, RefOr<Schema>)>)

Implement reference utoipa::openapi::schema::Schemas for this type.