Agents

Agents

Agents are the core of OpenCaddis. Each agent is a conversation thread with its own personality (system prompt), capabilities (plugins), and reasoning strategy (agent type). You define agents in opencaddis.json.

Assistant Agent

The Assistant agent uses a straightforward request-response pattern:

1. User sends a message
2. Message is sent to the LLM with the system prompt and configured tools
3. LLM responds (optionally calling tools)
4. Response is returned to the chat UI

Best for: General chat, simple tool use, quick questions, straightforward tasks where you don't need multi-step reasoning.

{
  "Handle": "Helper",
  "AgentType": "assistant",
  "Models": ["default"],
  "SystemPrompt": "You are a helpful assistant with access to the web and file system.",
  "Plugins": ["WebBrowser", "FileSystem", "Memory"]
}

Workflow Agent

The Workflow agent is a multi-agent orchestrator. Instead of doing everything itself, it plans work, delegates tasks to other agents, and verifies the results — coordinating multiple specialist agents to accomplish complex goals.

How It Works

The Workflow agent follows a structured pipeline:

1. Planning — The Workflow agent sends your request to the LLM, which generates a structured plan with tasks, assigned agents, dependencies, and acceptance criteria
2. Approval — The plan is presented to you for review. Say "go" to approve, "cancel" to abort, or provide feedback to adjust
3. Execution — Tasks are executed sequentially, respecting dependencies. Each task is delegated to the assigned agent, which uses its own plugins and tools to complete it
4. Acceptance — After each task completes, the Workflow agent evaluates the result against the task's acceptance criteria. Failed tasks may be retried with improved instructions or trigger a replan
5. Completion — Once all tasks are done, the Workflow agent summarizes what was accomplished

Managed Agents

The Workflow agent doesn't do work directly — it delegates to other agents you've configured. Use the ManagedAgents arg to specify which agents it can assign tasks to:

{
  "Handle": "Orchestrator",
  "AgentType": "workflow",
  "Models": ["default"],
  "SystemPrompt": "You are a project coordinator. Break complex requests into tasks and delegate them to the appropriate specialist agents.",
  "Args": {
    "ManagedAgents": "Researcher,Developer,Writer"
  }
}

User Commands

During different phases of the workflow, you can interact with the agent using these commands:

Task Lifecycle

Failure Handling

When a task fails acceptance criteria, the Workflow agent decides how to handle it:

• Retry — Re-run the task with improved instructions (up to MaxTaskAttempts)
• Blocked — Mark the task as blocked and continue with other tasks
• Replan — Generate a new plan that accounts for the failure
• Stall — If no progress can be made, stop and ask the user for guidance

Configuration

Best for: Multi-step projects, coordinating multiple specialist agents, research workflows, any task that benefits from planning and delegation.

{
  "Handle": "Project Lead",
  "AgentType": "workflow",
  "Models": ["default"],
  "SystemPrompt": "You are a project coordinator. Break complex requests into clear tasks, assign them to the right agents, and verify results meet quality standards.",
  "Args": {
    "ManagedAgents": "Helper,Researcher,Writer",
    "MaxTaskAttempts": 3
  }
}

Delegate Agent

The Delegate agent is an intelligent message router. Instead of doing work itself, it analyzes each user request, selects the most appropriate agent from a managed set, and delegates the work — then synthesizes the response back to you. It's a single-turn orchestrator: one request in, one answer out, routed to the right specialist automatically.

How It Works

The Delegate agent follows a four-step cycle for each request:

1. Select Agent — The Delegate agent sends your message to the LLM along with a catalog of available agents. The LLM picks the best-suited agent and explains its reasoning
2. Formulate — The LLM rewrites your request into an optimized delegation message tailored for the selected agent's capabilities
3. Delegate — The message is sent to the selected agent, which uses its own plugins and tools to complete the work. A configurable timeout prevents hanging
4. Analyze & Respond — The delegated agent's response is analyzed and synthesized into a clear, user-friendly answer

Best for: Providing a single natural-language entry point to a set of specialist agents. Users don't need to know which agent to talk to — the Delegate figures it out.

Managed Agents

Like the Workflow agent, the Delegate agent delegates to other agents you've configured. Use the ManagedAgents arg to specify which agents it can route to:

{
  "Handle": "Router",
  "AgentType": "delegate",
  "Models": ["default"],
  "Description": "Intelligent message router that selects the best agent for each request.",
  "Args": {
    "ManagedAgents": "Web,Files,Secretary"
  }
}

Real-time Progress

While processing, the Delegate agent sends thinking notifications so you can see what's happening:

• "Selecting the best agent..."
• "Formulating request..."
• "Delegating to Web..."
• "Analyzing response..."

Delegate vs. Workflow

Both are orchestration agents, but scoped differently:

Configuration

{
  "Handle": "Front Desk",
  "AgentType": "delegate",
  "Models": ["default"],
  "Description": "Intelligent message router that analyzes requests, selects the best agent, and synthesizes responses.",
  "Args": {
    "ManagedAgents": "Helper,Researcher,Secretary",
    "DelegationTimeoutSeconds": 180
  },
  "Tools": ["GetDateTime"]
}

Example Conversation

Event Log Agent

The Event Log agent is a live application diagnostics tool. It receives a real-time stream of OpenCaddis application logs and lets you query them through natural conversation — search by text, filter by severity or category, drill into time ranges, and get summary statistics.

How It Works

Unlike the other agent types, the Event Log agent has a passive data pipeline feeding it:

1. A custom ILoggerProvider captures all application log entries at Information level and above
2. Log entries are streamed through a bounded channel to the Event Log agent as events
3. The agent stores them in an in-memory ring buffer (last 1,000 entries, O(1) writes, no allocations)
4. When you ask a question, the LLM calls the agent's built-in tools to search and analyze the buffer

Built-in Tools

Configuration

What Gets Captured

• Included: All log entries at Information, Warning, Error, and Critical levels from OpenCaddis application code
• Excluded: Trace and Debug levels, and internal framework logs from FabrCore and Orleans (suppressed to avoid noise and recursion)
• Buffer: Rolling window of the last 1,000 entries — older entries are overwritten

Best for: Debugging, monitoring, understanding application behavior, triaging errors — without leaving the chat UI or opening a log viewer.

{
  "Handle": "Log Analyst",
  "AgentType": "eventlog",
  "Models": ["default"]
}

Example Conversation

Chain of Thought Agent

The ChainOfThoughtAgent is a reasoning agent that uses an adaptive confidence-threshold loop to answer complex questions. Unlike the standard AssistantAgent which makes a single LLM call, the CoT agent breaks problems into steps, executes them, synthesizes results, and iterates until it reaches a confidence threshold — producing deeper, more thorough answers.

Agent Type: chainofthought

How It Works

Phases

Confidence Threshold Decay

The agent uses a linearly decaying confidence threshold. This ensures it tries hard early but gracefully accepts "good enough" answers rather than looping forever.

Configuration

{
  "Name": "Cot",
  "AgentType": "chainofthought",
  "SystemPrompt": "You are a thoughtful reasoning assistant.",
  "Args": {
    "ModelConfig": "default",
    "MaxLoops": "8",
    "MaxSteps": "5",
    "InitialConfidenceThreshold": "0.75",
    "MinConfidenceThreshold": "0.40",
    "NetworkTimeoutSeconds": "180"
  },
  "Tools": ["DateTime"],
  "Plugins": ["WebBrowser", "FileSystem"]
}

When to Use

Performance Characteristics

The CoT agent makes multiple LLM calls per user message. Typical performance on Azure OpenAI gpt-5-nano:

Structured Output & LLM Optimization

All internal LLM calls use structured JSON output with the following optimizations:

• ReasoningEffort = None — Disables internal chain-of-thought reasoning in the LLM, reducing latency by ~30–40% on reasoning-capable models (GPT-5, o-series).
• ReasoningOutput = None — Suppresses reasoning traces from the response body, saving output tokens.
• AllowMultipleToolCalls = false — Required for compatibility with structured JSON output on Azure OpenAI, which does not support parallel tool calls with JSON schemas.

Data Models

The agent uses structured types for LLM communication:

Best for: Multi-faceted analysis, comparisons, research questions, anything requiring synthesis of multiple perspectives, and questions where you want the agent to self-evaluate its answer quality.

{
  "Handle": "Deep Thinker",
  "AgentType": "chainofthought",
  "Models": ["default"],
  "SystemPrompt": "You are a thoughtful reasoning assistant. Break complex problems into steps and synthesize thorough answers.",
  "Args": {
    "MaxLoops": "8",
    "MaxSteps": "5",
    "InitialConfidenceThreshold": "0.75",
    "MinConfidenceThreshold": "0.40"
  },
  "Plugins": ["WebBrowser", "Memory"]
}

Chat History Compaction

Long conversations accumulate message history that can fill the model's context window, increasing token costs and eventually hitting size limits. Compaction solves this by automatically summarizing older messages when the conversation grows too large — keeping agents effective in long-running sessions without losing important context.

How It Works

1. Estimate — Before each message, the agent estimates the total token count of all stored messages
2. Threshold — If the estimate exceeds the configured threshold (default 75% of the context window), compaction triggers
3. Summarize — Older messages are sent to the LLM with instructions to produce a concise summary that preserves key decisions, facts, names, numbers, outstanding tasks, and overall context
4. Replace — The older messages are atomically replaced with a single [Compacted History] system message containing the summary. The most recent messages (default 20) are always kept intact

Configuration

Compaction requires the ContextWindowTokens property set on your model configuration in fabr.json. Per-agent behavior can be tuned via Args:

{
  "Handle": "Long Chat",
  "AgentType": "assistant",
  "Models": ["default"],
  "SystemPrompt": "You are a helpful assistant.",
  "Plugins": ["WebBrowser", "Memory"],
  "Args": {
    "CompactionEnabled": "true",
    "CompactionKeepLastN": "30",
    "CompactionThreshold": "0.80"
  }
}

What Gets Preserved

The LLM summarization prompt is designed to preserve:

• Key decisions and conclusions
• Important facts, names, and numbers
• Outstanding tasks or open questions
• The overall topic and context of the conversation

Safety

• Tool message integrity — Compaction never splits a tool result from its parent assistant message, preventing API errors from orphaned tool messages
• Atomic replacement — The entire message history is replaced in a single operation, preventing race conditions
• Graceful failure — If compaction fails for any reason, the error is logged and the agent continues normally with the original history

Creating Agents

Here's a complete example with all five agent types:

{
  "Agents": [
    {
      "Handle": "Quick Chat",
      "AgentType": "assistant",
      "Models": ["default"],
      "SystemPrompt": "You are a friendly, concise assistant.",
      "Plugins": ["WebBrowser", "Memory"]
    },
    {
      "Handle": "Dev Assistant",
      "AgentType": "assistant",
      "Models": ["default"],
      "SystemPrompt": "You are a senior software developer. Write clean, well-tested code.",
      "Plugins": ["FileSystem", "PowerShell", "Docker", "Memory", "TaskManager"],
      "Args": {
        "FileSystem:RootPath": "C:\\Projects",
        "PowerShell:TimeoutSeconds": 60
      }
    },
    {
      "Handle": "Front Desk",
      "AgentType": "delegate",
      "Models": ["default"],
      "Description": "Routes requests to the best available agent.",
      "Args": {
        "ManagedAgents": "Quick Chat,Dev Assistant"
      }
    },
    {
      "Handle": "Project Lead",
      "AgentType": "workflow",
      "Models": ["default"],
      "SystemPrompt": "You are a project coordinator. Plan and delegate work to the right agents.",
      "Args": {
        "ManagedAgents": "Quick Chat,Dev Assistant"
      }
    },
    {
      "Handle": "Log Analyst",
      "AgentType": "eventlog",
      "Models": ["default"]
    },
    {
      "Handle": "Deep Thinker",
      "AgentType": "chainofthought",
      "Models": ["default"],
      "SystemPrompt": "You are a thoughtful reasoning assistant.",
      "Plugins": ["WebBrowser", "Memory"],
      "Args": {
        "MaxLoops": "8",
        "InitialConfidenceThreshold": "0.75"
      }
    }
  ]
}