Building AI Agents with C# and .NET 10
A Developer’s First Guide to the Microsoft Agent Framework
Front Matter
- Preface
- Introduction
- About the Author
Part I — Foundations
- The AI Revolution in .NET
- From software you write to software you delegate to
- What makes software agentic: the agent loop
- Agents, workflows, and plain LLM calls
- Where .NET sits in the AI world
- How Semantic Kernel and AutoGen became the Microsoft Agent Framework
- Where agents fit in your career
- Three things that change when the model joins your stack
- Agents act — and that changes the risk picture
- What you’ll build in this book
- A first glimpse of the code
- A word on how this book treats you
- When not to reach for an agent
- Summary
- Key Terms
- Practice Exercises
- What’s Next
- C# Essentials for AI Development
- Async, Task, and CancellationToken
- Records, primary constructors, and required members
- Raw string literals
- Pattern matching for LLM response dispatch
- Collection expressions, nullable references, and extension methods
- JSON serialization with System.Text.Json
- Dependency injection and Minimal API
- What this earns you in the rest of the book
- Summary
- Key Terms
- Practice Exercises
- What’s Next
- How LLMs Work: A Developer’s Mental Model
- Tokens — the atom of the LLM world
- The conversation is a list of messages
- Next-token prediction — the mechanism
- Temperature and top-p — controlling randomness
- Prompting techniques — just enough for Chapter 5
- Embeddings and cosine similarity
- Token economics — what this costs
- Summary
- Key Terms
- Practice Exercises
- What’s Next
- Setting Up Your Dev Environment
- Install the SDK and IDE
- Pick a provider
- Provisioning
- Configure appsettings.json
- Your first LLM call
- Your first streaming response
- When the first call fails
- Summary
- Practice Exercises
- What’s Next
Part II — Your First Agents
- Hello, Agent!
- What a ChatClientAgent actually is
- Three ways to create an agent
- Sessions are optional
- Non-streaming: RunAsync
- Overriding options per call
- When the call fails
- Streaming: RunStreamingAsync
- Exposing the agent over HTTP
- Putting it together — the mental model
- Summary
- Key Terms
- Practice Exercises
- What’s Next
- Conversations and Memory
- The amnesia problem
- Sessions and history providers
- Where does the conversation actually live?
- Persisting sessions across restarts
- Context providers
- Keeping history under the window
- Short-term vs long-term memory
- Putting it all together
- Summary
- Key Terms
- Practice Exercises
- What’s Next
- Structured Output and Typed Responses
- Why typed responses matter
- Your first typed call
- Records, JSON attributes, schemas
- Enums as structured validators
- Not every agent supports structured output
- The other door: ResponseFormat
- Typed output while streaming
- Tightening the schema (strict mode)
- A production-grade typed call
- Validating the extraction
- When typed responses fail
- The cost of a schema
- Structured output under trimming and AOT
- Polymorphic and discriminated-union responses
- When to reach for typed responses
- Summary
- Key Terms
- Practice Exercises
- What’s Next
Part III — Giving Agents Superpowers
- Tools and Function Calling
- The tool landscape
- The tool-calling loop
- Your first tool
- Multiple tools and chaining
- Inside the loop — FunctionInvokingChatClient and its limits
- Controlling tool choice
- The shell tool — the most dangerous tool you’ll build
- Tools backed by dependency injection
- Concurrent tool calls
- Graceful degradation
- Tool approval — keeping a human in the loop
- Giving an agent its own files: FileAccessProvider
- Testing your tools
- Tool design principles
- Integrating with Chapter 7 — typed tools
- Putting it together — the agent grows up
- Summary
- Key Terms
- Practice Exercises
- What’s Next
- The Model Context Protocol
- What MCP is (and isn't)
- Building an MCP server in C#
- MCP transports — stdio, SSE, HTTP
- Consuming an MCP server from an agent
- The capability-negotiation handshake
- Cross-language interop
- A second MCP server — knowledge base preview
- When to use MCP (and when not to)
- Debugging an MCP server
- Summary
- Key Terms
- Practice Exercises
- What’s Next
- Introduction to RAG
- What RAG is
- Embeddings, revisited in code
- The RAG pipeline
- Chunking strategies
- The Contoso FAQ agent — wiring RAG into an agent
- One provider, two modes: always-on vs on-demand
- Metadata filtering
- RAG-specific security
- The cost of getting RAG wrong
- Evaluating RAG quality
- Hosted RAG — when MAF does the heavy lifting
- When RAG is the wrong tool
- Summary
- Key Terms
- Practice Exercises
- What’s Next
- Multimodal Agents
- The same agent, a richer message
- Two ways to send an image: URL and bytes
- Choosing a vision model
- From a picture to a typed C# record
- An image is not free
- An image is untrusted input
- Multimodal RAG, honestly
- Audio: two real paths
- Video: sample the frames
- Testing multimodal agents without a model
- Summary
- Key Terms
- Practice Exercises
- What’s Next
Part IV — Multi-Agent Collaboration
- Multi-Agent Systems
- When to reach for multi-agent
- Sequential pipeline — the simplest case
- The orchestrator-and-specialists pattern
- Agents-as-tools — the mental model
- Content pipeline — Researcher → Writer → Editor
- The built-in orchestrations
- Streaming through a pipeline
- Every inter-agent boundary is a trust boundary
- Testing multi-agent compositions
- The pattern catalog
- BuildSequential vs manual chaining
- Observability, cost, and failure modes
- Mixing models, and the growing context
- Design principles for multi-agent
- When NOT to go multi-agent
- Summary
- Key Terms
- Practice Exercises
- What’s Next
- Introduction to Workflows
- Why workflows
- The primitives
- Sequential workflow
- Conditional edges — branching on data
- Agents as workflow executors
- Approval workflow — human-in-the-loop with a revision loop
- Checkpointing and durable resume
- State isolation — fresh instance per run
- Idiomatic fan-out and fan-in
- Sub-workflows and workflows-as-agents
- Visualizing a workflow
- Testing workflows
- The workflow event stream
- Workflows vs multi-agent — when to pick which
- Design principles
- When workflows are the wrong tool
- Summary
- Key Terms
- Practice Exercises
- What’s Next
Part V — Going to Production
- Hosting and Deployment
- Why hosting matters
- AddAIAgent() — the hosting extension
- Streaming from a hosted agent
- .NET Aspire — orchestration and observability in one
- The A2A protocol — agent discovery and invocation over HTTP
- Securing the agent API
- Rate limiting and resilience
- Deployment considerations
- Containerizing the agent service
- Deploying to the cloud
- A fully-hosted Contoso FAQ agent
- Summary
- Key Terms
- Practice Exercises
- What’s Next
- Observability and Debugging
- The three pillars
- OpenTelemetry — the .NET story
- The GenAI semantic conventions
- Structured logging with ILogger
- Custom metrics
- Custom traces with ActivitySource
- Running it
- Exporting to production
- Dashboards worth building
- When observability fails you
- Evaluation: the fourth signal
- Debugging an agent in production
- Summary
- Key Terms
- Practice Exercises
- What’s Next
- Safety and Guardrails
- The Quality Pyramid
- A threat model to anchor the layers — OWASP LLM Top 10
- Middleware — DelegatingChatClient and .Use()
- Input sanitization — prompt injection and PII
- The critic-agent pattern
- Injecting safety context mid-run — the AIContextProvider hook
- Indirect prompt injection — when the attack hides in the data
- Excessive Agency — gating the tools that can act
- Improper Output Handling — the answer is untrusted input
- Unbounded Consumption — denial-of-wallet and runaway loops
- Graduating from regex — Azure AI Content Safety
- Closing the loop — logging hygiene and retention
- Combining the layers
- Design principles for safety
- When safety fails
- Summary
- Key Terms
- Practice Exercises
- What’s Next
- Agent Skills
- What a Skill is, and what it is not
- Progressive disclosure — the four stages
- Providing skills to an agent — the AgentSkillsProvider
- Code-defined skills — AgentInlineSkill
- Class-based skills — AgentClassSkill<T>
- Mixing skill sources — AgentSkillsProviderBuilder
- Watching progressive disclosure run
- Gating scripts with human approval
- Customising the system prompt
- Dependency injection through skills
- Security — treating skills like dependencies
- Skills vs. workflows — when to pick which
- Summary
- Key Terms
- Practice Exercises
- What’s Next
- Evaluation
- Why eval is the blind spot of agent dev
- The three core types
- LocalEvaluator and the built-in EvalChecks
- Custom checks with FunctionEvaluator.Create
- EvaluateAsync — running queries against an evaluator
- FoundryEvals — cloud-based LLM-as-judge scoring
- Conversation split strategies
- Mixing local and cloud evaluators in one pass
- Evaluating workflows — Run.EvaluateAsync and per-agent breakdown
- Evaluating a RAG agent: grounding the Contoso FAQ agent
- The judge client: ChatConfiguration
- Safety evaluation
- Eval-driven development
- Composing with Microsoft.Extensions.AI.Evaluation
- Wiring eval into CI
- Summary
- Key Terms
- Practice Exercises
- What’s Next
- Your Next Steps
- What to build next
- The agentic protocol triad: A2A and AG-UI
- Enterprise governance patterns
- Contributing to MAF
- Where the ecosystem is heading
- Staying current
- A short send-off
- Summary
- Key Terms
- What’s Next After This Book
Appendices
- Appendix A — NuGet Package Reference
- Appendix B — Semantic Kernel to MAF Migration Map
- Appendix C — AutoGen to MAF Migration Map
- Appendix D — Glossary
- Appendix E — Exercise Solutions Reference
- Keyword Index
Building AI Agents with C# and .NET 10
A Developer’s First Guide to the Microsoft Agent Framework
Front Matter
- Preface
- Introduction
- About the Author
Part I — Foundations
- The AI Revolution in .NET
- From software you write to software you delegate to
- What makes software agentic: the agent loop
- Agents, workflows, and plain LLM calls
- Where .NET sits in the AI world
- How Semantic Kernel and AutoGen became the Microsoft Agent Framework
- Where agents fit in your career
- Three things that change when the model joins your stack
- Agents act — and that changes the risk picture
- What you’ll build in this book
- A first glimpse of the code
- A word on how this book treats you
- When not to reach for an agent
- Summary
- Key Terms
- Practice Exercises
- What’s Next
- C# Essentials for AI Development
- Async, Task, and CancellationToken
- Records, primary constructors, and required members
- Raw string literals
- Pattern matching for LLM response dispatch
- Collection expressions, nullable references, and extension methods
- JSON serialization with System.Text.Json
- Dependency injection and Minimal API
- What this earns you in the rest of the book
- Summary
- Key Terms
- Practice Exercises
- What’s Next
- How LLMs Work: A Developer’s Mental Model
- Tokens — the atom of the LLM world
- The conversation is a list of messages
- Next-token prediction — the mechanism
- Temperature and top-p — controlling randomness
- Prompting techniques — just enough for Chapter 5
- Embeddings and cosine similarity
- Token economics — what this costs
- Summary
- Key Terms
- Practice Exercises
- What’s Next
- Setting Up Your Dev Environment
- Install the SDK and IDE
- Pick a provider
- Provisioning
- Configure appsettings.json
- Your first LLM call
- Your first streaming response
- When the first call fails
- Summary
- Practice Exercises
- What’s Next
Part II — Your First Agents
- Hello, Agent!
- What a ChatClientAgent actually is
- Three ways to create an agent
- Sessions are optional
- Non-streaming: RunAsync
- Overriding options per call
- When the call fails
- Streaming: RunStreamingAsync
- Exposing the agent over HTTP
- Putting it together — the mental model
- Summary
- Key Terms
- Practice Exercises
- What’s Next
- Conversations and Memory
- The amnesia problem
- Sessions and history providers
- Where does the conversation actually live?
- Persisting sessions across restarts
- Context providers
- Keeping history under the window
- Short-term vs long-term memory
- Putting it all together
- Summary
- Key Terms
- Practice Exercises
- What’s Next
- Structured Output and Typed Responses
- Why typed responses matter
- Your first typed call
- Records, JSON attributes, schemas
- Enums as structured validators
- Not every agent supports structured output
- The other door: ResponseFormat
- Typed output while streaming
- Tightening the schema (strict mode)
- A production-grade typed call
- Validating the extraction
- When typed responses fail
- The cost of a schema
- Structured output under trimming and AOT
- Polymorphic and discriminated-union responses
- When to reach for typed responses
- Summary
- Key Terms
- Practice Exercises
- What’s Next
Part III — Giving Agents Superpowers
- Tools and Function Calling
- The tool landscape
- The tool-calling loop
- Your first tool
- Multiple tools and chaining
- Inside the loop — FunctionInvokingChatClient and its limits
- Controlling tool choice
- The shell tool — the most dangerous tool you’ll build
- Tools backed by dependency injection
- Concurrent tool calls
- Graceful degradation
- Tool approval — keeping a human in the loop
- Giving an agent its own files: FileAccessProvider
- Testing your tools
- Tool design principles
- Integrating with Chapter 7 — typed tools
- Putting it together — the agent grows up
- Summary
- Key Terms
- Practice Exercises
- What’s Next
- The Model Context Protocol
- What MCP is (and isn't)
- Building an MCP server in C#
- MCP transports — stdio, SSE, HTTP
- Consuming an MCP server from an agent
- The capability-negotiation handshake
- Cross-language interop
- A second MCP server — knowledge base preview
- When to use MCP (and when not to)
- Debugging an MCP server
- Summary
- Key Terms
- Practice Exercises
- What’s Next
- Introduction to RAG
- What RAG is
- Embeddings, revisited in code
- The RAG pipeline
- Chunking strategies
- The Contoso FAQ agent — wiring RAG into an agent
- One provider, two modes: always-on vs on-demand
- Metadata filtering
- RAG-specific security
- The cost of getting RAG wrong
- Evaluating RAG quality
- Hosted RAG — when MAF does the heavy lifting
- When RAG is the wrong tool
- Summary
- Key Terms
- Practice Exercises
- What’s Next
- Multimodal Agents
- The same agent, a richer message
- Two ways to send an image: URL and bytes
- Choosing a vision model
- From a picture to a typed C# record
- An image is not free
- An image is untrusted input
- Multimodal RAG, honestly
- Audio: two real paths
- Video: sample the frames
- Testing multimodal agents without a model
- Summary
- Key Terms
- Practice Exercises
- What’s Next
Part IV — Multi-Agent Collaboration
- Multi-Agent Systems
- When to reach for multi-agent
- Sequential pipeline — the simplest case
- The orchestrator-and-specialists pattern
- Agents-as-tools — the mental model
- Content pipeline — Researcher → Writer → Editor
- The built-in orchestrations
- Streaming through a pipeline
- Every inter-agent boundary is a trust boundary
- Testing multi-agent compositions
- The pattern catalog
- BuildSequential vs manual chaining
- Observability, cost, and failure modes
- Mixing models, and the growing context
- Design principles for multi-agent
- When NOT to go multi-agent
- Summary
- Key Terms
- Practice Exercises
- What’s Next
- Introduction to Workflows
- Why workflows
- The primitives
- Sequential workflow
- Conditional edges — branching on data
- Agents as workflow executors
- Approval workflow — human-in-the-loop with a revision loop
- Checkpointing and durable resume
- State isolation — fresh instance per run
- Idiomatic fan-out and fan-in
- Sub-workflows and workflows-as-agents
- Visualizing a workflow
- Testing workflows
- The workflow event stream
- Workflows vs multi-agent — when to pick which
- Design principles
- When workflows are the wrong tool
- Summary
- Key Terms
- Practice Exercises
- What’s Next
Part V — Going to Production
- Hosting and Deployment
- Why hosting matters
- AddAIAgent() — the hosting extension
- Streaming from a hosted agent
- .NET Aspire — orchestration and observability in one
- The A2A protocol — agent discovery and invocation over HTTP
- Securing the agent API
- Rate limiting and resilience
- Deployment considerations
- Containerizing the agent service
- Deploying to the cloud
- A fully-hosted Contoso FAQ agent
- Summary
- Key Terms
- Practice Exercises
- What’s Next
- Observability and Debugging
- The three pillars
- OpenTelemetry — the .NET story
- The GenAI semantic conventions
- Structured logging with ILogger
- Custom metrics
- Custom traces with ActivitySource
- Running it
- Exporting to production
- Dashboards worth building
- When observability fails you
- Evaluation: the fourth signal
- Debugging an agent in production
- Summary
- Key Terms
- Practice Exercises
- What’s Next
- Safety and Guardrails
- The Quality Pyramid
- A threat model to anchor the layers — OWASP LLM Top 10
- Middleware — DelegatingChatClient and .Use()
- Input sanitization — prompt injection and PII
- The critic-agent pattern
- Injecting safety context mid-run — the AIContextProvider hook
- Indirect prompt injection — when the attack hides in the data
- Excessive Agency — gating the tools that can act
- Improper Output Handling — the answer is untrusted input
- Unbounded Consumption — denial-of-wallet and runaway loops
- Graduating from regex — Azure AI Content Safety
- Closing the loop — logging hygiene and retention
- Combining the layers
- Design principles for safety
- When safety fails
- Summary
- Key Terms
- Practice Exercises
- What’s Next
- Agent Skills
- What a Skill is, and what it is not
- Progressive disclosure — the four stages
- Providing skills to an agent — the AgentSkillsProvider
- Code-defined skills — AgentInlineSkill
- Class-based skills — AgentClassSkill<T>
- Mixing skill sources — AgentSkillsProviderBuilder
- Watching progressive disclosure run
- Gating scripts with human approval
- Customising the system prompt
- Dependency injection through skills
- Security — treating skills like dependencies
- Skills vs. workflows — when to pick which
- Summary
- Key Terms
- Practice Exercises
- What’s Next
- Evaluation
- Why eval is the blind spot of agent dev
- The three core types
- LocalEvaluator and the built-in EvalChecks
- Custom checks with FunctionEvaluator.Create
- EvaluateAsync — running queries against an evaluator
- FoundryEvals — cloud-based LLM-as-judge scoring
- Conversation split strategies
- Mixing local and cloud evaluators in one pass
- Evaluating workflows — Run.EvaluateAsync and per-agent breakdown
- Evaluating a RAG agent: grounding the Contoso FAQ agent
- The judge client: ChatConfiguration
- Safety evaluation
- Eval-driven development
- Composing with Microsoft.Extensions.AI.Evaluation
- Wiring eval into CI
- Summary
- Key Terms
- Practice Exercises
- What’s Next
- Your Next Steps
- What to build next
- The agentic protocol triad: A2A and AG-UI
- Enterprise governance patterns
- Contributing to MAF
- Where the ecosystem is heading
- Staying current
- A short send-off
- Summary
- Key Terms
- What’s Next After This Book
Appendices
- Appendix A — NuGet Package Reference
- Appendix B — Semantic Kernel to MAF Migration Map
- Appendix C — AutoGen to MAF Migration Map
- Appendix D — Glossary
- Appendix E — Exercise Solutions Reference
- Keyword Index