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. Evaluations — Quality, safety, and self-reflection

Why Foundry?

Managed platform for building, deploying, and monitoring AI agents at scale

Azure OpenAI vs MAF + Azure AI Foundry

What Changes?

New package:

#:package Microsoft.Agents.AI.AzureAI@1.0.0-rc5
#:package Azure.AI.Projects@2.0.0-beta.2

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
AgentVersion agentVersion = await aiProjectClient.Agents.CreateAgentVersionAsync(
    agentName: "FoundryBasicsAgent",
    options: new AgentVersionCreationOptions(
        new PromptAgentDefinition(deploymentName)
        {
            Instructions = "You are a friendly assistant. Keep your answers brief.",
        }));
AIAgent agent = aiProjectClient.AsAIAgent(agentVersion);

Retrieve & Run — Same API

// Retrieve latest version by name
AgentRecord record = await aiProjectClient.Agents.GetAgentAsync("FoundryBasicsAgent");
AIAgent retrieved = aiProjectClient.AsAIAgent(record);

// 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 CreateAgentVersionAsync call creates a new version
AgentVersion v1 = await aiProjectClient.Agents.CreateAgentVersionAsync(
    agentName: "MyAgent",
    options: new (new PromptAgentDefinition("gpt-4o-mini") {
        Instructions = "You are helpful."
    }));

AgentVersion v2 = await aiProjectClient.Agents.CreateAgentVersionAsync(
    agentName: "MyAgent",
    options: new (new PromptAgentDefinition("gpt-4o-mini") {
        Instructions = "You are extremely helpful and concise."
    }));

// GetAgentAsync returns the latest version as an AgentRecord
AgentRecord latestRecord = await aiProjectClient.Agents.GetAgentAsync("MyAgent");
AIAgent latest = aiProjectClient.AsAIAgent(latestRecord);

Observability

OpenTelemetry + 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
AgentVersion agentVersion = await aiProjectClient.Agents.CreateAgentVersionAsync(
    agentName: "FoundryBasicsAgent",
    options: new (new PromptAgentDefinition(deploymentName) { Instructions = "You are a friendly assistant." }));
AIAgent agent = aiProjectClient
    .AsAIAgent(agentVersion)
    .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.");

Persistent Sessions

Server-side conversations with Foundry

Creating a Foundry Conversation

// Get agent client
AIAgent foundryAgent = aiProjectClient.AsAIAgent(agentVersion);
ChatClientAgent agent = foundryAgent.GetService<ChatClientAgent>()!;

// Create a server-side conversation
ProjectConversationsClient conversationsClient = aiProjectClient
    .GetProjectOpenAIClient()
    .GetProjectConversationsClient();

ProjectConversation conversation = await conversationsClient.CreateProjectConversationAsync();

// Link session to the conversation — history stored server-side
AgentSession session = await agent.CreateSessionAsync(conversation.Id);

// Run
Console.WriteLine(await agent.RunAsync("My name is Oleksii.", session));

Resuming a Conversation

// New session, same conversation ID — agent remembers everything

AgentSession resumed = await agent.CreateSessionAsync(conversation.Id);
Console.WriteLine(await agent.RunAsync("What's my name?", resumed));

// → "Your name is Oleksii."

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)
{
    return $"The weather in {location} is sunny with a high of 22°C.";
}

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

Creating Agent with Tools

// Register schema server-side (declarative) + provide invocable impl client-side
AgentVersion agentVersion = await aiProjectClient.Agents.CreateAgentVersionAsync(
    agentName: "WeatherAgent",
    options: new AgentVersionCreationOptions(
        new PromptAgentDefinition(deploymentName)
        {
            Instructions = "You are a helpful assistant with weather tools.",
            Tools = { getWeather.AsOpenAIResponseTool() },
        }
    )
);

AIAgent agent = aiProjectClient.AsAIAgent(agentVersion, tools: tools);

Retrieving Agents with Tools

// IMPORTANT: Server only stores the tool schema (JSON Schema)
// You must provide invocable tools when retrieving
AgentRecord record = await aiProjectClient.Agents.GetAgentAsync("WeatherAgent");
AIAgent existing = aiProjectClient.AsAIAgent(
    record,
    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

AgentVersion agentVersion = await aiProjectClient.Agents.CreateAgentVersionAsync(
    agentName: "MathTutor",
    options: new AgentVersionCreationOptions(
        new PromptAgentDefinition(deploymentName)
        {
            Instructions = "You are a math tutor. Write and run Python code to solve problems.",
            Tools = { ResponseTool.CreateCodeInterpreterTool(
                new CodeInterpreterToolContainer(
                    CodeInterpreterToolContainerConfiguration.CreateAutomaticContainerConfiguration(fileIds: []))) },
        }));
AIAgent agent = aiProjectClient.AsAIAgent(agentVersion);

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

Web Search — Real-Time Queries

AgentVersion agentVersion = await aiProjectClient.Agents.CreateAgentVersionAsync(
    agentName: "WebSearchAgent",
    options: new AgentVersionCreationOptions(
        new PromptAgentDefinition(deploymentName)
        {
            Instructions = "Search the web to answer questions accurately. Cite your sources.",
            Tools = { ResponseTool.CreateWebSearchTool() },
        }));
AIAgent agent = aiProjectClient.AsAIAgent(agentVersion);

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" });

// Wait for file ingestion to complete before querying
while ((await vectorStoresClient.GetVectorStoreAsync(vectorStore.Value.Id)).Value.Status
    != VectorStoreStatus.Completed)
{
    await Task.Delay(500);
}

Create Agent with File Search

AgentVersion agentVersion = await aiProjectClient.Agents.CreateAgentVersionAsync(
    agentName: "RAGAgent",
    options: new AgentVersionCreationOptions(
        new PromptAgentDefinition(deploymentName)
        {
            Instructions = "Answer questions using the product catalog. Cite the source.",
            Tools = { ResponseTool.CreateFileSearchTool(vectorStoreIds: [vectorStoreId]) },
        }));
AIAgent agent = aiProjectClient.AsAIAgent(agentVersion);

// 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));

Foundry Workflows

Declarative multi-agent orchestration

Workflow YAML — Storyteller + Critic

kind: Workflow
trigger:
  kind: OnConversationStart
  id: story_critic_workflow
  actions:
    - kind: InvokeAzureAgent
      id: storyteller_step
      conversationId: =System.ConversationId
      agent:
        name: StorytellerAgent
    - kind: InvokeAzureAgent
      id: critic_step
      conversationId: =System.ConversationId
      agent:
        name: CriticAgent

Registering & Running a Workflow

// Register workflow in Foundry
AgentVersion workflowVersion = await aiProjectClient.Agents
    .CreateAgentVersionAsync(WorkflowName, new(workflowDefinition));

// Run with streaming — each agent produces a separate message
AgentRecord workflowRecord = await aiProjectClient.Agents.GetAgentAsync(WorkflowName);
ChatClientAgent workflowAgent = (ChatClientAgent)aiProjectClient.AsAIAgent(workflowRecord);

ChatClientAgentRunOptions runOptions = new(
    new ChatOptions { ConversationId = conversation.Id });

await foreach (var update in workflowAgent.RunStreamingAsync(prompt, session, runOptions))
{
    Console.Write(update.Text);
}

Evaluations

Quality and safety scoring

Available Evaluators

Running Evaluations

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

// Safety evaluators need the Foundry content safety endpoint
ContentSafetyServiceConfiguration safetyConfig = new(credential, new Uri(endpoint));
ChatConfiguration config = safetyConfig.ToChatConfiguration(
    originalChatConfiguration: new ChatConfiguration(chatClient));

EvaluationResult result = await evaluator.EvaluateAsync(
    messages, chatResponse, config, additionalContext: [new GroundednessEvaluatorContext(context)]);

Key Takeaways

1. AIProjectClient.Agents.CreateAgentVersionAsync() + AsAIAgent() — same AIAgent API, server-managed lifecycle with versioning

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

3. ResponseTool.CreateCodeInterpreterTool() / CreateWebSearchTool() — zero-infrastructure hosted tools

4. File upload → vector store → ResponseTool.CreateFileSearchTool() — RAG in ~10 lines

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

Resources

• MAF Documentation
• MAF Samples
• Azure AI Foundry
• Azure.AI.Projects SDK
• Microsoft.Extensions.AI.Evaluation
• This repo