CasCap.Common.AI 4.15.0

CasCap.Common.AI

AI agent framework infrastructure — agent creation, session management, MCP tool/prompt resolution, chat history compaction, and slash-command handling.

Installation

dotnet add package CasCap.Common.AI

Purpose

Provides the shared infrastructure for building multi-agent AI systems with support for multiple providers (Azure OpenAI, OpenAI, Ollama), automatic MCP tool discovery from [McpServerTool]-decorated service types, sub-agent delegation (fan-out pattern), persistent session state, and context-window compaction for edge GPU devices.

This library contains no domain-specific MCP query services — those live in downstream consumer projects. It provides the framework that consumer projects use to wire agents, tools, sessions, and prompts together.

Target frameworks: net10.0

Services

Abstractions

Extensions

Configuration

Models

Enums

Service Architecture

Agent framework infrastructure showing how AgentExtensions creates agents and resolves tools from multiple source types:

graph TD
    classDef core fill:#dbeafe,stroke:#3b82f6,color:#1e3a8a
    classDef service fill:#d1fae5,stroke:#10b981,color:#064e3b
    classDef config fill:#fef3c7,stroke:#f59e0b,color:#78350f
    classDef store fill:#e0f2fe,stroke:#0284c7,color:#0c4a6e

    AE["AgentExtensions"]:::core

    subgraph AgentCreation["Agent Creation"]
        CREATE["CreateAgent()<br/>(IChatClient + AIAgent)"]:::core
        RUN["RunAnalysisAsync()<br/>(AgentRunResult)"]:::core
    end

    subgraph ToolResolution["Tool Resolution"]
        SVC_TOOLS["CreateToolsFromServiceProvider&lt;T&gt;()<br/>(discovers [McpServerTool] methods)"]:::core
        AGENT_TOOL["CreateAgentTool()<br/>(wraps peer agent as AITool)"]:::core
        HTTP_TOOLS["GetHttpTools()<br/>(remote MCP endpoint)"]:::core
        FILTER["FilterTools()<br/>(include/exclude)"]:::core
    end

    subgraph Providers["Provider Support"]
        OLLAMA["Ollama"]:::config
        AZURE["Azure OpenAI"]:::config
        OPENAI["OpenAI"]:::config
    end

    subgraph SessionMgmt["Session Management"]
        CMD["AgentCommandHandler<br/>(slash-commands)"]:::service
        MEM_STORE["InMemorySessionStore"]:::store
        DIST_STORE["DistributedCacheSessionStore<br/>(Redis)"]:::store
    end

    subgraph Compaction["Chat History Compaction"]
        REDUCER["ToolOutputStrippingChatReducer<br/>(IChatReducer)"]:::service
    end

    AE --> AgentCreation
    AE --> ToolResolution
    CREATE --> Providers
    CREATE -.configures.-> REDUCER
    CMD --> MEM_STORE
    CMD --> DIST_STORE

Agent Instruction Resolution

AgentExtensions.ResolveInstructions resolves the InstructionsSource property on each AgentConfig using a two-step fallback:

1. Embedded resource — looks for a matching manifest resource name in the supplied assembly.
2. File system path — if the value is an absolute path to an existing file, reads it from disk.

If neither source is found an exception is thrown. The fallback Instructions string property can still be used for simple inline text.

Chat History Compaction

Long conversations accumulate large context windows — especially from verbose tool call/result JSON payloads. Automatic compaction is configured per-agent via AgentConfig.MaxMessages.

When MaxMessages is set to a positive value, AgentExtensions.CreateAgent configures the agent's InMemoryChatHistoryProvider with a ToolOutputStrippingChatReducer that:

1. Preserves the first system message (agent instructions are never lost).
2. Strips all FunctionCallContent and FunctionResultContent from non-system messages (the primary source of context bloat), dropping any message left with no remaining content.
3. Keeps a sliding window of the most recent MaxMessages non-system exchanges.

Tool content is removed from every message rather than only from messages consisting solely of tool content. An assistant message mixing narration text with a FunctionCallContent would otherwise be retained while its matching FunctionResultContent was dropped, leaving an orphaned tool call — OpenAI and Azure OpenAI reject such a request with HTTP 400.

The reducer runs automatically before each agent invocation. Set MaxMessages to 0 or null to disable automatic compaction.

Run Scope

Host callbacks and per-run state are carried by an AgentRunScope passed to RunAnalysisAsync, replacing the ambient Set*/Clear* callback pairs that callers previously had to balance in a finally block:

var scope = new AgentRunScope
{
    OnDelegation = (agentKey, depth, provider, ct) => NotifyAsync(agentKey, depth, ct),
    OnCompletion = (agentKey, depth, result, ct) => RecordAsync(agentKey, result, ct),
    OnCompaction = stats => Debug($"{stats.InputCount} → {stats.OutputCount}"),
};

var result = await agent.RunAnalysisAsync(provider, agentConfig, message, chatOptions, scope: scope);

ForSubAgent() creates a child scope with an incremented Depth that shares the parent's callbacks and attachment collection, so an image produced several delegations deep still surfaces on the top-level AgentRunResult.

CompactionStats carries InputCount, OutputCount, ToolDropped, WindowTrimmed and Target.

Session Isolation

Each agent uses its own AgentSession keyed by AgentConfig.Name. Sub-agents invoked via the fan-out pattern (ToolSource.Agent) create a fresh stateless session per invocation, ensuring no cross-agent context leakage.

Session Persistence

Dependencies

NuGet Packages

Project References

License

This project is released under The Unlicense. See the LICENSE file for details.