# Researching Azure AI Sdk > Provides research patterns for Foundry Agent Service SDK. Use when implementing agent features, looking up SDK methods, finding code samples, or troubleshooting Azure.AI.Projects API usage. - Skill: `microsoft-foundry/researching-azure-ai-sdk` (Agent Skill) - Install (CLI): `npx skillmds@latest add microsoft-foundry/researching-azure-ai-sdk` - Raw SKILL.md: https://api.skillmd.com/api/skills/microsoft-foundry/researching-azure-ai-sdk/raw - Safety review: pending - Works with: Claude Code, Claude.ai, OpenAI Codex - Category: DevOps & Infra - Author: microsoft-foundry (https://skillmd.com/u/microsoft-foundry) - Updated: 2026-09-10 - Page: https://skillmd.com/skills/microsoft-foundry/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 ```text 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 | Delegate to Subagent | Keep Inline | |----------------------|-------------| | Multi-repo code search | Local codebase grep | | Finding all usages | Known method lookup | | API surface exploration | Single file read | | Pattern comparison | Quick signature check | | Sample discovery | Using known pattern | ## SDK Architecture Overview The Foundry Agent Service SDK has **two API surfaces** for agents: | API | Endpoint | ID Format | SDK Access | |-----|----------|-----------|------------| | **v2 Agents API** | `/agents/` | Human-readable (e.g., `dadjokes`) | `AIProjectClient.AgentAdministrationClient` | | **OpenAI Assistants API** | `/assistants/` | OpenAI format (e.g., `asst_xxx`) | `PersistentAgentsClient` | **This project uses v2 Agents API** for human-readable agent IDs. ```text 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**: ```csharp 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: ```text # Find streaming patterns "StreamingResponseOutputTextDeltaUpdate language:csharp" # Find Responses API usage "ProjectResponsesClient CreateResponseStreamingAsync language:csharp" # Find conversation patterns "ProjectConversation GetProjectResponsesClientForAgent language:csharp" ``` ## Current SDK Packages | Package | Purpose | |---------|---------| | `Azure.AI.Projects` | Main entry point, `AIProjectClient`, v2 Agents API, Responses API | | `Azure.Identity` | Authentication (`AzureDeveloperCliCredential`, `ManagedIdentityCredential`) | | `Microsoft.Identity.Web` | JWT Bearer authentication for API | **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: | Topic | URL | |-------|-----| | **Agent Service overview** | https://learn.microsoft.com/azure/ai-foundry/agents/overview | | **Quickstart: Create an agent** | https://learn.microsoft.com/azure/ai-foundry/agents/quickstart | | **Agent concepts & architecture** | https://learn.microsoft.com/azure/ai-foundry/agents/concepts | | **Supported models** | https://learn.microsoft.com/azure/ai-foundry/agents/concepts/supported-models | | **Tools: File Search** | https://learn.microsoft.com/azure/ai-foundry/agents/how-to/tools/file-search | | **Tools: Code Interpreter** | https://learn.microsoft.com/azure/ai-foundry/agents/how-to/tools/code-interpreter | | **Tools: Bing Grounding** | https://learn.microsoft.com/azure/ai-foundry/agents/how-to/tools/bing-grounding | | **Tools: Azure AI Search** | https://learn.microsoft.com/azure/ai-foundry/agents/how-to/tools/azure-ai-search | | **Tools: Azure Functions** | https://learn.microsoft.com/azure/ai-foundry/agents/how-to/tools/azure-functions | | **MCP server tools** | https://learn.microsoft.com/azure/ai-foundry/agents/how-to/tools/mcp-servers | | **v2 Agents API migration** | https://learn.microsoft.com/azure/ai-foundry/agents/how-to/migrate | | **REST API reference** | https://learn.microsoft.com/rest/api/azureai/agents | | **Quotas & limits** | https://learn.microsoft.com/azure/ai-foundry/agents/concepts/quotas-limits | **Agent Framework (Microsoft.Agents) docs**: | Topic | URL | |-------|-----| | **Agent Framework overview** | https://learn.microsoft.com/microsoft-agents/overview | | **Agent Framework .NET SDK** | https://github.com/microsoft/Agents-for-net | | **NuGet package** | https://www.nuget.org/packages/Microsoft.Agents.AI.AzureAI | | **IChatClient abstraction** | https://learn.microsoft.com/dotnet/api/microsoft.extensions.ai.ichatclient | ## Annotation Types in Responses The SDK provides several annotation types for citations (from `OpenAI.Responses` namespace): | Type | Class | Use Case | Key Properties | |------|-------|----------|----------------| | URI Citation | `UriCitationMessageAnnotation` | Bing, Azure AI Search, SharePoint | `Uri`, `Title`, `StartIndex`, `EndIndex` | | File Citation | `FileCitationMessageAnnotation` | File search (vector stores) | `FileId`, `Filename`, `Index` | | File Path | `FilePathMessageAnnotation` | Code interpreter output | `FileId`, `Index` | | Container Citation | `ContainerFileCitationMessageAnnotation` | Container file citations | `FileId`, `Filename`, `ContainerId`, `StartIndex`, `EndIndex` | **Note**: `FileCitationMessageAnnotation` uses `Index` (not `StartIndex`/`EndIndex`) per the SDK. See `ExtractAnnotations()` in `AgentFrameworkService.cs` for mapping to `AnnotationInfo`. ### Container File Download The C# SDK does not yet have a typed client for container file downloads. Use the REST API directly with a bearer token scoped to `https://ai.azure.com/.default`: ``` GET {projectEndpoint}/openai/v1/containers/{containerId}/files/{fileId}/content Authorization: Bearer {token} ``` For standard (non-container) files (`cfile_` prefix absent), use `OpenAI.Files.FileClient` instead. The backend endpoint `GET /api/files/{fileId}?containerId={id}` abstracts this: it routes `cfile_`-prefixed files through the REST API and standard files through `FileClient`. ## Streaming Response Types (from OpenAI.Responses namespace) | Type | Purpose | |------|---------| | `StreamingResponseOutputTextDeltaUpdate` | Text content delta chunks | | `StreamingResponseOutputItemDoneUpdate` | Item completion signals | | `StreamingResponseCompletedUpdate` | Response completion with usage | | `ResponseItem` | Base type for response items | **Pattern used in this project**: ```csharp await foreach (var update in responsesClient.CreateResponseStreamingAsync(...)) { if (update is StreamingResponseOutputTextDeltaUpdate textUpdate) yield return new StreamChunk { Text = textUpdate.Delta }; if (update is StreamingResponseOutputItemDoneUpdate itemDone) // Extract annotations from itemDone.Item } ``` ## Microsoft Agent Framework (NOT used — see rationale) **Package**: `Microsoft.Agents.AI.AzureAI` (prerelease, not referenced) **Status**: ❌ **Not installed.** Blocked on compatibility with `Azure.AI.Projects 2.0.0` GA. ### Compatibility blocker (as of rc5) `Microsoft.Agents.AI.AzureAI 1.0.0-rc5` pins `Azure.AI.Projects 2.0.0-beta.2` and references types removed in the GA release. Attempting to use rc5 with `Azure.AI.Projects 2.0.0` throws `TypeLoadException` at runtime. Re-evaluate when rc6+ ships. ### Why we use the direct SDK anyway Even when the compat blocker is lifted, this project's streaming path needs direct access to `ProjectResponsesClient` and typed response items that are not surfaced by the `IChatClient` abstraction: - `McpToolCallApprovalRequestItem` for MCP approval flows - `FileSearchCallResponseItem` for file search quotes - `MessageResponseItem.OutputTextAnnotations` for citations - `ResponseItem.CreateMcpApprovalResponseItem()` to respond to MCP approvals Routing through `ChatClientAgent.RunStreamingAsync()` would require casting `RawRepresentation` for each of these, which defeats the abstraction benefit. ### Current pattern (direct SDK only) ```csharp // Agent metadata — no "latest" keyword in the REST spec; enumerate versions descending. ProjectsAgentVersion? agentVersion = null; await foreach (var v in projectClient.AgentAdministrationClient.GetAgentVersionsAsync( agentName: agentName, limit: 1, order: AgentListOrder.Descending, after: null, before: null, cancellationToken: ct)) { agentVersion = v; break; } var definition = agentVersion?.Definition as DeclarativeAgentDefinition; string model = definition?.Model ?? ""; string instructions = definition?.Instructions ?? ""; // Streaming — pin the resolved version so streaming hits the same version as metadata. ProjectResponsesClient responsesClient = projectClient.ProjectOpenAIClient .GetProjectResponsesClientForAgent( new AgentReference(agentId, agentVersion?.Version), conversationId); await foreach (var update in responsesClient.CreateResponseStreamingAsync(...)) { } ``` ## Migration Notes `AIProjectClient` requires a project endpoint URI (not a connection string): ```csharp var projectClient = new AIProjectClient(new Uri(projectEndpoint), new DefaultAzureCredential()); ``` Connection-string constructors are deprecated. See: https://github.com/Azure/azure-sdk-for-net/blob/main/sdk/ai/Azure.AI.Projects/AGENTS_MIGRATION_GUIDE.md ## Additional SDK Resources ### Fetch SDK Source from GitHub (Authoritative) Type definitions live in these repos—read them directly: - **Azure.AI.Projects source**: https://github.com/Azure/azure-sdk-for-net/tree/main/sdk/ai/Azure.AI.Projects/src - **Azure.AI.Agents.Persistent samples**: https://github.com/Azure/azure-sdk-for-net/tree/main/sdk/ai/Azure.AI.Agents.Persistent/samples - **OpenAI.Responses types**: https://github.com/openai/openai-dotnet/tree/main/src ### GitHub Code Search Search across all .NET codebases for real-world usage: ```text "ProjectResponsesClient CreateResponseStreamingAsync" language:csharp "StreamingResponseOutputTextDeltaUpdate" language:csharp ``` This finds how other projects use these APIs, revealing patterns and edge cases. ### PowerShell Reflection (When Docs Lag Behind) Use when SDK docs are outdated or incomplete — the DLLs are the ground truth. Works even when `dotnet build` fails (loads from NuGet cache): ```powershell cd backend/WebApp.Api; dotnet restore # Option A: Load from build output (requires successful build) $asm = [Reflection.Assembly]::LoadFrom((Resolve-Path "bin/Debug/net10.0/Azure.AI.Projects.dll")) # Option B: Load from NuGet cache (works even if build fails — use for pre-release migrations) $dll = Get-ChildItem "$env:USERPROFILE\.nuget\packages\azure.ai.projects" -Recurse -Filter "Azure.AI.Projects.dll" | Select-Object -Last 1 $asm = [Reflection.Assembly]::LoadFrom($dll.FullName) # Find types matching a pattern $asm.GetExportedTypes() | Where-Object { $_.Name -like "*Streaming*" } | ForEach-Object { $_.FullName } # Get method signatures with parameter details $type = $asm.GetType("Azure.AI.Extensions.OpenAI.ProjectResponsesClient") $type.GetMethods() | Where-Object { $_.Name -like "*Async*" } | Select-Object Name, ReturnType, @{N='Params';E={($_.GetParameters() | ForEach-Object { "$($_.ParameterType.Name) $($_.Name)" }) -join ', '}} ``` **Agent Framework assemblies** (for Microsoft.Agents.AI.AzureAI migrations): ```powershell # Load Agent Framework DLL from NuGet cache $pkg = Get-ChildItem "$env:USERPROFILE\.nuget\packages\microsoft.agents.ai.azureai" -Recurse -Filter "Microsoft.Agents.AI.AzureAI.dll" | Select-Object -Last 1 $asm = [Reflection.Assembly]::LoadFrom($pkg.FullName) # Dump all exported types to see what changed between versions $asm.GetExportedTypes() | ForEach-Object { $_.FullName } | Sort-Object # Check if types you depend on still exist @("ChatClientAgent", "AgentVersion", "PromptAgentDefinition", "AgentReference") | ForEach-Object { $match = $asm.GetExportedTypes() | Where-Object { $_.Name -eq $_ } if ($match) { Write-Host "FOUND: $($match.FullName)" } else { Write-Host "MISSING: $_" -ForegroundColor Red } } # Inspect extension methods (GetAIAgentAsync, etc.) $asm.GetExportedTypes() | Where-Object { $_.GetMethods([Reflection.BindingFlags]::Static -bor [Reflection.BindingFlags]::Public) | Where-Object { $_.IsDefined([Runtime.CompilerServices.ExtensionAttribute], $false) } } | ForEach-Object { $_.GetMethods() | Where-Object { $_.IsDefined([Runtime.CompilerServices.ExtensionAttribute], $false) } | ForEach-Object { Write-Host "$($_.DeclaringType.Name).$($_.Name)" } } ``` **When to use**: SDK upgrade with breaking changes, pre-release packages where docs lag, verifying actual API surface before writing migration code. **Key insight**: Load from NuGet cache (`$env:USERPROFILE\.nuget\packages\`) to inspect the *new* version's types even when the build is broken.