👁 Image
CasCap.Common.AI 4.12.1

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

 subgraph Polling["Poll Tracking"]
 POLL["InMemoryPollTracker"]:::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 messages consisting solely of FunctionCallContent or FunctionResultContent (the primary source of context bloat).
3. Keeps a sliding window of the most recent MaxMessages non-system exchanges.

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

Compaction Callback

AgentExtensions exposes an ambient AsyncLocal compaction callback so host services can observe when compaction occurs:

AgentExtensions.SetCompactionCallback((inputCount, outputCount, toolDropped, windowTrimmed, target) =>
{
 // e.g. send a debug notification
});

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 . See the file for details.