👁 Image
AgentSdk 1.4.0

Cyclotron.Maf.AgentSdk

👁 NuGet Version
👁 NuGet Downloads
👁 Build Status
👁 License: MIT
👁 .NET

A .NET SDK for building AI agent workflows using Microsoft Agent Framework (MAF) and Azure AI Foundry. Provides workflow orchestration, agent factories, vector store management, and OpenTelemetry integration.

For PDF processing features, see .

Features

• 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 for Azure AI Foundry vector stores with automatic indexing wait
• 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 provider support

For PDF processing features (image extraction, content analysis, markdown conversion), see .

Installation

dotnet add package AgentSdk

# For PDF processing features
dotnet add package AgentSdk.Pdf

Session Management

Sessions maintain conversation context and state across multiple agent invocations. Each session is created per agent and managed throughout the workflow:

• Session Creation: Automatically created when CreateAgentAsync() is called
• Session Reuse: Persists across multiple RunAgentWithPollingAsync() calls
• Session Cleanup: Automatically deleted when CleanupAsync() is called (if auto_delete is true)

Quick Start

1. Configure Services

using Cyclotron.Maf.AgentSdk.Agents;
using Cyclotron.Maf.AgentSdk.Services;
using Microsoft.Extensions.DependencyInjection;

var builder = Host.CreateApplicationBuilder(args);

// Load agent configuration from agent.config.yaml and .env files
builder.UseAgentSdk();

// Register core services
builder.Services.AddAgentSdkServices();

// Add telemetry (optional)
builder.AddAgentSdkTelemetry();

2. Define Agent Configuration

Create agent.config.yaml in your project:

# Model Provider Configuration
providers:
 azure_foundry:
 type: "azure_foundry"
 endpoint: "${PROJECT_ENDPOINT}" # Environment variable substitution
 deployment_name: "${PROJECT_DEPLOYMENT_NAME}"
 api_version: "2024-12-01-preview"
 timeout_seconds: 300
 max_retries: 3

# Agent Configuration
agents:
 my_agent:
 type: "custom"
 enabled: true
 auto_delete: true # Delete agent after workflow completes
 auto_cleanup_resources: true # Delete vector store after workflow completes

 metadata:
 description: "Document processing agent"
 tools: # Configure which tools the agent can use
 - "file_search" # Enable document search in vector stores
 - "code_interpreter" # Enable Python code execution (optional)

 provider: "azure_foundry" # Reference to providers section

 system_prompt_template: |
 You are a helpful assistant specialized in document analysis.

 user_prompt_template: |
 Process the document: {{fileName}}
 Context: {{context}}

3. Set Environment Variables

Create a .env file in your project root:

PROJECT_ENDPOINT=https://your-project.api.azureml.ms
PROJECT_DEPLOYMENT_NAME=gpt-4o

4. Create Workflow Executors

using Cyclotron.Maf.AgentSdk.Agents;
using Microsoft.Agents.AI.Workflows.Executors;
using Microsoft.Extensions.DependencyInjection;

public class MyProcessingExecutor : Executor<InputType, OutputType>
{
 private readonly IAgentFactory _agentFactory;

 public MyProcessingExecutor(
 [FromKeyedServices("my_agent")] IAgentFactory agentFactory)
 {
 _agentFactory = agentFactory;
 }

 public override async ValueTask<OutputType> HandleAsync(
 InputType input,
 IWorkflowContext context,
 CancellationToken cancellationToken = default)
 {
 // Create agent with vector store
 await _agentFactory.CreateAgentAsync(vectorStoreId, cancellationToken);

 try
 {
 // Run agent with automatic retry and polling
 var response = await _agentFactory.RunAgentWithPollingAsync(
 messages: [_agentFactory.CreateUserMessage(promptContext)],
 cancellationToken: cancellationToken);

 // Process response...
 return result;
 }
 finally
 {
 // Cleanup respects auto_delete and auto_cleanup_resources settings
 // This deletes the agent, session, and optionally the vector store
 await _agentFactory.CleanupAsync(cancellationToken);
 }
 }
}

5. Build and Execute Workflow

using Microsoft.Agents.AI.Workflows;

var workflow = new WorkflowBuilder(executor1)
 .AddEdge(executor1, executor2)
 .AddEdge(executor2, executor3)
 .WithOutputFrom(executor3)
 .Build();

var result = await workflow.ExecuteAsync<OutputType>(input, cancellationToken);

Configuration Reference

Agent Configuration (agent.config.yaml)

Provider Options

Agent Definition Options

Agent Metadata Options

Note: If no tools are configured, file_search is enabled by default when creating an agent with a vector store.

Provider Reference

Environment Variables

Values in agent.config.yaml support ${VAR_NAME} syntax for environment variable substitution:

endpoint: "${PROJECT_ENDPOINT}" # Reads PROJECT_ENDPOINT from environment
deployment_name: "${PROJECT_DEPLOYMENT_NAME}"

Application Settings (appsettings.json)

Telemetry Options

{
 "Telemetry": {
 "Enabled": true,
 "SourceName": "MyAgentService",
 "EnableSensitiveData": false,
 "OtlpEndpoint": "http://localhost:4318"
 }
}

Vector Store Indexing Options

{
 "VectorStoreIndexing": {
 "MaxWaitAttempts": 60,
 "InitialWaitDelayMs": 2000,
 "UseExponentialBackoff": true,
 "MaxWaitDelayMs": 30000,
 "TotalTimeoutMs": 0
 }
}

For PDF-related configuration options, see .

Namespaces

Key Interfaces

For PDF processing interfaces, see .

Microsoft Learn Documentation

For more information on Microsoft Agent Framework and session management, refer to these official resources:

• Microsoft Agent Framework Overview - Core framework concepts and architecture
• Agent Framework Get Started - Quick start guide
• Agent Framework: Sessions & Conversations - Managing agent sessions for maintaining conversation context
• Agent Framework: Memory Management - How agents remember conversation history
• Azure AI Foundry Agents - Creating and managing agents in Azure AI Foundry
• Azure AI Foundry: Vector Stores - Vector store concepts and management
• OpenTelemetry Integration - Observability and telemetry for .NET applications

Workflow State Management

Use WorkflowStateConstants for common state keys:

using Cyclotron.Maf.AgentSdk.Models.Workflow;

// Define your domain-specific scope constants
public static class MyWorkflowStateConstants
{
 public static readonly string MyDataScope = nameof(MyDataScope);
}

// Store data in workflow state
await context.QueueStateUpdateAsync(
 MyWorkflowStateConstants.MyDataScope,
 data,
 scopeName: WorkflowStateConstants.GetScopeName(workflowId, MyWorkflowStateConstants.MyDataScope),
 cancellationToken);

// Read data from workflow state
var data = await context.ReadStateAsync<MyType>(
 MyWorkflowStateConstants.MyDataScope,
 scopeName: WorkflowStateConstants.GetScopeName(workflowId, MyWorkflowStateConstants.MyDataScope),
 cancellationToken);

Dependencies

For PDF processing dependencies (PdfPig, System.Drawing.Common), see .

For vector store dependencies (OllamaSharp), see .

Requirements

• .NET 8.0 or later
• For Azure providers: Azure AI Foundry project endpoint
• For Ollama providers: Ollama installed and running locally or remotely
• Azure credentials (DefaultAzureCredential or API key)

Samples

See the for a complete working example.

License

MIT