A .NET SDK for building AI agent workflows using Microsoft Agent Framework (MAF) and Azure AI Foundry. This SDK simplifies creating, orchestrating, and managing AI agents with built-in support for vector stores, document processing, and observability.
# Core SDK
dotnet add package AgentSdk
# PDF processing extensions (optional)
dotnet add package AgentSdk.Pdfvar builder = Host.CreateApplicationBuilder(args);
// Load configuration from agent.config.yaml and .env files
builder.UseAgentSdk();
// Register core services
builder.Services.AddAgentSdkServices();
// Optional: Add telemetry
builder.AddAgentSdkTelemetry();Create agent.config.yaml in your project root:
providers:
azure_foundry:
type: "azure_foundry"
endpoint: "${PROJECT_ENDPOINT}"
deployment_name: "${PROJECT_DEPLOYMENT_NAME}"
temperature: 0.7
top_p: 0.95
agents:
my_agent:
type: "custom"
enabled: true
auto_delete: true
auto_cleanup_resources: true
temperature: 0.3
top_p: 0.8
metadata:
description: "My AI agent"
tools:
- "file_search" # Enable document search
- "code_interpreter" # Enable code execution (optional)
provider: "azure_foundry"
system_prompt_template: |
You are a helpful assistant.
user_prompt_template: |
Process: {{input}}Create a .env file:
PROJECT_ENDPOINT=https://your-project.api.azureml.ms
PROJECT_DEPLOYMENT_NAME=gpt-4o| Feature | Description |
|---|---|
| Workflow Orchestration | Build sequential executor pipelines using MAF's Executor<TInput, TOutput> pattern |
| Agent Factory | Create and manage ephemeral Azure AI Foundry agents with keyed DI support |
| Vector Store Management | Lifecycle management with automatic indexing wait and exponential backoff |
| Prompt Rendering | Handlebars-based template rendering for dynamic agent prompts |
| OpenTelemetry | Built-in tracing, metrics, and logging with OTLP exporter support |
| Configurable Tools | Enable file_search and/or code_interpreter via YAML configuration |
| Multi-Provider Support | Azure AI Foundry and Ollama (with reasoning mode, multimodal, and vector store integration) |
| Feature | Description |
|---|---|
| Content Analysis | Automatic detection of PDF content type (TextBased, ImageOnly, Mixed) |
| Image Extraction | Extract embedded images and render pages for vision model processing |
| Markdown Conversion | Convert text-based PDFs to markdown using PdfPig with layout detection |
| Vision Model Ready | Base64-encoded images compatible with Azure OpenAI GPT-4 Vision |
See AgentSdk.Pdf README for PDF processing documentation.
maf-agent-sdk/
├── src/
│ ├── Cyclotron.Maf.AgentSdk/ # Core SDK library
│ └── Cyclotron.Maf.AgentSdk.Pdf/ # PDF processing extensions
├── samples/
│ └── SpamDetection/ # Complete working example with PDF workflows
├── test/
│ ├── Cyclotron.Maf.AgentSdk.UnitTests/
│ └── Cyclotron.Maf.AgentSdk.Pdf.UnitTests/
└── docs/
├── CHANGELOG.md # Version history and migration guides
├── CICD.md # CI/CD and versioning
└── TELEMETRY.md # Observability setup
- SDK Documentation - Detailed API reference and configuration options
- Spam Detection Sample - Complete working example
- Changelog - Version history and migration guides
- Telemetry Guide - OpenTelemetry setup and configuration
- CI/CD Guide - Build pipeline and versioning
- Microsoft Agent Framework - Build AI agents using MAF
- Agent Framework: Get Started - Getting started guide
- Agent Framework: Conversations & Sessions - Managing agent conversations with sessions
- Azure AI Foundry: Agents - Azure AI Foundry agents overview
- Azure AI Foundry: Agent API Reference - Agent operations API
This project uses GitVersion with semantic versioning following the GitFlow workflow. Versions are automatically bumped based on commit message keywords.
Add +semver: to your commit messages to control version increments:
| Keyword | Version Bump | Example |
|---|---|---|
+semver: breaking or +semver: major |
Major (X.0.0) | BREAKING CHANGE: +semver: major Refactor API |
+semver: feature or +semver: minor |
Minor (0.X.0) | CHANGE: +semver: feature Add new endpoint |
+semver: fix or +semver: patch |
Patch (0.0.X) | FIX: +semver: patch Resolve dependency issue |
+semver: skip or +semver: none |
No bump | CHORE: +semver: skip Update docs |
- main - Stable releases (1.0.0, 1.0.1, 2.0.0, etc.)
- dev - Alpha pre-releases (1.1.0-alpha.1, 1.1.0-alpha.2, etc.)
- release/* - Release candidates (1.0.0-rc.1, 1.0.0-rc.2, etc.)
- feature/* - Feature branches with pre-release labels
- hotfix/* - Patch releases for critical fixes
For more details, see GitVersion.yaml
- .NET 8.0 or later
- Azure AI Foundry project with a deployed model (GPT-4o, GPT-4o-mini, etc.)
- Azure CLI authenticated (
az login) or service principal credentials
A complete example demonstrating:
- Agent configuration via YAML
- Vector store creation with training data
- Message classification with confidence scores
- Full agent lifecycle management
cd samples/SpamDetection
dotnet run┌─────────────────────────────────────────────────────────────┐
│ Your Application │
├─────────────────────────────────────────────────────────────┤
│ Cyclotron.Maf.AgentSdk │
│ ┌─────────────┐ ┌─────────────┐ ┌─────────────────────┐ │
│ │AgentFactory │ │VectorStore │ │PromptRendering │ │
│ │ │ │Manager │ │Service │ │
│ └──────┬──────┘ └──────┬──────┘ └──────────┬──────────┘ │
├─────────┼────────────────┼────────────────────┼─────────────┤
│ │ Microsoft Agent Framework (MAF) │ │
│ │ ┌─────────────────────────────┐ │ │
│ │ │ Workflow Executors │ │ │
│ │ │ AIAgent / AgentSession │ │ │
│ └────┴─────────────────────────────┴──┘ │
├─────────────────────────────────────────────────────────────┤
│ Azure AI Foundry │
│ ┌─────────────┐ ┌─────────────┐ ┌─────────────────────┐ │
│ │ Agents API │ │Vector Stores│ │ Model Deployments │ │
│ └─────────────┘ └─────────────┘ └─────────────────────┘ │
└─────────────────────────────────────────────────────────────┘
Contributions are welcome! Please see our contributing guidelines.
# Clone the repository
git clone https://github.com/cyclotron-azure/maf-agent-sdk.git
cd maf-agent-sdk
# Build
dotnet build
# Run tests
dotnet test
# Run sample
cd samples/SpamDetection
cp .env.example .env
# Edit .env with your Azure AI Foundry credentials
dotnet runThis project is licensed under the MIT License - see the LICENSE file for details.
Cyclotron is an award-winning technology consultancy specializing in Microsoft solutions, AI innovation, and enterprise security. Founded in 2014 and headquartered in San Francisco, Cyclotron helps organizations accelerate digital transformation through services spanning Azure cloud, modern work, compliance, and custom AI platforms. As a multi-year Microsoft Partner of the Year and member of the Copilot Early Access Program, Cyclotron delivers integrated solutions that drive real business impact—empowering clients to work smarter, scale faster, and innovate securely.
Learn more at cyclotron.com.