Agenda

1. Why Foundry? — From plain Azure OpenAI to managed agents
2. First Foundry Agent — AIProjectClient + versioning
3. Observability — OpenTelemetry + Aspire + Foundry traces
4. Function Tools — Same pattern, server-side management
5. Hosted Tools — Code Interpreter, Web Search
6. RAG via Foundry — File upload, vector stores, file search
7. Memory — Cross-session recall with MemorySearchTool
8. Evaluations — Quality, safety, and self-reflection

Why Foundry?

From Azure OpenAI to managed agents

Azure OpenAI vs Azure AI Foundry

What Changes?

New package:

#:package Microsoft.Agents.AI.AzureAI@1.0.0-rc4
#:package Azure.AI.Projects@1.2.0-beta.5

New entry point:

AIProjectClient aiProjectClient = new(new Uri(endpoint), new DefaultAzureCredential());

New env var:

export AZURE_AI_PROJECT_ENDPOINT="https://your-project.services.ai.azure.com/api"

First Foundry Agent

Server-side managed agents with versioning

Creating a Foundry Agent

AIProjectClient aiProjectClient = new(new Uri(endpoint), new DefaultAzureCredential());

// Create a server-side agent — Foundry manages it with name + version
AIAgent agent = await aiProjectClient.CreateAIAgentAsync(
    name: "FoundryBasicsAgent",
    model: deploymentName,
    instructions: "You are a friendly assistant. Keep your answers brief.");

Retrieve & Run — Same API

// Retrieve latest version by name
AIAgent retrieved = await aiProjectClient.GetAIAgentAsync(name: "FoundryBasicsAgent");

// Non-streaming — same as Azure OpenAI agents
Console.WriteLine(await agent.RunAsync("Tell me a fun fact about Azure."));

// Streaming — same as Azure OpenAI agents
await foreach (var update in agent.RunStreamingAsync("Tell me a fun fact about .NET."))
{
    Console.Write(update);
}

// Cleanup — deletes server-side agent and all its versions
await aiProjectClient.Agents.DeleteAgentAsync(agent.Name);

Agent Versioning

// Each CreateAIAgentAsync call creates a new version
AIAgent v1 = await aiProjectClient.CreateAIAgentAsync(
    name: "MyAgent", model: "gpt-4o-mini",
    instructions: "You are helpful.");

AIAgent v2 = await aiProjectClient.CreateAIAgentAsync(
    name: "MyAgent", model: "gpt-4o-mini",
    instructions: "You are extremely helpful and concise.");

// GetAIAgentAsync returns the latest version
AIAgent latest = await aiProjectClient.GetAIAgentAsync(name: "MyAgent");

Observability

OpenTelemetry + Aspire Dashboard + Foundry Traces

Two Sides of the Trace

Adding OpenTelemetry to a Foundry Agent

// 1. Setup OTLP exporter → Aspire dashboard
using var tracerProvider = Sdk.CreateTracerProviderBuilder()
    .SetResourceBuilder(ResourceBuilder.CreateDefault().AddService("FoundryBasicsDemo"))
    .AddSource("FoundryBasicsDemo")
    .AddSource("*Microsoft.Agents.AI")
    .AddOtlpExporter()
    .Build();

// 2. Wrap agent with telemetry
AIAgent agent = (await aiProjectClient.CreateAIAgentAsync(
    name: "FoundryBasicsAgent", model: deploymentName,
    instructions: "You are a friendly assistant."))
    .AsBuilder()
    .UseOpenTelemetry(sourceName: "FoundryBasicsDemo")
    .Build();

Correlated Traces

// Parent span groups related calls
using var activitySource = new ActivitySource("FoundryBasicsDemo");
using var activity = activitySource.StartActivity("foundry-basics-demo");

Console.WriteLine($"Trace ID: {activity?.TraceId}");

await agent.RunAsync("Tell me a fun fact about Azure.");
await agent.RunStreamingAsync("Tell me a fun fact about .NET.");

Function Tools

Same pattern, managed by Foundry

Function Tools on Foundry

[Description("Get the weather for a given location.")]
static string GetWeather([Description("The location")] string location)
    => $"The weather in {location} is sunny with a high of 22°C.";

AITool[] tools = [AIFunctionFactory.Create(GetWeather)];

// Server stores tool schemas, client provides invocable implementations
AIAgent agent = await aiProjectClient.CreateAIAgentAsync(
    name: "WeatherAgent", model: deploymentName,
    instructions: "You are a helpful assistant with weather tools.",
    tools: tools);

Retrieving Agents with Tools

// IMPORTANT: Server only stores the tool schema (JSON Schema)
// You must provide invocable tools when retrieving
var existing = await aiProjectClient.GetAIAgentAsync(
    name: "WeatherAgent",
    tools: [AIFunctionFactory.Create(GetWeather)]);

Console.WriteLine(await existing.RunAsync("What's the weather in Kyiv?"));

Hosted Tools

Code Interpreter, Web Search — zero infrastructure

Hosted vs Client Tools

Code Interpreter — Python Sandbox

AIAgent agent = await aiProjectClient.CreateAIAgentAsync(
    model: deploymentName,
    name: "MathTutor",
    instructions: "You are a math tutor. Write and run Python code to solve problems.",
    tools: [new HostedCodeInterpreterTool() { Inputs = [] }]);

AgentResponse response = await agent.RunAsync(
    "Solve x^3 - 6x^2 + 11x - 6 = 0. Plot the function and mark the roots.");

Extracting Code & Results

// Get the Python code that was executed
var toolCall = response.Messages.SelectMany(m => m.Contents)
    .OfType<CodeInterpreterToolCallContent>().FirstOrDefault();

if (toolCall?.Inputs?.OfType<DataContent>().FirstOrDefault() is { } code)
    Console.WriteLine(Encoding.UTF8.GetString(code.Data.ToArray()));

// Get the execution result
var toolResult = response.Messages.SelectMany(m => m.Contents)
    .OfType<CodeInterpreterToolResultContent>().FirstOrDefault();

if (toolResult?.Outputs?.OfType<TextContent>().FirstOrDefault() is { } result)
    Console.WriteLine(result.Text);

Web Search — Real-Time Queries

AIAgent agent = await aiProjectClient.CreateAIAgentAsync(
    name: "WebSearchAgent",
    model: deploymentName,
    instructions: "Search the web to answer questions accurately. Cite your sources.",
    tools: [new HostedWebSearchTool()]);

AgentResponse response = await agent.RunAsync("What are the latest features in .NET 10?");

Extracting URL Citations

foreach (var annotation in response.Messages
    .SelectMany(m => m.Contents)
    .SelectMany(c => c.Annotations ?? []))
{
    if (annotation.RawRepresentation is UriCitationMessageAnnotation urlCitation)
    {
        Console.WriteLine($"  - {urlCitation.Title}: {urlCitation.Uri}");
    }
}

RAG via Foundry

File upload → Vector store → Grounded Q&A

The RAG Pipeline

Upload & Create Vector Store

var projectOpenAIClient = aiProjectClient.GetProjectOpenAIClient();
var filesClient = projectOpenAIClient.GetProjectFilesClient();
var vectorStoresClient = projectOpenAIClient.GetProjectVectorStoresClient();

// Upload knowledge base
OpenAIFile uploaded = filesClient.UploadFile(tempFile, FileUploadPurpose.Assistants);

// Create vector store — auto-chunks and embeds
var vectorStore = await vectorStoresClient.CreateVectorStoreAsync(
    new() { FileIds = { uploaded.Id }, Name = "contoso-products" });

Create Agent with File Search

AIAgent agent = await aiProjectClient.CreateAIAgentAsync(
    model: deploymentName,
    name: "RAGAgent",
    instructions: "Answer questions using the product catalog. Cite the source.",
    tools: [new HostedFileSearchTool() {
        Inputs = [new HostedVectorStoreContent(vectorStoreId)]
    }]);

// Multi-turn Q&A with grounded answers
var session = await agent.CreateSessionAsync();
Console.WriteLine(await agent.RunAsync("What's the cheapest product?", session));
Console.WriteLine(await agent.RunAsync("Which product supports CI/CD?", session));

Memory

Cross-session recall with Foundry Memory Stores

Memory Search Tool

// Memory store must be pre-created via Azure Portal
string memoryStoreName = Environment.GetEnvironmentVariable("AZURE_AI_MEMORY_STORE_ID")!;

// Scope isolates memories per user
string userScope = $"user_{Environment.MachineName}";

MemorySearchTool memorySearchTool = new(memoryStoreName, userScope)
{
    UpdateDelay = 1,  // seconds before new memories are indexed
};

AIAgent agent = await aiProjectClient.CreateAIAgentAsync(
    model: deploymentName, name: "MemoryAgent",
    instructions: "Remember user preferences across conversations.",
    tools: [((ResponseTool)memorySearchTool).AsAITool()]);

Cross-Session Recall

// Session 1: Share preferences
await agent.RunAsync("My name is Alex. I prefer dark mode in all my tools.");

// Wait for memory indexing
await Task.Delay(3000);

// Session 2: Test recall — agent remembers without chat history
await agent.RunAsync("What do you know about me?");
// → "Your name is Alex and you prefer dark mode."

Inspecting Memory Results

foreach (var message in response.Messages)
{
    if (message.RawRepresentation is MemorySearchToolCallResponseItem memoryResult)
    {
        foreach (var result in memoryResult.Results)
        {
            Console.WriteLine($"  [{result.MemoryItem.Scope}] {result.MemoryItem.Content}");
        }
    }
}

Evaluations

Quality, safety, and self-reflection

Why Evaluate?

Before production, you need to know:

Self-Reflection Loop

Based on Reflexion (NeurIPS 2023) — verbal reinforcement learning

GroundednessEvaluator evaluator = new();

for (int i = 0; i < 3; i++)
{
    AgentResponse agentResponse = await agent.RunAsync(currentPrompt, session);
    EvaluationResult result = await evaluator.EvaluateAsync(
        messages, chatResponse, config, additionalContext: [groundingContext]);

    double score = result.Get<NumericMetric>(
        GroundednessEvaluator.GroundednessMetricName).Value ?? 0;

    if (score >= 4.0) break;

    currentPrompt = $"Your answer scored {score}/5. Improve grounding.";
}

Combined Quality + Safety

CompositeEvaluator evaluator = new([
    new RelevanceEvaluator(),
    new CoherenceEvaluator(),
    new ContentHarmEvaluator(),
]);

// Safety evaluators use Azure AI Foundry content safety endpoint
ContentSafetyServiceConfiguration safetyConfig = new(
    credential: credential, endpoint: new Uri(endpoint));

ChatConfiguration config = safetyConfig.ToChatConfiguration(
    originalChatConfiguration: new ChatConfiguration(chatClient));

EvaluationResult result = await evaluator.EvaluateAsync(
    messages, chatResponse, config);

Evaluation Output

=== Quality + Safety Evaluation ===

  Relevance               Score: 5.0/5  Rating: Good
  Coherence               Score: 4.5/5  Rating: Good
  ContentHarm.Violence    Value: False   Rating: Good    Failed: False
  ContentHarm.SelfHarm    Value: False   Rating: Good    Failed: False
  ContentHarm.Sexual      Value: False   Rating: Good    Failed: False
  ContentHarm.HateUnfair  Value: False   Rating: Good    Failed: False

Key Takeaways

1. AIProjectClient.CreateAIAgentAsync() — same AIAgent API, server-managed lifecycle

2. .UseOpenTelemetry() + Aspire — client spans correlated with Foundry server traces

3. HostedCodeInterpreterTool / HostedWebSearchTool — zero-infrastructure hosted tools

4. File upload → vector store → HostedFileSearchTool — RAG in ~10 lines

5. MemorySearchTool — cross-session memory, user-scoped, Foundry-managed

6. GroundednessEvaluator + ContentHarmEvaluator — evaluate quality and safety before production

Resources

• MAF Documentation
• MAF Samples
• Azure AI Foundry
• Azure.AI.Projects SDK
• Microsoft.Extensions.AI.Evaluation
• Reflexion Paper (NeurIPS 2023)
• This repo