1. Mục tiêu
Trong bài đầu tiên của chuỗi tìm hiểu Microsoft Agent Framework (MAF), chúng ta sẽ tìm hiểu những khái niệm nền tảng về AI Agent và xây dựng một Agent đơn giản bằng C#.
Thay vì sử dụng Microsoft Foundry làm model provider, bài thực hành này sử dụng Google Gemini Developer API. Cách tiếp cận này giúp chúng ta tập trung tìm hiểu cách MAF xây dựng và vận hành Agent mà không cần thiết lập Azure subscription hoặc Foundry Project.
Sau bài học, bạn sẽ:
- Phân biệt LLM, Chatbot và AI Agent.
- Hiểu vai trò của Microsoft Agent Framework.
- Hiểu mối quan hệ giữa Agent Framework và model provider.
- Tạo Console Application bằng C# trên .NET 10.
- Kết nối ứng dụng với Google Gemini API.
- Tạo Agent, thiết lập Instructions và thực hiện hội thoại nhiều lượt với AgentSession.
2. Môi trường phát triển
Các công cụ sử dụng trong bài:
| Thành phần | Phiên bản / Công nghệ |
|---|---|
| IDE | Visual Studio 2026 |
| Framework | .NET 10 |
| Ngôn ngữ | C# 14 |
| Agent Framework | Microsoft Agent Framework |
| LLM Provider | Google Gemini Developer API |
| Model | Gemini 3.8 Flash |
| Package Manager | NuGet |
Lưu ý: Để phát triển ứng dụng .NET 10, cần Visual Studio 2026 phiên bản 18.0 trở lên.
3. LLM, Chatbot và AI Agent khác nhau như thế nào?
Trước khi tìm hiểu MAF, chúng ta cần phân biệt ba khái niệm thường gặp.
3.1. LLM (Large Language Model)
LLM là mô hình ngôn ngữ lớn được huấn luyện trên lượng dữ liệu lớn để hiểu và tạo ra nội dung bằng ngôn ngữ tự nhiên.
Một số ví dụ:
- Google Gemini
- OpenAI GPT
- Anthropic Claude
- Meta Llama
LLM có thể trả lời câu hỏi, tóm tắt tài liệu, viết nội dung và hỗ trợ lập trình.
Tuy nhiên, bản thân LLM không tự động có quyền truy cập database, gọi API hoặc thực hiện các thao tác trong hệ thống của chúng ta.
3.2. Chatbot
Chatbot là ứng dụng cho phép người dùng tương tác với hệ thống thông qua hội thoại.
Một chatbot đơn giản thường có luồng xử lý:
Chatbot có thể lưu lịch sử hội thoại để hiểu ngữ cảnh, nhưng không có nghĩa là nó có khả năng tự lập kế hoạch hoặc sử dụng công cụ.
3.3. AI Agent
AI Agent là hệ thống sử dụng mô hình AI để xử lý mục tiêu, lựa chọn hành động và phối hợp với các công cụ nhằm hoàn thành nhiệm vụ.
Ví dụ, người dùng yêu cầu:
Kiểm tra tình trạng đơn hàng ORD-001 và cho tôi biết đơn hàng có được giao hôm nay không.
Một Agent có thể thực hiện các bước:
- Hiểu yêu cầu của người dùng.
- Xác định cần kiểm tra thông tin đơn hàng.
- Gọi công cụ tra cứu đơn hàng.
- Đọc kết quả trả về.
- Phân tích trạng thái giao hàng.
- Trả lời người dùng.
Điểm khác biệt quan trọng là Agent có thể phối hợp với công cụ để thực hiện nhiệm vụ, thay vì chỉ tạo ra câu trả lời bằng văn bản.
4. Microsoft Agent Framework là gì?
Microsoft Agent Framework (MAF) là framework mã nguồn mở của Microsoft giúp xây dựng và điều phối AI Agent bằng .NET và Python.
Framework cung cấp các thành phần để xây dựng ứng dụng Agent, chẳng hạn:
- Agents: Định nghĩa và vận hành Agent.
- Instructions: Hướng dẫn hành vi của Agent.
- Tools: Cho phép Agent sử dụng các chức năng bên ngoài.
- Sessions: Quản lý ngữ cảnh hội thoại.
- Middleware: Can thiệp vào quá trình thực thi.
- Workflows: Xây dựng quy trình phối hợp nhiều bước hoặc nhiều Agent.
4.1. Mối quan hệ giữa MAF và LLM
Một điểm cần hiểu rõ: MAF không phải là một LLM.
MAF cung cấp cơ chế xây dựng Agent, còn LLM là model provider đảm nhiệm việc suy luận và tạo nội dung.
MAF hỗ trợ nhiều model provider. Vì vậy, chúng ta có thể sử dụng Gemini, OpenAI, Azure OpenAI, Microsoft Foundry hoặc những dịch vụ khác có triển khai IChatClient tương thích.
Trong bài này, chúng ta chọn Google Gemini Developer API.
4.2. Mối quan hệ giữa MAF, Semantic Kernel và AutoGen
Nếu đã từng tìm hiểu Semantic Kernel hoặc AutoGen, bạn có thể nhận thấy chúng đều liên quan đến việc xây dựng ứng dụng AI.
- Semantic Kernel: SDK giúp tích hợp AI vào ứng dụng, kết nối model với plugins, functions và các thành phần nghiệp vụ.
- AutoGen: Framework tập trung vào việc xây dựng ứng dụng hội thoại và phối hợp giữa nhiều Agent.
- Microsoft Agent Framework: Kết hợp các ý tưởng và kinh nghiệm từ những framework trước đó, cung cấp mô hình xây dựng Agent và Workflows thống nhất.
Có thể xem MAF là hướng phát triển tiếp theo trong hệ sinh thái Agent của Microsoft, thay vì coi đây chỉ là một thư viện gọi LLM.
5. Chuẩn bị Google Gemini API
Chúng ta cần một API key để ứng dụng C# có thể gửi yêu cầu đến Gemini.
5.1. Tạo API key
Truy cập Google AI Studio.
Đăng nhập bằng tài khoản Google và tạo API key trong phần quản lý API key.
Sau khi có API key, hãy lưu lại để sử dụng trong ứng dụng.
Lưu ý: Không nên đưa API key trực tiếp vào source code hoặc commit lên Git repository.
5.2. Cấu hình biến môi trường
Mở PowerShell và chạy:
$env:GOOGLE_GENAI_API_KEY="YOUR_GOOGLE_API_KEY"
$env:GOOGLE_GENAI_MODEL="gemini-3.8-flash"
Hai biến môi trường có ý nghĩa:
| Biến | Ý nghĩa |
|---|---|
GOOGLE_GENAI_API_KEY |
API key dùng để xác thực với Gemini |
GOOGLE_GENAI_MODEL |
Tên model Gemini muốn sử dụng |
Lưu ý: Cách cấu hình trên chỉ có hiệu lực trong phiên PowerShell hiện tại. Nếu mở một terminal mới, bạn cần thiết lập lại biến môi trường.
6. Tạo ứng dụng đầu tiên với Microsoft Agent Framework
6.1. Tạo Console Application
Mở Visual Studio 2026.
Chọn:
- Create a new project.
- Chọn Console App.
- Đặt tên project:
MafGeminiDemo. - Chọn Framework: .NET 10.0.
- Tạo project.
Cấu trúc ban đầu:
MafGeminiDemo/
├── MafGeminiDemo.csproj
└── Program.cs
6.2. Cài đặt NuGet packages
Mở Terminal tại thư mục project và chạy:
dotnet add package Google.GenAI
dotnet add package Microsoft.Agents.AI
Vai trò của hai package:
| Package | Vai trò |
|---|---|
Google.GenAI |
Google GenAI SDK, cung cấp khả năng kết nối Gemini API |
Microsoft.Agents.AI |
Các thành phần cốt lõi để xây dựng Agent |
Nếu muốn kiểm tra phiên bản package đã cài đặt:
dotnet list package --include-transitive
Không nên tự ý cố định phiên bản package cũ khi bắt đầu một project mới. Hãy kiểm tra phiên bản thực tế được NuGet restore và các yêu cầu tương thích của package.
6.3. Tạo Agent đầu tiên
Mở file Program.cs và thay thế nội dung bằng đoạn code sau:
using Google.GenAI;
using Microsoft.Agents.AI;
using Microsoft.Extensions.AI;
using Microsoft.Extensions.Configuration;
var configuration = new ConfigurationBuilder()
.SetBasePath(AppContext.BaseDirectory)
.AddJsonFile("appsettings.json", optional: true, reloadOnChange: true)
.AddJsonFile("appsettings.dev.json", optional: true, reloadOnChange: true)
.AddEnvironmentVariables()
.Build();
const string AgentName = "GeminiAssistant";
const string AgentInstructions = """
You are a helpful AI assistant.
Answer questions clearly and concisely.
If you do not know the answer, say so honestly.
""";
// 1. Read configuration (ưu tiên Environment Variable, sau đó đến file config)
string apiKey = configuration["Gemini:ApiKey"]
?? throw new InvalidOperationException(
"GOOGLE_GENAI_API_KEY hoặc Gemini:ApiKey chưa được cấu hình.");
string model = configuration["Gemini:Model"]
?? "gemini-3.8-flash";
// 2. Create Gemini chat client
var chatClient = new Client(
vertexAI: false,
apiKey: apiKey
).AsIChatClient(model);
// 3. Create Agent
var agent = new ChatClientAgent(
chatClient,
name: AgentName,
instructions: AgentInstructions);
// 4. Send a request to the Agent
var response = await agent.RunAsync(
"Explain what an AI Agent is.");
Console.WriteLine(response);
Setup file appsettings.json
{
"Gemini": {
"ApiKey": "AQ.<your-key>",
"Model": "gemini-3.5-flash-lite"
}
}
Chạy chương trình bằng Visual Studio hoặc lệnh:
dotnet run
Nếu cấu hình API key và model hợp lệ, chương trình sẽ gửi câu hỏi đến Gemini và hiển thị câu trả lời trong Console.
6.4. Phân tích đoạn code
Chúng ta hãy xem xét từng thành phần.
Bước 1 – Đọc cấu hình
var configuration = new ConfigurationBuilder()
.SetBasePath(AppContext.BaseDirectory)
.AddJsonFile("appsettings.json", optional: true, reloadOnChange: true)
.AddJsonFile("appsettings.dev.json", optional: true, reloadOnChange: true)
.AddEnvironmentVariables()
.Build();
// 1. Read configuration (ưu tiên Environment Variable, sau đó đến file config)
string apiKey = configuration["Gemini:ApiKey"]
?? throw new InvalidOperationException(
"GOOGLE_GENAI_API_KEY hoặc Gemini:ApiKey chưa được cấu hình.");
string model = configuration["Gemini:Model"]
?? "gemini-3.8-flash";
Ứng dụng đọc API key từ appsetting.
Bước 2 – Tạo Gemini Chat Client
var chatClient = new Client(
vertexAI: false,
apiKey: apiKey
).AsIChatClient(model);
Đây là phần kết nối ứng dụng với Google Gemini Developer API.
Giải thích:
Client: Client của Google GenAI SDK.vertexAI: false: Sử dụng Gemini Developer API thay vì Vertex AI.apiKey: API key dùng để xác thực.AsIChatClient(model): Chuyển client thành abstractionIChatClientđể MAF có thể sử dụng.
IChatClient là abstraction thuộc hệ sinh thái Microsoft.Extensions.AI. Nó giúp ứng dụng làm việc với nhiều nhà cung cấp model thông qua một giao diện thống nhất.
Bước 3 – Tạo Agent
var agent = new ChatClientAgent(
chatClient,
name: AgentName,
instructions: AgentInstructions);
Ở đây chúng ta sử dụng ChatClientAgent.
Các tham số:
chatClient: Model provider mà Agent sẽ sử dụng.name: Tên định danh của Agent.instructions: Hướng dẫn hành vi của Agent.
Instructions đóng vai trò định hướng cách Agent phản hồi.
You are a helpful AI assistant.
Answer questions clearly and concisely.
If you do not know the answer, say so honestly.
Bạn có thể thay đổi Instructions để tạo ra những Agent có vai trò khác nhau.
Bước 4 – Gửi yêu cầu
var response = await agent.RunAsync(
"Explain what an AI Agent is.");
RunAsync() là phương thức yêu cầu Agent xử lý một đầu vào.
Ở ví dụ này, Agent sử dụng Gemini để tạo câu trả lời.
7. Quản lý hội thoại với AgentSession
Ở ví dụ trước, chúng ta gọi RunAsync() một lần.
Nhưng nếu người dùng muốn tiếp tục hỏi dựa trên nội dung của câu trả lời trước đó thì sao?
Ví dụ:
User: What is an AI Agent?
Agent: An AI Agent is a system that can use tools
to complete tasks.
User: Can you give me an example?
Agent: ...
Câu hỏi thứ hai cần ngữ cảnh của câu hỏi thứ nhất.
MAF cung cấp AgentSession để quản lý ngữ cảnh hội thoại.
7.1. Ví dụ hội thoại nhiều lượt
Thay thế nội dung từ số 2 trở đi trong file Program.cs bằng:
// 2. Create Gemini chat client
var chatClient = new Client(
vertexAI: false,
apiKey: apiKey
).AsIChatClient(model);
// 3. Create Agent
var agent = new ChatClientAgent(
chatClient,
name: AgentName,
instructions: AgentInstructions);
// 4. Create a conversation session and start chat loop
AgentSession session = await agent.CreateSessionAsync();
Console.WriteLine("Gemini Agent is ready.");
Console.WriteLine("Type 'exit' to quit.");
while (true)
{
Console.Write("\nYou: ");
string? prompt = Console.ReadLine();
if (string.IsNullOrWhiteSpace(prompt))
{
continue;
}
if (prompt.Equals("exit", StringComparison.OrdinalIgnoreCase))
{
break;
}
var response = await agent.RunAsync(prompt, session);
Console.WriteLine($"\nAgent: {response}");
}
Chạy chương trình và thử hội thoại:
You: What is Microsoft Agent Framework?
Agent: Microsoft Agent Framework is...
You: What are its main components?
Agent: Its main components include...
Ở câu hỏi thứ hai, Agent có thể sử dụng ngữ cảnh từ lượt hội thoại trước đó.
7.2. AgentSession hoạt động như thế nào?
AgentSession session = await agent.CreateSessionAsync();
Dòng code trên tạo một session mới.
Sau đó:
var response = await agent.RunAsync(prompt, session);
Mỗi lần gọi RunAsync() với cùng session, MAF sử dụng session đó để duy trì ngữ cảnh hội thoại.
Cần lưu ý rằng AgentSession trong ví dụ này chỉ được sử dụng trong bộ nhớ của ứng dụng. Khi ứng dụng kết thúc, session không tự động trở thành dữ liệu lưu trữ lâu dài. Nếu muốn khôi phục hội thoại sau khi khởi động lại ứng dụng, chúng ta cần tìm hiểu cơ chế lưu trữ và khôi phục session ở những bài tiếp theo.
8. Tổng kết kiến trúc
Qua bài thực hành, chúng ta đã xây dựng một ứng dụng có các thành phần:
| Thành phần | Trách nhiệm |
|---|---|
| Console Application | Giao diện tương tác với người dùng |
| ChatClientAgent | Đại diện cho AI Agent |
| Agent Instructions | Định nghĩa hành vi của Agent |
| AgentSession | Quản lý ngữ cảnh hội thoại |
| IChatClient | Abstraction giao tiếp với model |
| Google GenAI Client | Kết nối Gemini API |
| Gemini | Thực hiện suy luận và tạo câu trả lời |
Điểm quan trọng nhất cần ghi nhớ:
MAF không phụ thuộc vào một model provider duy nhất. Chúng ta có thể thay đổi provider mà vẫn giữ lại phần lớn logic xây dựng Agent, miễn là provider đó có implementation tương thích với abstraction mà MAF sử dụng.
9. Bài tập thực hành
Hãy thử thực hiện các bài tập sau:
Bài tập 1 – Thay đổi Instructions
Tạo một Agent chuyên giải thích kiến thức lập trình C#.
Yêu cầu:
- Chỉ trả lời các câu hỏi liên quan đến C# và .NET.
- Giải thích bằng tiếng Việt.
- Luôn đưa ví dụ code khi phù hợp.
Bài tập 2 – Thử nghiệm hội thoại nhiều lượt
Hãy đặt các câu hỏi liên tiếp:
What is Dependency Injection?
What are the benefits?
Can you show me a C# example?
Quan sát cách Agent sử dụng ngữ cảnh từ các câu hỏi trước.
Bài tập 3 – Thử thay đổi model
Thay đổi giá trị GOOGLE_GENAI_MODEL sang một model Gemini khác mà tài khoản của bạn được phép sử dụng.
So sánh:
- Chất lượng câu trả lời.
- Thời gian phản hồi.
- Chi phí sử dụng.
10. Kết luận
Trong Day 1, chúng ta đã tìm hiểu các khái niệm nền tảng của AI Agent và xây dựng Agent đầu tiên bằng Microsoft Agent Framework, C# .NET 10 và Google Gemini API.
Chúng ta cũng đã làm quen với một số thành phần quan trọng:
ChatClientAgentIChatClientAgentSessionRunAsync()
Đây là nền tảng để tiếp tục tìm hiểu cách Agent tương tác với hệ thống bên ngoài.
Day 2: Function Calling và Tools – Cho phép AI Agent thực thi các chức năng trong ứng dụng C#.
Source code: https://github.com/anbinhtrong/microsoft-agent-framework-sample-2026/releases/tag/v1.0
Nhận xét