AI Agents Course - Padrões de Agentes em C#
mrviduus/AiAgents
Aprenda a construir agentes de IA em C# com padrões prontos para produção
Ver no GitHubRepositório educacional com 6 projetos práticos em C# .NET 10 demonstrando padrões de agentes de IA: loops ReAct, RAG com recuperação fundamentada, implementação MCP server e sistemas de memória. Inclui exemplos de integração com OpenAI, Claude e Gemini, totalmente containerizado com Docker.
Instalação
npx convez-ai mrviduus/AiAgents1 comando no terminal: detecta o formato do repositório (marketplace ou plugin avulso) e instala via Claude Code. Requer Node 18+ e o Claude Code instalado.
Métricas
Casos de uso
- Construir agentes autônomos que orquestram ferramentas e APIs
- Implementar sistemas RAG com recuperação de conhecimento fundamentada
- Desenvolver servidores MCP compatíveis com Claude para integração
- Gerenciar memória e contexto em aplicações com LLMs
- Prototipar chatbots e assistentes de negócios em .NET
Veredito

Recurso robusto para desenvolvedores .NET aprenderem padrões de agentes de IA com código executável e bem documentado. A cobertura de múltiplos provedores (OpenAI, Claude, Gemini) e o suporte a MCP server o tornam valioso para automação empresarial em C#.
README
A tradução para o português deste README ainda está na fila.
AI Agents Course - Learn by Building
Learn how to build AI agents in C# through practical examples. This repository contains 6 working projects that demonstrate different AI agent patterns, from simple chatbots to advanced MCP servers.
📚 Table of Contents
Core Concepts
- GPT Fundamentals - Understanding GPT models and their evolution
- Stateless AI - Why AI models have no memory and how to manage state
Architecture Patterns
- Agent Loops - The core pattern for autonomous AI agents
- ReAct Pattern - Deep dive into Thought → Action → Observation
- RAG Pattern - Retrieval-Augmented Generation and RAG Ultrathink for grounded responses
- Completion vs Reasoning Models - Choosing the right model for your use case
Implementation Details
- Memory Systems - Episodic and semantic memory for AI agents
- Summarization Strategies - Managing context and token limits
🚀 Getting Started in 5 Minutes
What You Need
- .NET 10.0 - Download here
- Code Editor - Visual Studio 2022 or VS Code
- API Keys - Get at least one:
First-Time Setup
Option 1: Docker (Easiest!)
# 1. Clone this repository
git clone https://github.com/mrviduus/AiAgents.git
cd AiAgents
# 2. Copy and edit .env file
cp .env.example .env
# Edit .env with your API keys
# 3. Run with Docker Compose
docker-compose up # All services
# OR specific services:
docker-compose -f docker-compose.invoice.yml up # Invoice services only
docker-compose -f docker-compose.mcp.yml up # MCP services only
Option 2: Manual Setup
- Clone this repository
- Create a
.envfile in the project folder you want to run:
OPENAI_API_KEY=your-key-here
CLAUDE_API_KEY=your-key-here
GEMINI_API_KEY=your-key-here
📦 The 6 Projects - From Simple to Advanced
1️⃣ BasicOpenAiExamples - Start Here!
Your first AI chatbot in 5 lines of code.
cd BasicOpenAiExamples
echo "OPENAI_API_KEY=your-key" > .env
dotnet run
# Chat with AI directly!
2️⃣ ConsoleAgent - AI with Superpowers
An AI agent that can check weather, manage wardrobe, and send emails.
cd ConsoleAgent
# Pick your AI provider:
dotnet run --provider openai --model gpt-4.1-mini
dotnet run --provider claude --model claude-3-5-haiku-latest
dotnet run --provider gemini --model gemini-2.0-flash-lite
Try: "What should I wear today in New York?"
3️⃣ InvoiceAgentApi - Business AI Assistant
AI that manages invoices and reads documentation.
cd InvoiceAgentApi
dotnet run --provider openai --model gpt-5-mini
# API runs at http://localhost:5001
Pair with InvoiceApp for full experience.
4️⃣ InvoiceApp - Web Interface
Beautiful web UI for the Invoice AI.
cd InvoiceApp
dotnet run
# Open http://localhost:5000 in browser
5️⃣ McpServer - Connect AI to Everything
Advanced server using Anthropic's MCP protocol.
cd McpServer
dotnet run
# Server at http://localhost:5050
# Test it:
npx @modelcontextprotocol/inspector
6️⃣ RawJsonImplementation - Under the Hood
See how AI APIs work at the lowest level.
cd RawJsonImplementation
dotnet run
# Learn by reading the code!
💡 What You'll Learn
The Big Ideas (With Examples!)
🤖 AI Agents - AI that can use tools and take actions
- Example: ConsoleAgent checks weather and suggests clothes
🧠 Memory Systems - Give AI memory between conversations
- Example: Agent remembers your preferences
🔄 Agent Loops - Think → Act → Observe → Repeat
- Example: AI tries multiple approaches to solve problems
📚 RAG Pattern - AI that reads documents before answering
- Example: InvoiceAgentApi reads docs to answer questions
🔌 MCP Protocol - Connect AI to any service
- Example: McpServer exposes tools, prompts, and resources
📖 Documentation Structure
docs/
├── concepts/ # Fundamental AI concepts
│ ├── gpt-fundamentals.md
│ └── stateless-ai.md
├── architecture/ # Design patterns and architectures
│ ├── agent-loops.md
│ ├── react-pattern.md
│ ├── rag-pattern.md
│ └── completion-vs-reasoning-models.md
└── implementation/ # Practical implementation guides
├── memory-systems.md
└── summarization-strategies.md
💡 Best Practices
- Always manage context - AI models are stateless; you must provide context
- Implement proper error handling - Agent loops can fail; plan for recovery
- Monitor costs - Each API call has a cost; implement budgets
- Use appropriate models - Completion for speed, reasoning for accuracy
- Log everything - Essential for debugging agent behavior
🛠️ Technology Stack
- Language: C# (.NET 10.0)
- AI Models: OpenAI GPT, Azure OpenAI, Claude, Google Gemini
- Patterns: Agent Loops, ReAct, RAG, Memory Systems, MCP
- Tools: Dependency Injection, Async/Await, LINQ, Vector Databases
- Frameworks: Microsoft.Extensions.AI, Model Context Protocol (MCP)
📝 Code Examples
All code examples in this repository are written in C# and follow Microsoft's coding conventions. Each concept includes:
- Theoretical explanation
- Practical implementation
- Real-world use cases
- Best practices
🎯 Learning Objectives
After studying this repository, you will understand:
- How GPT and LLMs work under the hood
- Why AI is stateless and how to manage state
- How to build autonomous AI agents
- Different memory strategies for AI systems
- When to use completion vs reasoning models
- How to implement the ReAct pattern
- How to build RAG systems and use RAG Ultrathink for deep reasoning
- Effective summarization techniques
🔌 What is MCP?
Model Context Protocol (MCP) is Anthropic's way to connect AI to your tools and data.
Think of it like this:
- Without MCP: AI can only chat
- With MCP: AI can use your tools, read your docs, and take actions
MCP Gives AI Three Superpowers:
-
🔧 Tools - Functions AI can call
- Example: "List all invoices", "Mark invoice #123 as paid"
-
💬 Prompts - Ready-made templates
- Example: "Pay invoice for [customer name]"
-
📄 Resources - Documents AI can read
- Example: Your product documentation, FAQs
Try It Yourself:
# 1. Start the MCP server
cd McpServer
dotnet run
# 2. Test with the inspector (new terminal)
npx @modelcontextprotocol/inspector
# Opens a web UI to test your tools!
Connect to Claude.ai (Advanced):
Need HTTPS? Use this tunnel:
ssh -R 80:localhost:5050 nokey@localhost.run
# Gives you: https://abc123.localhost.run
Then add to Claude.ai → Settings → Connectors
🔗 Quick Links
Documentation
- Agent Loop Examples
- Memory System Implementation
- ReAct Pattern in C#
- RAG and RAG Ultrathink
- Model Selection Guide
Projects
🐳 Docker Support
Quick Start with Docker
All services are containerized and ready to run:
# Run everything (Invoice + MCP services)
docker-compose up
# Run specific service groups
docker-compose -f docker-compose.invoice.yml up # Invoice services
docker-compose -f docker-compose.mcp.yml up # MCP + Inspector
# Run with HTTPS tunnel for Claude.ai
docker-compose --profile tunnel up
Service URLs
When running with Docker:
- InvoiceApp: http://localhost:5000
- InvoiceAgentApi: http://localhost:5001
- McpServer: http://localhost:5050
- MCP Inspector: http://localhost:6274
Docker Commands
# Build images
docker-compose build
# Run in background
docker-compose up -d
# View logs
docker-compose logs -f [service-name]
# Stop services
docker-compose down
# Clean up everything
docker-compose down -v # Removes volumes too
Docker Environment Variables
Set in .env file (copy from .env.example):
AI_PROVIDER=openai # or claude, gemini
AI_MODEL=gpt-4.1-mini # your preferred model
❓ Troubleshooting
Common Issues & Solutions
"API key not found"
- Create
.envfile in the project folder (not root) - Format:
OPENAI_API_KEY=sk-...(no quotes)
"Model not found"
- OpenAI: Use
gpt-4.1-miniorgpt-3.5-turbo - Claude: Use
claude-3-5-haiku-latest - Gemini: Use
gemini-2.0-flash-lite
"Port already in use"
- InvoiceApp: Default port 5000
- InvoiceAgentApi: Default port 5001
- McpServer: Default port 5050
- Kill existing process or change port
"dotnet: command not found"
- Install .NET 10.0: https://dotnet.microsoft.com/download
MCP Inspector not working
- Install Node.js first: https://nodejs.org
- Run in separate terminal from MCP server
🤝 Contributing
This is an educational repository from our AI Agents course. Feel free to:
- Report issues
- Suggest improvements
- Share your implementations
- Ask questions
📄 License
This repository is for educational purposes. All code examples are provided as-is for learning.
This repository contains examples and exercises from our AI Agents course, demonstrating practical applications of AI agent architectures in C#.