Struct AgentParams 

pub struct AgentParams {

    pub prompt: String,
    pub system: Option<String>,
    pub provider: Option<String>,
    pub model: Option<String>,
    pub mcp: Vec<String>,
    pub tools: Vec<String>,
    pub max_turns: Option<u32>,
    pub token_budget: Option<u32>,
    pub stop_sequences: Vec<String>,
    pub scope: Option<String>,
    pub extended_thinking: Option<bool>,
    pub thinking_budget: Option<u64>,
    pub depth_limit: Option<u32>,
    pub tool_choice: Option<ToolChoice>,
    pub temperature: Option<f32>,
    pub max_tokens: Option<u32>,
    pub skills: Option<Vec<String>>,
    pub completion: Option<CompletionConfig>,
    pub guardrails: Vec<GuardrailConfig>,
    pub limits: Option<LimitsConfig>,
}

Parameters for the agent: verb

Enables agentic execution with MCP tool access. The agent runs in a loop, calling tools as needed until a stop condition is met or max_turns is reached.

Fields

prompt: String

System/user prompt for the agent

system: Option<String>

System prompt (optional, sets the agent’s behavior/persona)

provider: Option<String>

LLM provider override (defaults to workflow provider)

model: Option<String>

Model override (defaults to workflow model)

mcp: Vec<String>

MCP servers the agent can access for tool calling

tools: Vec<String>

Builtin tools the agent can use (nika:read, nika:write, etc.)

max_turns: Option<u32>

Maximum agentic turns before stopping

token_budget: Option<u32>

Token budget for the entire agent session Stops gracefully when budget is exceeded

stop_sequences: Vec<String>

Sequences that stop generation (passed to LLM)

scope: Option<String>

Scope preset (full, minimal, debug)

extended_thinking: Option<bool>

Enable extended thinking for Claude models

When enabled, the agent captures Claude’s reasoning process in the thinking field of AgentTurn events. Only supported for Claude provider.

thinking_budget: Option<u64>

Token budget for extended thinking (default: 4096)

Controls how many tokens Claude can use for reasoning in extended thinking mode. Higher values allow deeper analysis but cost more. Only used when extended_thinking: true.

depth_limit: Option<u32>

Maximum depth for nested agent spawning (default: 3, max: 10)

Controls how many levels of sub-agents can be spawned recursively. A depth_limit of 1 means no sub-agents can be spawned. Used by spawn_agent internal tool to prevent infinite recursion.

tool_choice: Option<ToolChoice>

Tool choice behavior

Controls when the agent uses tools:

• auto (default): LLM decides when to use tools
• required: Must use at least one tool per turn
• none: Never use tools (text-only response)

temperature: Option<f32>

Model temperature for response randomness

Controls the randomness/creativity of responses:

• 0.0: Deterministic, most focused
• 1.0: Balanced creativity (typical default)
• 2.0: Maximum creativity/randomness

If not set, uses the provider’s default.

max_tokens: Option<u32>

Maximum tokens to generate per turn

Required when using extended_thinking: true with Claude. Must be greater than thinking_budget. If not set with extended thinking enabled, defaults to thinking_budget + 8192.

skills: Option<Vec<String>>

Skills to inject into the agent’s system prompt

List of skill aliases that will be loaded and prepended to the system prompt before each LLM call. Skills are resolved from the workflow’s skills: map.

completion: Option<CompletionConfig>

Completion behavior configuration

Controls how the agent signals task completion:

• mode: explicit - Agent must call nika:complete tool (recommended)
• mode: natural - Completes when agent has no more tool calls
• mode: pattern - Completes on pattern match

When not set, defaults to natural mode.

guardrails: Vec<GuardrailConfig>

Guardrails for validating agent outputs

Guardrails are checked after the agent signals completion. If any guardrail fails, the agent is asked to retry.

limits: Option<LimitsConfig>

Execution limits for cost control

Limits control resource consumption:

• max_turns: Maximum agentic loop iterations
• max_tokens: Total token budget (input + output)
• max_cost_usd: Cost ceiling per execution
• max_duration_secs: Wall-clock timeout

When a limit is reached, the action specified in on_limit_reached is taken (complete_partial, fail, or escalate).

Implementations

impl AgentParams

pub fn effective_max_turns(&self) -> u32

Get effective max turns (with default).

Returns the configured max_turns if set, otherwise returns the default value of 10.

pub fn effective_token_budget(&self) -> u32

Get effective token budget (with default).

Returns the configured token_budget if set, otherwise returns u32::MAX (effectively unlimited).

pub fn effective_thinking_budget(&self) -> u64

Get effective thinking budget (with default).

Returns the configured thinking_budget if set, otherwise returns the default value of 4096 tokens.

pub fn effective_depth_limit(&self) -> u32

Get effective depth limit for nested agent spawning (with default).

Returns the configured depth_limit if set, otherwise returns the default value of 3.

pub fn effective_max_tokens(&self) -> Option<u32>

Get effective max tokens for LLM calls.

When extended_thinking is enabled, Claude requires max_tokens > thinking_budget. If max_tokens is not set but extended thinking is enabled, this returns thinking_budget + 8192 to ensure valid configuration.

Returns None if neither max_tokens is set nor extended_thinking is enabled.

pub fn effective_tool_choice(&self) -> ToolChoice

Get effective tool choice behavior.

Returns the configured tool_choice if set, otherwise returns ToolChoice::Auto (LLM decides when to use tools).

pub fn has_explicit_tool_choice(&self) -> bool

Check if tool_choice was explicitly set by the user.

Returns true only if the user explicitly specified tool_choice in YAML. Used to avoid redundant .tool_choice(Auto) calls when the default is sufficient.

Why This Matters

Some providers handle tool_choice differently:

• Perplexity: Logs warning, ignores tool_choice
• Cohere: Rejects Auto explicitly (rig-core skips if Auto)
• Claude/OpenAI: Full support

By only setting tool_choice when explicit, we avoid:

1. Unnecessary API calls with default values
2. Provider-specific edge cases with Auto

pub fn effective_temperature(&self) -> Option<f32>

Get effective temperature.

Returns the configured temperature if set, otherwise returns None to use the provider’s default.

pub fn effective_completion(&self) -> Option<CompletionConfig>

Get effective completion configuration.

Returns the completion config if set, otherwise None (natural mode).

pub fn completion_system_instruction(&self) -> String

Generate system instruction for completion.

Returns the auto-generated instruction to append to the system prompt, or empty string if no special completion instruction is needed.

pub fn validate(&self) -> Result<(), NikaError>

Validate agent parameters.

Errors

Returns an error string if:

• prompt is empty
• max_turns is 0 or exceeds 100
• token_budget is 0

pub fn effective_limits(&self) -> LimitsConfig

Get effective limits configuration.

Returns the limits config if set, or a default (no limits) otherwise.

pub fn has_limits(&self) -> bool

Check if any limits are configured.

Trait Implementations

impl Clone for AgentParams

fn clone(&self) -> AgentParams

Returns a duplicate of the value.

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

Performs copy-assignment from source.

impl Debug for AgentParams

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

Formats the value using the given formatter.

impl Default for AgentParams

fn default() -> AgentParams

Returns the “default value” for a type.

impl<'de> Deserialize<'de> for AgentParams

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

where __D: Deserializer<'de>,

Deserialize this value from the given Serde deserializer.