Language-Specific Implementation Guides

Relevant source files

• .github/prompts/git-cherrypicking.prompt.md
• 00-course-setup/AzureSearch.cs
• 00-course-setup/AzureSearch.md
• 01-intro-to-ai-agents/code_samples/01-dotnet-agent-framework.cs
• 01-intro-to-ai-agents/code_samples/01-dotnet-agent-framework.md
• 01-intro-to-ai-agents/code_samples/01-python-agent-framework.ipynb
• 02-explore-agentic-frameworks/code_samples/02-dotnet-agent-framework.cs
• 02-explore-agentic-frameworks/code_samples/02-dotnet-agent-framework.md
• 03-agentic-design-patterns/code_samples/03-dotnet-agent-framework.cs
• 03-agentic-design-patterns/code_samples/03-dotnet-agent-framework.md
• 03-agentic-design-patterns/code_samples/03-python-agent-framework.ipynb
• 04-tool-use/code_samples/04-dotnet-agent-framework.cs
• 04-tool-use/code_samples/04-dotnet-agent-framework.md
• 04-tool-use/code_samples/04-python-agent-framework.ipynb
• 05-agentic-rag/code_samples/05-python-agent-framework.ipynb
• 07-planning-design/code_samples/07-python-agent-framework.ipynb
• 08-multi-agent/code_samples/08-python-agent-framework.ipynb
• 09-metacognition/code_samples/09-python-agent-framework.ipynb
• 13-agent-memory/13-agent-memory.ipynb
• global.json
• translations/en/01-intro-to-ai-agents/code_samples/01-python-agent-framework.ipynb
• translations/es/01-intro-to-ai-agents/code_samples/01-python-agent-framework.ipynb
• translations/es/03-agentic-design-patterns/code_samples/03-python-agent-framework.ipynb
• translations/es/04-tool-use/code_samples/04-python-agent-framework.ipynb
• translations/es/05-agentic-rag/code_samples/05-python-agent-framework.ipynb
• translations/es/07-planning-design/code_samples/07-python-agent-framework.ipynb
• translations/es/08-multi-agent/code_samples/08-python-agent-framework.ipynb
• translations/es/09-metacognition/code_samples/09-python-agent-framework.ipynb
• translations/fr/01-intro-to-ai-agents/code_samples/01-python-agent-framework.ipynb

Purpose and Scope

This page provides practical implementation guides for building AI agents in Python and .NET, the two primary languages supported in this course. Each language guide covers framework usage patterns, async programming models, plugin development, memory management, and Azure service integration specific to that language ecosystem.

For framework architecture details and selection criteria, see AI Agent Frameworks. For production deployment patterns independent of language choice, see Production Deployment.

---

Language Support Overview

The repository supports dual-language development with distinct framework ecosystems optimized for each language's strengths:

Language	Primary Frameworks	Typical Use Cases	Notebook Count
Python	Semantic Kernel, AutoGen, Azure AI Agent Service	Research, rapid prototyping, data science workflows, Jupyter-based development	~40+ notebooks
.NET	Microsoft Agent Framework, Semantic Kernel	Enterprise applications, production systems, strongly-typed workflows, integration with .NET ecosystems	~15+ notebooks

Both languages share common infrastructure components (Azure AI Search, Azure OpenAI, GitHub Models) but differ in API patterns, type systems, and concurrency models.

Sources: requirements.txt1-31 .env.example1-26

---

Cross-Language Architecture

The following diagram maps how language-specific SDKs interact with shared infrastructure, showing actual class names and package structures from the codebase:

Key Observations:

• Python dominates notebook count due to Jupyter ecosystem and data science focus
• .NET emphasizes workflow orchestration and enterprise patterns
• Authentication uses identical environment variables across languages (GITHUB_TOKEN, AZURE_OPENAI_API_KEY)
• Service clients (SearchClient, AsyncOpenAI) provide language-idiomatic APIs to same underlying services

Sources: requirements.txt1-31 02-semantic-kernel.ipynb27-42 02-autogen.ipynb27-37 14-human-loop.ipynb99-124 01-intro-to-ai-agents/code_samples/01-dotnet-agent-framework.cs67-76

---

Common Implementation Patterns

Environment Configuration Pattern

Both languages use .env files for configuration but load them differently:

Python Pattern:

.NET Pattern:

All samples consistently use these environment variables defined in .env.example1-26:

• GITHUB_TOKEN - GitHub Models authentication
• GITHUB_ENDPOINT - Base URL for inference API
• AZURE_OPENAI_* - Azure OpenAI service configuration
• AZURE_SEARCH_* - Azure AI Search endpoints
• PROJECT_ENDPOINT - Azure AI Foundry project endpoint

Sources: .env.example1-26 02-semantic-kernel.ipynb103-119 14-human-loop.ipynb126-133 01-intro-to-ai-agents/code_samples/01-dotnet-agent-framework.cs45-51

Async/Await Execution Pattern

Both languages use async patterns but with different syntax:

Python (async/await):

.NET (Task-based):

Both patterns enable streaming responses, cancellation, and concurrent operations, but .NET uses Task<T> while Python uses Coroutine[T].

Sources: 04-semantic-kernel-tool.ipynb186-292 14-human-loop.ipynb99-134 01-intro-to-ai-agents/code_samples/01-dotnet-agent-framework.cs82-86

---

Python-Specific Patterns

Package Import Structure

Python notebooks follow a consistent import pattern across all frameworks:

Framework Detection Pattern:

The choice of imports indicates which framework a notebook uses:

• Semantic Kernel: Imports semantic_kernel.agents.ChatCompletionAgent
• AutoGen: Imports autogen_agentchat.agents.AssistantAgent
• Azure AI Agent Service: Imports azure.ai.projects.AIProjectClient

Sources: 04-semantic-kernel-tool.ipynb18-37 02-autogen.ipynb27-37 02-azureaiagent.ipynb9-17

Plugin Development with @kernel_function

Semantic Kernel plugins use the @kernel_function decorator to expose Python functions as AI-callable tools:

Example from codebase:

The pattern in 04-semantic-kernel-tool.ipynb57-82 shows:

1. Define plugin class with descriptive docstring
2. Decorate methods with @kernel_function(description="...")
3. Use Annotated[ReturnType, "Description"] for type hints
4. Pass plugin instance to ChatCompletionAgent(plugins=[...])

The @kernel_function decorator:

• Automatically generates JSON schema for function calling
• Handles serialization/deserialization of parameters
• Provides metadata for LLM to understand tool purpose
• Enables automatic invocation during agent execution

Sources: 04-semantic-kernel-tool.ipynb57-82 05-semantic-kernel-azuresearch.ipynb94-155

Streaming Response Handling

Python notebooks consistently use async for to handle streaming responses with content type inspection:

Implementation Pattern:

04-semantic-kernel-tool.ipynb186-292 demonstrates the canonical streaming pattern:

1. Initialize buffers (full_response, function_calls, argument_buffer)
2. Iterate with async for response in agent.invoke_stream(...)
3. Inspect response.items for content type
4. Accumulate FunctionCallContent.arguments until complete
5. Display FunctionResultContent.result when received
6. Append StreamingTextContent.text to response buffer
7. Update thread = response.thread for conversation continuity

This pattern enables:

• Progressive rendering of LLM output
• Function call transparency (show tool invocations to user)
• Context preservation via thread management
• Error handling at granular content level

Sources: 04-semantic-kernel-tool.ipynb186-292 02-semantic-kernel.ipynb166-243 05-semantic-kernel-azuresearch.ipynb243-326

ChatHistoryAgentThread for Memory

Python Semantic Kernel uses ChatHistoryAgentThread for conversation state management:

The thread object:

• Stores full conversation history (user + assistant messages)
• Automatically passed to LLM on subsequent calls
• Returned by invoke_stream() for persistence
• Supports .delete() for cleanup

Sources: 04-semantic-kernel-tool.ipynb186-292 01-semantic-kernel.ipynb160-187

AutoGen Multi-Agent Pattern

AutoGen uses a different architecture focused on message-based agent communication:

Key Differences from Semantic Kernel:

Aspect	Semantic Kernel	AutoGen
Agent Creation	ChatCompletionAgent(service=..., plugins=...)	AssistantAgent(model_client=..., tools=...)
Message Format	String or ChatMessage	TextMessage(content=..., source=...)
Execution	invoke_stream(messages=...)	on_messages([messages], CancellationToken())
Response	Streaming with async for	Single response.chat_message.content
Memory	ChatHistoryAgentThread	Agent state managed internally

The AutoGen pattern emphasizes:

• Event-driven agent coordination
• Message passing between agents
• Multi-agent teamwork (not shown in basic sample)
• Cancellation tokens for workflow control

Sources: 02-autogen.ipynb54-156 05-autogen-chromadb.ipynb63-106

Azure AI Search Integration

Python samples demonstrate vector database integration using azure-search-documents:

Implementation in 05-semantic-kernel-azuresearch.ipynb167-217:

1. Index Schema Definition (lines 188-194):

   • SimpleField(name="id", type=SearchFieldDataType.String, key=True)
   • SearchableField(name="content", type=SearchFieldDataType.String)

2. Client Initialization (lines 177-186):

3. Document Upload (line 216):

4. Retrieval in Plugin (lines 115-124):

This pattern enables:

• Persistent document storage (survives notebook restarts)
• Semantic search over unstructured data
• Context augmentation for RAG patterns
• Scalable retrieval using Azure infrastructure

Sources: 05-semantic-kernel-azuresearch.ipynb167-217 13-agent-memory.ipynb154-191

Memory Systems: Mem0 + Azure AI Search

Advanced Python samples combine mem0ai with Azure AI Search for persistent agent memory:

Configuration Pattern from 13-agent-memory.ipynb154-191:

Memory Types Tracked:

• Short-term: Current conversation context
• Long-term: User preferences across sessions
• Episodic: Past interactions and events
• Entity: Facts about people, places, things
• Persona: User characteristics and style

Sources: 13-agent-memory.ipynb154-191

---

.NET-Specific Patterns

Microsoft Agent Framework Architecture

The .NET ecosystem centers on the Microsoft.Agents.AI and Microsoft.Extensions.AI packages with strong typing and workflow orchestration:

Fundamental Pattern from 01-intro-to-ai-agents/code_samples/01-dotnet-agent-framework.cs67-76:

Sources: 01-intro-to-ai-agents/code_samples/01-dotnet-agent-framework.cs67-76 02-explore-agentic-frameworks/code_samples/02-dotnet-agent-framework.cs93-100

Tool Definition with [Description]

.NET samples define tools using static methods decorated with [Description] attributes, which the AIFunctionFactory uses to generate function schemas:

Key aspects:

• [Description] attribute on the method provides the tool's overall purpose to the LLM.
• [Description] attribute on parameters provides details for each argument, enabling the LLM to correctly extract values.
• AIFunctionFactory.Create(MethodName) registers the method as a callable tool for the AIAgent.

Sources: 01-intro-to-ai-agents/code_samples/01-dotnet-agent-framework.cs19-43 03-agentic-design-patterns/code_samples/03-dotnet-agent-framework.cs26-58

Conversation Session Management

The .NET AIAgent uses AgentSession to maintain conversation context across multiple turns:

The AgentSession object:

• Stores the history of messages exchanged within a conversation.
• Ensures the agent remembers previous interactions and maintains conversational state.
• Is passed to RunStreamingAsync to continue the conversation contextually.

Sources: 03-agentic-design-patterns/code_samples/03-dotnet-agent-framework.cs131 02-explore-agentic-frameworks/code_samples/02-dotnet-agent-framework.cs106

---

Framework-Specific Integration Patterns

GitHub Models Client Configuration

Both languages use identical GitHub Models authentication but with different client libraries:

Python (Semantic Kernel):

Python (AutoGen):

.NET (Microsoft Agent Framework):

All three patterns:

• Use GITHUB_TOKEN from environment
• Point to https://models.inference.ai.azure.com
• Support same model IDs (gpt-4o-mini, gpt-4o)
• Enable function calling capabilities

Sources: 02-semantic-kernel.ipynb103-119 02-autogen.ipynb54-76 01-intro-to-ai-agents/code_samples/01-dotnet-agent-framework.cs54-63

Azure OpenAI Client Configuration

For production deployments, samples use Azure OpenAI Service:

Python (Azure AI Search + OpenAI):

Python (Azure AI Agent Service):

Environment Variables Required:

• AZURE_OPENAI_ENDPOINT - Azure OpenAI resource endpoint
• AZURE_OPENAI_API_KEY - API key (or use DefaultAzureCredential)
• AZURE_OPENAI_CHAT_DEPLOYMENT_NAME - Deployment name (e.g., "gpt-4o")
• AZURE_OPENAI_API_VERSION - API version (e.g., "2024-02-15-preview")
• PROJECT_ENDPOINT - Azure AI Foundry project endpoint (for Agent Service)

Sources: 13-agent-memory.ipynb119-142 02-azureaiagent.ipynb21-34

---

Code Organization Patterns

Notebook Structure

All language implementations follow consistent notebook organization:

Standard Sections:

1. Title Cell - Markdown with lesson number and framework name
2. Import Section - All package imports with comments
3. Client Configuration - Model endpoint setup (GitHub Models or Azure OpenAI)
4. Plugin/Tool Definition - @kernel_function or [Description] decorated functions
5. Agent Creation - Framework-specific agent instantiation
6. Execution Loop - async def main() or await foreach with streaming response handling
7. Output Examples - Expected results in markdown

This structure ensures:

• Reproducibility - Clear setup steps
• Learning progression - Build complexity gradually
• Self-contained examples - Each notebook runs independently
• Consistent patterns - Easy to compare frameworks

Sources: 04-semantic-kernel-tool.ipynb1-50 02-autogen.ipynb1-50 01-intro-to-ai-agents/code_samples/01-dotnet-agent-framework.cs1-10

Display Utilities for Notebooks

Python notebooks use IPython.display for rich HTML formatting:

Common Styling Patterns:

• Blue (#e3f2fd) - Tool invocations
• Green (#c8e6c9) - Successful checks
• Red (#ffcdd2) - Errors
• Orange/Yellow (gradient) - Priority/special status

This provides:

• Visual workflow tracking - See execution flow in real-time
• Debugging aid - Identify where errors occur
• Educational clarity - Highlight important concepts
• Professional appearance - Polished notebook output

Sources: 14-conditional-workflow.ipynb138-162 14-human-loop.ipynb254-260 14-middleware.ipynb189-254

---

Language Selection Guidance

Decision Factor	Choose Python	Choose .NET
Primary Use Case	Research, data science, rapid prototyping, Jupyter workflows	Enterprise applications, production systems, business process automation
Framework Preference	Semantic Kernel, AutoGen, Azure AI Agent Service	Microsoft Agent Framework, Semantic Kernel (.NET)
Type Safety Needs	Dynamic typing acceptable, prefer flexibility	Strong typing required, compile-time validation
Existing Codebase	Python/Flask/Django/FastAPI	ASP.NET/Blazor/.NET MAUI
Team Expertise	Data scientists, ML engineers	Enterprise developers, .NET architects
Development Speed	Fastest iteration (REPL, notebooks)	Slower initial setup, faster debugging
Workflow Complexity	Simple to moderate agent chains	Complex multi-step business processes with HITL
Deployment Target	Cloud functions, notebooks, APIs	Azure App Service, Kubernetes, Windows services
Observability Needs	Built-in with Langfuse/OpenLit	Built-in with OpenTelemetry + Azure Monitor

Recommendation:

• Start with Python for learning and prototyping (60+ notebooks available)
• Migrate to .NET for production if you need workflow orchestration, middleware, or enterprise integration
• Use both - Python for data processing/RAG, .NET for workflow coordination

Sources: requirements.txt1-31 14-conditional-workflow.ipynb1-400 02-semantic-kernel.ipynb1-267

---

Common Pitfalls and Solutions

Python-Specific Issues

Issue: Streaming Response Buffer Management

Sources: 04-semantic-kernel-tool.ipynb207-260

Issue: Thread Memory Not Persisting

Sources: 04-semantic-kernel-tool.ipynb186-292

.NET-Specific Issues

Issue: Missing AgentSession for Context

Sources: 03-agentic-design-patterns/code_samples/03-dotnet-agent-framework.cs131 02-explore-agentic-frameworks/code_samples/02-dotnet-agent-framework.cs106

Issue: Incorrect Tool Definition

Sources: 01-intro-to-ai-agents/code_samples/01-dotnet-agent-framework.cs19

---

Performance Considerations

Async Execution Best Practices

Both languages benefit from proper async patterns:

Python:

• Use async for for streaming responses (avoid blocking)
• Gather concurrent operations with asyncio.gather()
• Don't mix sync/async code (causes thread blocking)
• Use nest_asyncio if running in Jupyter with existing event loop

Example from 05-autogen-chromadb.ipynb22:

.NET:

• Use await foreach for streaming
• Avoid Task.Wait() or Task.Result (causes deadlocks)
• Use ConfigureAwait(false) in library code
• Leverage IAsyncEnumerable<T> for streaming

Sources: 05-autogen-chromadb.ipynb22 01-intro-to-ai-agents/code_samples/01-dotnet-agent-framework.cs82-86

Memory Management

Python:

• Explicitly delete threads: await thread.delete() if thread else None
• Clear large context buffers between user inputs
• Use gc.collect() for long-running notebook sessions

Example from 01-semantic-kernel.ipynb184-186:

.NET:

• Dispose AgentSession objects when no longer needed using await using var session = ...
• Limit conversation history size for long sessions by managing the AgentSession content.

Sources: 01-semantic-kernel.ipynb184-186 03-agentic-design-patterns/code_samples/03-dotnet-agent-framework.cs131

---

Summary

This guide has covered language-specific patterns for implementing AI agents in Python and .NET, including:

Python Ecosystem:

• Semantic Kernel with @kernel_function plugins and ChatHistoryAgentThread
• AutoGen with event-driven AssistantAgent and message passing
• Azure AI Agent Service with AIProjectClient for managed deployments
• Azure AI Search integration for RAG patterns
• Mem0 for persistent agent memory

.NET Ecosystem:

• Microsoft Agent Framework with AIAgent for core agent functionality
• [Description] attributes for tool definition
• AgentSession for conversation context management
• Streaming responses with await foreach

Both languages share:

• GitHub Models and Azure OpenAI authentication
• Azure AI Search for vector storage
• OpenTelemetry for observability
• Consistent environment variable patterns

For detailed framework comparisons, see AI Agent Frameworks. For production deployment strategies, see Production Deployment. For specific implementation examples in your chosen language, see Python Development Guide or .NET Development Guide.