Researching Azure AI SDK

Researching Azure AI SDK

CRITICAL: Don't guess SDK usage. Follow this research workflow.

Subagent Delegation for Research

Multi-repo research blows up context (1000+ tokens per file). Delegate to subagent for:

• Searching across 3+ repositories
• Reading 5+ files for patterns
• Comprehensive API surface exploration
• Finding all usages of a method/type

Delegation Pattern

runSubagent(
  prompt: "RESEARCH task - do NOT write code.
    
    **Question**: [specific SDK question]
    
    **Search these sources in order**:
    1. Azure.AI.Projects SDK: github.com/Azure/azure-sdk-for-net/tree/main/sdk/ai/Azure.AI.Projects
    2. Azure.AI.Agents.Persistent samples: .../Azure.AI.Agents.Persistent/samples
    3. Microsoft Foundry Samples: github.com/microsoft-foundry/foundry-samples
    
    **Find**:
    - Method signatures for [specific API]
    - Usage examples (pseudocode only)
    - Any gotchas or edge cases
    
    **Return** (max 20 lines):
    - Key method name and signature
    - Code pattern (pseudocode)
    - File path where found (for later reference)
    
    Do NOT include full file contents.",
  description: "SDK research: [topic]"
)

When to Delegate vs Inline

SDK Architecture Overview

The Foundry Agent Service SDK has two API surfaces for agents:

This project uses v2 Agents API for human-readable agent IDs.

Azure.AI.Projects (Main Entry Point)
├── AIProjectClient
│   ├── .AgentAdministrationClient.GetAgentVersionAsync() → ProjectsAgentVersion (v2 Agents API)
│   ├── .GetPersistentAgentsClient() → PersistentAgentsClient (Assistants API)
│   └── .ProjectOpenAIClient.GetProjectResponsesClientForAgent() → ProjectResponsesClient (Responses API)
└── Companion packages:
    ├── Azure.AI.Projects.Agents (ProjectsAgentVersion, DeclarativeAgentDefinition, …)
    ├── Azure.AI.Extensions.OpenAI (ProjectConversationsClient, ProjectOpenAIClient, …)
    └── OpenAI.Responses (streaming types)

1. Primary SDK Repository (Start Here)

Azure.AI.Projects SDK: https://github.com/Azure/azure-sdk-for-net/tree/main/sdk/ai/Azure.AI.Projects

• README: Core client patterns, authentication, basic operations
• Samples: tests/Samples/ folder with full examples

Azure.AI.Agents.Persistent SDK: https://github.com/Azure/azure-sdk-for-net/tree/main/sdk/ai/Azure.AI.Agents.Persistent

• 33+ samples covering streaming, file search, Bing grounding, MCP, Azure Functions
• Key samples:
  • Sample9_PersistentAgents_Streaming.md - Basic streaming pattern
  • Sample8_PersistentAgents_FunctionsWithStreaming.md - Tool calls with streaming
  • Sample27_PersistentAgents_MCP_Streaming.md - MCP server integration

2. Official Quickstart Samples

Microsoft Foundry Samples: https://github.com/microsoft-foundry/foundry-samples

• samples/csharp/quickstart/quickstart-chat-with-agent.cs - Responses API pattern
• samples/csharp/quickstart/ - Multiple quickstart examples

Key pattern from official quickstart:

AIProjectClient projectClient = new(new Uri(projectEndpoint), new AzureCliCredential());
ProjectConversation conversation = projectClient.ProjectOpenAIClient.GetProjectConversationsClient().CreateProjectConversation();
ProjectResponsesClient responsesClient = projectClient.ProjectOpenAIClient.GetProjectResponsesClientForAgent(
    defaultAgent: agentName,
    defaultConversationId: conversation.Id);
ResponseResult response = responsesClient.CreateResponse("Your prompt");

3. Azure Architecture Center Samples

Baseline Chat App: https://github.com/Azure-Samples/microsoft-foundry-baseline

• Full production architecture with Entra ID auth
• website/chatui/Controllers/ChatController.cs - SSE streaming pattern

Basic Chat Example: https://github.com/Azure-Samples/microsoft-foundry-basic

• Simpler example of Foundry agent chat integration

Semantic Kernel + Foundry: https://github.com/Azure-Samples/app-service-agentic-semantic-kernel-ai-foundry-agent

• Integration pattern for Semantic Kernel with Foundry Agents

4. UI Reference Samples (React Patterns)

Primary UI Reference

Azure AI Agents React Sample: https://github.com/Azure-Samples/get-started-with-ai-agents

This is the primary UI reference for this project. Many UI patterns were borrowed from here:

• Chat interface components
• Message rendering with citations/annotations
• Streaming text display
• Responsive layout patterns

Agent Framework DevUI (Python)

Agent Framework DevUI: https://github.com/microsoft/agent-framework/tree/main/python/packages/devui

Alternative UI patterns for agent development:

• Development-focused chat interface
• Multi-agent visualization
• Tool call debugging UI

UI Component Inspiration

When implementing new UI features, check these sources in order:

1. get-started-with-ai-agents - React + TypeScript patterns for chat UI
2. agent-framework/devui - Development UI patterns
3. Fluent UI Copilot Components - Base component library (already used)

5. Semantic Kernel Integration

Repository: https://github.com/microsoft/semantic-kernel

Relevant paths:

• dotnet/src/Agents/OpenAI/ - OpenAI Responses API integration
• dotnet/samples/GettingStartedWithAgents/AzureAIAgent/
• dotnet/samples/Concepts/Agents/ (Step##_*.cs files)

6. OpenAI .NET SDK (Streaming Types)

Repository: https://github.com/openai/openai-dotnet

• docs/guides/streaming-responses/ - Streaming patterns
• Source of StreamingResponseOutputTextDeltaUpdate and related types

7. GitHub Code Search (For Specific Patterns)

Use GitHub search to find usage examples:

# Find streaming patterns
"StreamingResponseOutputTextDeltaUpdate language:csharp"

# Find Responses API usage
"ProjectResponsesClient CreateResponseStreamingAsync language:csharp"

# Find conversation patterns
"ProjectConversation GetProjectResponsesClientForAgent language:csharp"

Current SDK Packages

Note: Check WebApp.Api.csproj for current versions. This project requires Azure.AI.Projects GA with v2 Agents API support (AIProjectClient.AgentAdministrationClient).

Companion packages used:

• Azure.AI.Projects.Agents — ProjectsAgentVersion, ProjectsAgentRecord, DeclarativeAgentDefinition / HostedAgentDefinition / WorkflowAgentDefinition, AgentAdministrationClient
• Azure.AI.Extensions.OpenAI — ProjectOpenAIClient, ProjectConversationsClient, ProjectResponsesClient, ProjectConversation
• OpenAI.Responses — streaming types

Agent Framework (Microsoft.Agents.AI.AzureAI): Not referenced. As of rc5, incompatible with Azure.AI.Projects 2.0.0 GA. See "Compatibility blocker" below.

Key Resources:

• NuGet (Azure.AI.Projects): https://www.nuget.org/packages/Azure.AI.Projects
• SDK Source: https://github.com/Azure/azure-sdk-for-net/tree/main/sdk/ai/Azure.AI.Projects
• v2 Migration Guide: https://learn.microsoft.com/en-us/azure/ai-foundry/agents/how-to/migrate
• API Reference: https://learn.microsoft.com/en-us/dotnet/api/azure.ai.projects
• Product Docs: https://learn.microsoft.com/azure/ai-studio/
• Infrastructure Bicep Templates: https://github.com/microsoft-foundry/foundry-samples/tree/main/infrastructure/infrastructure-setup-bicep

Official Azure AI Foundry Agent Service Documentation

Start here when researching agent capabilities, limits, or new features:

Agent Framework (Microsoft.Agents) docs: