Struct RigAgentLoop 

pub struct RigAgentLoop {
    pub media_staging: AgentMediaStaging,
    /* private fields */
}

Rig-based agentic execution loop

Uses rig-core’s AgentBuilder for multi-turn execution with MCP tools.

Chat History

The agent loop now supports conversation history for multi-turn interactions:

let mut agent = RigAgentLoop::new(...)?;

// First turn
let result = agent.run_claude().await?;

// Continue conversation with history
agent.add_to_history("What's the capital of France?", &result.final_output.to_string());
let result2 = agent.chat_continue("And what about Germany?").await?;

Fields

media_staging: AgentMediaStaging

Shared media staging for agent tool calls (H1 side-channel). Binary content blocks from MCP tools are collected here since rig’s ToolDyn::call() returns String only.

Implementations

impl RigAgentLoop

pub fn add_to_history(&mut self, user_prompt: &str, assistant_response: &str)

Add a user/assistant turn to the conversation history

Call this after each completed turn to maintain context for chat_continue().

pub fn push_message(&mut self, message: Message)

Add a single message to the history

pub fn clear_history(&mut self)

Clear all conversation history and reset turn count

pub fn history_len(&self) -> usize

Get the current history length (number of messages)

pub fn turn_count(&self) -> u32

Get the number of completed turns (user + assistant exchanges).

pub fn history(&self) -> &[Message]

Get a reference to the conversation history

pub fn with_history(self, history: Vec<Message>) -> Self

Create with pre-existing history

Useful for resuming conversations or injecting context.

pub async fn chat_continue( &mut self, prompt: &str, ) -> Result<RigAgentLoopResult, NikaError>

Continue a conversation using the accumulated history

Uses rig-core’s Chat trait for multi-turn conversations. The history is automatically updated with the user prompt and response.

Example

// First turn
let result1 = agent.run_claude().await?;
agent.add_to_history("Initial prompt", &extract_text(&result1));

// Continue conversation
let result2 = agent.chat_continue("Follow-up question").await?;
// History now contains both turns

impl RigAgentLoop

pub async fn run_mock(&self) -> Result<RigAgentLoopResult, NikaError>

Run the agent loop with a mock provider (for testing)

This method simulates agent execution without making real API calls.

pub async fn run_claude(&mut self) -> Result<RigAgentLoopResult, NikaError>

Run the agent loop with the real Claude provider

This method uses rig-core’s AgentBuilder for actual execution. Requires ANTHROPIC_API_KEY environment variable to be set.

Includes confidence retry loop and guardrail retry loop, matching the generic provider path behavior.

Note

This method takes &mut self because tools are consumed (moved to rig’s AgentBuilder). The agent loop is designed for single-use execution.

Extended Thinking

When extended_thinking: true is set in AgentParams, this method uses the streaming API to capture Claude’s reasoning process. The thinking is stored in AgentTurnMetadata.thinking for observability.

Token Tracking

• Without tools: Uses streaming API for accurate token tracking
• With tools: Falls back to agent.prompt() (tokens will be 0)
• With extended_thinking: Uses dedicated streaming path

pub async fn run_openai(&mut self) -> Result<RigAgentLoopResult, NikaError>

Run the agent loop with the OpenAI provider

This method uses rig-core’s OpenAI client for actual execution. Requires OPENAI_API_KEY environment variable to be set.

Includes confidence retry loop and guardrail retry loop, matching the generic provider path behavior.

Note

This method takes &mut self because tools are consumed (moved to rig’s AgentBuilder). The agent loop is designed for single-use execution.

pub async fn run_auto(&mut self) -> Result<RigAgentLoopResult, NikaError>

Run the agent loop with the best available provider

Provider selection order:

1. Check AgentParams.provider field
2. Check ANTHROPIC_API_KEY env var → use Claude
3. Check OPENAI_API_KEY env var → use OpenAI
4. Check MISTRAL_API_KEY env var → use Mistral
5. Check GROQ_API_KEY env var → use Groq
6. Check DEEPSEEK_API_KEY env var → use DeepSeek
7. Error if no provider available

Note

This is the recommended method for production use.

pub async fn run_mistral(&mut self) -> Result<RigAgentLoopResult, NikaError>

Run with Mistral provider (requires MISTRAL_API_KEY)

pub async fn run_groq(&mut self) -> Result<RigAgentLoopResult, NikaError>

Run with Groq provider (requires GROQ_API_KEY)

pub async fn run_deepseek(&mut self) -> Result<RigAgentLoopResult, NikaError>

Run with DeepSeek provider (requires DEEPSEEK_API_KEY)

pub async fn run_gemini(&mut self) -> Result<RigAgentLoopResult, NikaError>

Run with Gemini provider (requires GEMINI_API_KEY)

pub async fn run_xai(&mut self) -> Result<RigAgentLoopResult, NikaError>

Run with xAI provider (requires XAI_API_KEY)

impl RigAgentLoop

pub fn check_guardrails(&self, output: &str) -> GuardrailCheckResult

Run all configured guardrails against the output

Emits events for each guardrail result:

• GuardrailPassed: Guardrail check succeeded
• GuardrailFailed: Guardrail check failed
• GuardrailEscalation: Guardrail failed with on_failure: escalate

Returns GuardrailCheckResult indicating the appropriate action:

• AllPassed: All guardrails passed
• FailedRetry: Some failed with on_failure: retry (default)
• FailedEscalate: Some failed with on_failure: escalate
• FailedImmediate: Some failed with on_failure: fail

Priority: Immediate > Escalate > Retry

pub fn determine_status(&self, output: &str) -> RigAgentStatus

Determine agent status based on output content

Checks in order:

1. Explicit completion via nika:complete tool
   • With confidence: compare against threshold → HighConfidence/LowConfidence
   • Without confidence: ExplicitCompletion
2. Pattern completion (if completion.mode: pattern)
3. Natural completion — but only when mode is NOT explicit When completion.mode: explicit, natural end-of-turn without nika:complete returns LowConfidence(0.0) to trigger retry.

pub async fn run_claude_with_thinking( &mut self, ) -> Result<RigAgentLoopResult, NikaError>

Run the agent loop with extended thinking enabled (Claude only).

Uses rig-core’s streaming API to capture thinking blocks from Claude’s extended thinking feature. The thinking is accumulated and stored in the AgentTurnMetadata for observability.

Errors

• NIKA-113: Extended thinking failed
• NIKA-110: Agent execution error

impl RigAgentLoop

pub fn new( task_id: String, params: AgentParams, event_log: EventLog, mcp_clients: FxHashMap<String, Arc<McpClient>>, ) -> Result<Self, NikaError>

Create a new rig-based agent loop

Errors

• NIKA-113: Empty prompt
• NIKA-113: Invalid max_turns (0 or > 100)

pub fn with_stream_tx(self, tx: Sender<StreamChunk>) -> Self

Set streaming channel for real-time token display

When set, tokens will be sent to this channel as they arrive during streaming. This enables Claude Code-like real-time text display in the TUI.

pub fn with_skills( self, injector: Arc<SkillInjector>, skills_map: HashMap<String, String>, base_dir: PathBuf, ) -> Self

Configure skill injection for this agent

When set, skills defined in the workflow are loaded and prepended to the agent’s system prompt before LLM calls.

Arguments

• injector - Shared SkillInjector instance (with DashMap cache)
• skills_map - Mapping of skill names to file paths from workflow YAML
• base_dir - Base directory for resolving relative skill paths

Example

let agent = RigAgentLoop::new(task_id, params, log, mcp)?
    .with_skills(
        Arc::new(SkillInjector::new()),
        skills_map,
        PathBuf::from("/path/to/workflow"),
    );

pub fn with_structured_output(self, schema: Value) -> Self

Inject a DynamicSubmitTool for structured output enforcement.

When the task has an output policy with a JSON schema, this adds submit_result as an available tool. Unlike infer: (which forces tool_choice: Required), the agent can call submit_result when ready — it’s available but not forced.

Arguments

• schema - JSON Schema as serde_json::Value for the expected output

pub fn drain_media(&self) -> Vec<ContentBlock>

Drain collected media content blocks from all agent tool calls.

Returns all ContentBlocks that were staged during the agent loop. The DashMap is drained (emptied) after this call.

pub fn tool_count(&self) -> usize

Get the number of tools available

Trait Implementations

impl Debug for RigAgentLoop

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

Formats the value using the given formatter.