C++ Event-Sourced Agent Framework

An AI agent framework built on event sourcing principles with OpenAI API integration, MCP tool support, and multi-agent system.

Features

• Event Sourcing - All state changes captured as immutable events with complete audit trail
• Multi-Agent System - Load specialized AI personas from files, databases, or APIs with runtime switching
• Streaming Support - Real-time OpenAI streaming responses with granular event emission
• Tool Integration - MCP (Model Context Protocol) integration for external tool execution
• Elicitation - MCP servers can request structured user input during tool execution with validation and retry
• LLM Sampling - MCP servers can request LLM generations from the client, enabling agentic tool behaviors
• Time-Travel Debugging - Replay events to any point in conversation history
• Multiple Projections - Same events projected differently for conversation state, tools, and agents
• Pluggable Architecture - Interface-based design supports multiple LLM providers and agent sources

Quick Start

Prerequisites

# Ubuntu/Debian
sudo apt-get install -y libcurl4-openssl-dev nlohmann-json3-dev cmake build-essential

# macOS
brew install curl nlohmann-json cmake

Build

# Clone the repository
git clone https://github.com/MKAbdElrahman/cpp-agent.git
cd cpp-agent

# Build
make build

# Run
export OPENAI_API_KEY="your-key-here"
make chat

Using Agents

The framework supports specialized AI agents with custom system prompts and LLM preferences.

List Available Agents

# Show all agents
./samples/cli/build/chat --list-agents

Start with Specific Agent

# Start chat with C programming expert
./samples/cli/build/chat --agent c-pro

# Start with data engineering expert
./samples/cli/build/chat --agent data-engineer

Interactive Commands

During a chat session:

/agents              # List all available agents
/use c-pro           # Switch to C programming expert
/agent-info          # Show current agent details
/tools               # List available MCP tools
/history             # Show conversation state
/events              # Show full event log
/help                # Show all commands

Agent Definition Format

Agents are defined in YAML frontmatter markdown files:

---
name: agent-name
description: Agent description
provider: openai
model: gpt-4o
---

System prompt content here...

Agents can be loaded from:

• Local files (LocalFileAgentRegistry)
• Databases (implement IAgentRegistry)
• APIs (implement IAgentRegistry)
• Any custom source

License

MIT

Author

Mohamed Kamal Abdelrahman (@MKAbdElrahman)