Chuyển đến nội dung chính

Microsoft Agent Framework: Tìm hiểu AI Agent và xây dựng Agent đầu tiên với C# - Day 1

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ệ
IDEVisual Studio 2026
Framework.NET 10
Ngôn ngữC# 14
Agent FrameworkMicrosoft Agent Framework
LLM ProviderGoogle Gemini Developer API
ModelGemini 3.8 Flash
Package ManagerNuGet

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ý:

flowchart TD A["User"] --> B["Chatbot Application"] B --> C["LLM"] C --> D["Generate Response"] D --> E["Display to User"]

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:

  1. Hiểu yêu cầu của người dùng.
  2. Xác định cần kiểm tra thông tin đơn hàng.
  3. Gọi công cụ tra cứu đơn hàng.
  4. Đọc kết quả trả về.
  5. Phân tích trạng thái giao hàng.
  6. Trả lời người dùng.
flowchart TD A["User Request"] --> B["AI Agent"] B --> C["LLM Reasoning"] C --> D{"Need a Tool?"} D -->|Yes| E["Call Tool"] E --> F["Receive Tool Result"] F --> C D -->|No| G["Generate Final Response"] G --> H["User"]

Đ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.

flowchart TB U["User"] --> A["Microsoft Agent Framework"] subgraph MAF["Agent Framework"] A --> I["Instructions"] A --> T["Tools"] A --> S["Session"] A --> C["Agent Orchestration"] end C --> P["IChatClient"] P --> G["Google Gemini API"] G --> P P --> C C --> R["Agent Response"] R --> U

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:

  1. Create a new project.
  2. Chọn Console App.
  3. Đặt tên project: MafGeminiDemo.
  4. Chọn Framework: .NET 10.0.
  5. 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:

PackageVai 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 abstraction IChatClient để 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.

sequenceDiagram participant U as User participant A as MAF Agent participant S as AgentSession participant G as Gemini U->>A: First question A->>S: Read conversation context A->>G: Send prompt G-->>A: First response A->>S: Update conversation A-->>U: First response U->>A: Follow-up question A->>S: Read previous context A->>G: Send context + new prompt G-->>A: Follow-up response A->>S: Update conversation A-->>U: Follow-up response

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ầnTrách nhiệm
Console ApplicationGiao 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
AgentSessionQuản lý ngữ cảnh hội thoại
IChatClientAbstraction giao tiếp với model
Google GenAI ClientKết nối Gemini API
GeminiThự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:

  • ChatClientAgent
  • IChatClient
  • AgentSession
  • RunAsync()

Đâ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

Tài liệu tham khảo

  1. Microsoft Agent Framework – GitHub
  2. Microsoft Learn – Google Gemini integration
  3. Microsoft Learn – Model Providers
  4. Google AI Studio
  5. Gemini API – Models
  6. Visual Studio 2026

Nhận xét

Bài đăng phổ biến từ blog này

[ASP.NET MVC] Authentication và Authorize

Một trong những vấn đề bảo mật cơ bản nhất là đảm bảo những người dùng hợp lệ truy cập vào hệ thống. ASP.NET đưa ra 2 khái niệm: Authentication và Authorize Authentication xác nhận bạn là ai. Ví dụ: Bạn có thể đăng nhập vào hệ thống bằng username và password hoặc bằng ssh. Authorization xác nhận những gì bạn có thể làm. Ví dụ: Bạn được phép truy cập vào website, đăng thông tin lên diễn đàn nhưng bạn không được phép truy cập vào trang mod và admin.

Tổng hợp một số kiến thức lập trình về Amibroker

Giới thiệu về Amibroker Amibroker theo developer Tomasz Janeczko được xây dựng dựa trên ngôn ngữ C. Vì vậy bộ code Amibroker Formula Language sử dụng có syntax khá tương đồng với C, ví dụ như câu lệnh #include để import hay cách gói các object, hàm trong các block {} và kết thúc câu lệnh bằng dấu “;”. AFL trong Amibroker là ngôn ngữ xử lý mảng (an array processing language). Nó hoạt động dựa trên các mảng (các dòng/vector) số liệu, khá giống với cách hoạt động của spreadsheet trên excel.

ASP.NET MVC: Cơ bản về Validation

Validation (chứng thực) là một tính năng quan trọng trong ASP.NET MVC và được phát triển trong một thời gian dài. Validation vắng mặt trong phiên bản đầu tiên của asp.net mvc và thật khó để tích hợp 1 framework validation của một bên thứ 3 vì không có khả năng mở rộng. ASP.NET MVC2 đã hỗ trợ framework validation do Microsoft phát triển, tên là Data Annotations. Và trong phiên bản 3, framework validation đã hỗ trợ tốt hơn việc xác thực phía máy khách, và đây là một xu hướng của việc phát triển ứng dụng web ngày nay.