Existo.Persistence.EntityFrameworkCore 0.1.0-alpha.0.15

Existo

From Latin existo — "I exist." Derived from Descartes' cogito ergo sum — "I think, therefore I am." An agent framework that reasons, acts, and exists in the world.

Existo is a .NET 10 framework for building AI agents and multi-agent systems. It provides a composable, streaming-first runtime with built-in memory, orchestration, tool integration, MCP and A2A protocol support, and OpenTelemetry observability — without locking you into any single LLM provider.

Origin & purpose

Existo was born from a desire to learn — to understand deeply how LLM-based agents work by building one from the ground up rather than wrapping an existing framework.

Every concept here — the ReAct loop, memory tiers, tool dispatch, streaming events, orchestration graphs — was implemented from scratch as a learning exercise. That makes Existo a learning tool as much as a side project: if you want to understand how AI agents are wired together at the .NET level, this codebase is designed to be read, forked, and experimented with.

This project was developed with the assistance of Claude — but it was not vibe coded. Every decision was deliberate: each pattern was researched, discussed, and chosen with the explicit goal of understanding the concepts behind it. Claude was used as a thinking partner and implementation aid, not as a shortcut. If anything, the process was slower and more intentional than writing the code alone would have been, because the point was always to learn, not just to ship.

Whether you are exploring agent patterns for the first time or building something for yourself, Existo is for you.

Key capabilities

• ReAct agent loop — LLM reasons, calls tools, observes results, repeats until done
• Agent composition — Sequential, Parallel, and Loop wrappers for multi-step pipelines
• DAG orchestration — Route between agents with static or conditional edges (AgentGraph)
• Group chat — Round-robin or custom-strategy multi-agent conversations (GroupChatOrchestrator)
• Three-tier memory — Working memory, episodic summaries, and persistent semantic memory
• Auto-compaction — LLM-summarised session history when context windows grow large
• Self-learning skills — Agents write, store, and reuse TypeScript and Python tools at runtime
• MCP integration — Connect any MCP server over HTTP or stdio; tools appear automatically
• A2A integration — Call remote A2A agents as tools via their agent card
• Five LLM providers — Azure OpenAI, OpenAI, Anthropic, Google Gemini, Ollama
• Two persistence backends — Entity Framework Core (PostgreSQL / SQL Server) and Azure Cosmos DB
• OpenTelemetry — Distributed tracing and metrics across the entire runtime
• Streaming throughout — IAsyncEnumerable<AgentEvent> from agent to runner to your code

Projects

Existo — Core runtime

The foundation of the framework. Contains everything needed to build and run an agent:

• LlmAgent — a ReAct loop that calls the LLM, dispatches tool calls, and streams AgentEvent results
• SequentialAgent / ParallelAgent / LoopAgent — composable wrappers for multi-step pipelines
• AgentRunner — ties an agent to a session and exposes a simple RunAsync(input, session) entry point
• AgentBuilder — fluent builder for configuring agents with tools, system prompts, and options
• Memory — IMemoryStore (key/value facts), IEpisodicMemoryStore (past-session summaries), and working memory inside the session
• Sessions — ISession and ISessionService decouple conversation state from agent instances; InMemorySessionService is included out of the box
• Tools — [ToolFunction] attribute, ToolRegistry, parameter schema generation, per-tool timeouts, and approval guards
• LLM abstraction — ILlmProvider and IEmbeddingProvider interfaces that all provider packages implement; agent code never references any SDK directly

Existo.Orchestration — Multi-agent coordination

Builds on the core to coordinate multiple agents:

• AgentGraph — a directed acyclic graph (DAG) where each node is an agent and edges carry static or condition-based routing; supports fan-out and merge patterns
• GroupChatOrchestrator — a shared conversation loop where multiple agents take turns, controlled by a pluggable IGroupChatStrategy (round-robin included) and a termination strategy (max turns, keyword match, or composite)

Existo.Skills — Self-learning skill system

Agents can learn new capabilities at runtime without redeployment:

• When the LLM decides it needs a tool that does not yet exist, it calls create_tool to write the implementation in TypeScript or Python
• The skill is saved to a ISkillStore (file system by default) and immediately loaded into the session via ISessionToolOverlay
• On subsequent sessions the skill is automatically restored, so the agent grows its own toolbox over time
• TypeScript skills are executed with Deno (deno run --no-prompt) for sandboxed, dependency-free execution
• Python skills are executed with uv (uv run --no-project), supporting PEP 723 inline script dependencies
• SkillExecutorRegistry dispatches by language; adding a new runtime is a single ISkillExecutor implementation

LLM providers

Each provider package implements ILlmProvider (streaming chat completions) and, where supported, IEmbeddingProvider (vector embeddings). Register them with a single AddXxx() extension on ExistoBuilder.

Persistence

In-memory stores ship with the core package. These packages add durable backends.

Existo.Persistence.EntityFrameworkCore EF Core implementations of ISessionService, IMemoryStore, and IEpisodicMemoryStore. Supports any EF Core-compatible database; tested with PostgreSQL and SQL Server. Includes migrations and a ready-to-use ExistoDbContext.

Existo.Persistence.EntityFrameworkCore.Pgvector Extends the EF Core store with semantic (vector) search powered by pgvector. Adds GetRelevantMemoriesAsync and GetRelevantEpisodesAsync using cosine similarity on stored embeddings. Requires the pgvector PostgreSQL extension.

Existo.Persistence.CosmosDB Azure Cosmos DB implementations of the same session, memory, and episodic stores. Uses the Cosmos DB SDK directly with a custom System.Text.Json serializer.

Protocols

Existo.MCP Connects to any Model Context Protocol server. Supports HTTP (HttpMcpConnection) and stdio (StdioMcpConnection). Tools exposed by the MCP server appear automatically in the agent's tool registry via McpToolAdapter.

Existo.A2A Implements the Agent-to-Agent (A2A) protocol client side. A remote A2A agent is resolved via its agent card and called as a regular tool inside the local agent's ReAct loop.

Existo.A2A.AspNetCore Exposes a local agent as an A2A server. Registers the required JSON-RPC endpoints via IEndpointRouteBuilder with a single MapA2AAgent() call.

Existo.OpenTelemetry — Observability

Plugs into the .NET OpenTelemetry SDK to instrument the entire runtime with zero agent-code changes:

• Traces — one span per agent turn, child spans for each tool call; propagated across sequential and parallel agent compositions
• Metrics — token usage (prompt / completion), tool call counts, turn duration histograms, error counters
• Register with AddExistoInstrumentation() on your TracerProviderBuilder / MeterProviderBuilder

Quick start

All Existo configuration flows through AddExisto, using its optional builder callback to keep every provider, agent, and runner registration in one scoped block:

using Existo;
using Existo.LLM.AzureOpenAI;
using Existo.Runner;
using Existo.Sessions;
using Microsoft.Extensions.DependencyInjection;
using Microsoft.Extensions.Hosting;

var host = Host.CreateDefaultBuilder(args)
    .ConfigureServices((ctx, services) =>
    {
        services.AddExisto(b => b
            .AddAzureOpenAIProvider(opts =>
            {
                opts.Endpoint       = "https://<resource>.openai.azure.com/";
                opts.DeploymentName = "gpt-4o";
                opts.ApiKey         = "<key>";
            })
            .AddAgent("assistant", (sp, ab) => ab
                .WithSystemPrompt("You are a helpful assistant.")
                .AddTool(MyTools.GetCurrentTimeAsync))
            .AddAgentRunner("runner", "assistant"));

        // Non-Existo registrations go directly on services as usual
        services.AddSingleton<IMyService, MyService>();
    })
    .Build();

var runner  = host.Services.GetRequiredKeyedService<IAgentRunner>("runner");
var session = await host.Services.GetRequiredService<ISessionService>()
                        .CreateSessionAsync("user-1");

await foreach (var evt in runner.RunAsync("What time is it?", session))
{
    if (evt.Type == AgentEventType.AgentMessage && evt.IsFinal)
        Console.WriteLine(evt.Messages[0].Content);
}

AddExisto returns the ExistoBuilder for cases where you need to spread registrations across multiple statements (e.g. conditional provider selection):

var existo = services.AddExisto();

if (useAzure) existo.AddAzureOpenAIProvider(opts => { ... });
else          existo.AddAnthropicProvider(opts => { ... });

existo.AddAgent("assistant", (sp, ab) => ab
        .WithSystemPrompt("You are a helpful assistant."))
      .AddAgentRunner("runner", "assistant");

Documentation

Samples

Build and test

dotnet build
dotnet test
dotnet run --project samples/Existo.Samples/Existo.Samples.csproj

License

MIT — see LICENSE.