Xây dựng AI Agent Stateful với Agno Framework và Python: Hướng dẫn về Memory, Storage và Knowledge Base

AI tutorial - IT technology blog
AI tutorial - IT technology blog

So sánh cách tiếp cận: Stateless LLM và Stateful Agno Agent

Hầu hết lập trình viên bắt đầu với GenAI bằng cách truyền chuỗi prompt vào một API endpoint rồi in kết quả dạng văn bản ra màn hình. Pattern này hoạt động tốt cho các tác vụ dùng một lần như tóm tắt pull request. Tuy nhiên, nó sẽ bộc lộ hạn chế ngay khi trợ lý ảo cần xử lý các cuộc hội thoại nhiều lượt (multi-turn), tra cứu runbook nội bộ và ghi nhớ tùy chọn cá nhân qua các phiên CLI hoặc web riêng biệt.

Các hệ thống production thường đi theo một trong ba mô hình kiến trúc sau:

  • Gọi trực tiếp API LLM và tự quản lý trạng thái: Bạn gửi raw JSON payload tới OpenAI hoặc Anthropic, đồng thời append lịch sử chat vào một danh sách in-memory. Cách này cho bạn toàn quyền kiểm soát runtime. Điểm trừ? Bạn sẽ phải viết khoảng 300 đến 500 dòng code boilerplate để xử lý giới hạn context window, cắt bớt token (token truncation), lưu trữ database và tra cứu vector.
  • Các framework điều phối nặng nề (Heavy Orchestration Frameworks): Các thư viện dạng graph nguyên khối mang lại hệ sinh thái khổng lồ. Tuy nhiên, hệ thống phân cấp class sâu và các chain wrapper phức tạp thường dẫn đến mã nguồn dễ gãy vỡ. Khi một request bị treo trên production, việc lần vết qua 6 tầng callback nội bộ sẽ biến quá trình debug thành cơn ác mộng.
  • Kiến trúc Agent tinh gọn (Agno Framework): Agno—phiên bản kế nhiệm của Phidata—dựa trên các primitive chuẩn của Python. Framework này đóng gói LLM, persistent storage, memory và vector knowledge vào một đối tượng duy nhất, gắn kết mà không cần các middleware ẩn hay các tầng trừu tượng cồng kềnh.

Chuyển đổi từ các hàm bọc prompt dùng một lần sang các công cụ đáng tin cậy cho doanh nghiệp đòi hỏi bạn phải làm chủ được các ranh giới trạng thái này.

Ưu và nhược điểm khi sử dụng Agno Framework cho Stateful Agent

Đánh giá kỹ agent framework ngay từ đầu sẽ giúp bạn tránh được việc phải viết lại toàn bộ mã nguồn đầy đau đớn sau sáu tháng triển khai production. Dưới đây là đánh giá thực tế về Agno trong môi trường kỹ thuật thực tế.

Ưu điểm

  • Tách bạch trạng thái rõ ràng: Agno phân định rạch ròi giữa log hội thoại thô (storage), thuộc tính người dùng đã được tóm tắt (memory) và tài liệu tham khảo đã được đánh chỉ mục (knowledge base). Bạn sẽ không bao giờ phải gượng ép đưa log hội thoại vào vector collection chỉ để ghi nhớ một username.
  • Overhead tối thiểu và tốc độ thực thi nhanh: Nhờ sử dụng Pydantic schema gọn nhẹ và các lệnh gọi Python chuẩn, chi phí điều phối (dispatch overhead) của framework luôn ở mức dưới 5ms mỗi lượt chạy. Ngược lại, các graph engine cồng kềnh có thể làm tăng từ 50ms đến 120ms độ trễ middleware trước cả khi lệnh gọi model bắt đầu.
  • Adapter database tích hợp sẵn: Cung cấp sẵn các driver production-ready cho SQLite, PostgreSQL (hỗ trợ pgvector), LanceDB và Qdrant. Bạn có thể tạo prototype với file cục bộ trên máy cá nhân rồi chuyển sang cluster Aurora Postgres trên staging chỉ bằng việc thay đổi một connection URI duy nhất.
  • Debug dễ dàng, trực quan: Vết thực thi (execution trace) luôn theo đường thẳng. Nếu một truy vấn của agent gặp lỗi, stack trace sẽ chỉ thẳng tới hàm hoặc lệnh gọi database bị lỗi thay vì đi lòng vòng trong runtime loop nội bộ của framework.

Nhược điểm & Đánh đổi

  • Hệ sinh thái đang trong giai đoạn phát triển: Sau khi đổi tên từ Phidata vào cuối năm 2024, API cốt lõi đã ổn định. Tuy nhiên, các bài hướng dẫn cộng đồng từ đầu năm 2024 thường chứa các tên class không còn được khuyến nghị (deprecated) và đường dẫn import cũ.
  • Danh mục tích hợp còn hạn chế: LangChain sở hữu danh sách hơn 700 connector từ cộng đồng, trong khi Agno chỉ tập trung vào các giao thức thiết yếu. Việc tích hợp một API SaaS doanh nghiệp đặc thù thường đồng nghĩa với việc bạn phải tự viết một custom tool Python gọn gàng khoảng 15 dòng.

Thiết lập môi trường phát triển cục bộ chuẩn Production

Hãy thiết lập một môi trường sandbox sử dụng Python 3.10, 3.11 hoặc 3.12. Đối với trạng thái cục bộ, SQLite sẽ đảm nhận việc lưu trữ phiên làm việc (session persistence) và LanceDB quản lý các vector embedding. Cả hai đều chạy nhúng trực tiếp bên trong tiến trình và lưu thẳng xuống ổ đĩa, do đó bạn không cần đến Docker daemon hay các dịch vụ database độc lập trong quá trình phát triển.

Khởi tạo thư mục làm việc và môi trường ảo:

mkdir agno-stateful-agent
cd agno-stateful-agent
python3 -m venv .venv
source .venv/bin/activate

Cài đặt các dependency với phiên bản cố định:

pip install agno==1.1.3 openai lancedb tantivy pypdf sqlalchemy

Cấu hình xác thực OpenAI:

export OPENAI_API_KEY="sk-proj-your-actual-api-key-here"

Hướng dẫn triển khai: Từng bước xây dựng Agno Agent với Memory, Storage và Knowledge Base

Chúng ta sẽ xây dựng một trợ lý vận hành (operations assistant) có khả năng lưu giữ lịch sử trò chuyện kể cả khi tiến trình khởi động lại, theo dõi tùy chọn của lập trình viên và đưa ra câu trả lời dựa trên runbook kỹ thuật nội bộ.

Bước 1: Thiết lập cấu trúc thư mục và dữ liệu mẫu

Tạo các thư mục riêng cho tài liệu nghiệp vụ và các file database SQLite:

mkdir -p data/docs data/storage

Ghi chính sách bảo mật vận hành vào file data/docs/company_policy.txt:

Hướng dẫn bảo mật mạng:
- Kỹ sư phải thay đổi thông tin xác thực VPN định kỳ mỗi 90 ngày.
- Triển khai lên môi trường production yêu cầu phê duyệt ngang hàng (peer approval) từ ít nhất hai kỹ sư cấp cao.
- Sao lưu database diễn ra hàng ngày vào lúc 02:00 UTC và được lưu trữ tại cold storage đa khu vực trong 365 ngày.
- Việc nâng cấp cụm Kubernetes tại khu vực ap-southeast-1 cần thông báo tạm ngừng bảo trì trước 48 giờ.

Bước 2: Cấu hình Knowledge Base và Vector Database

Tạo một file có tên agent.py. Chúng ta import các module cốt lõi của Agno và cấu hình LanceDB với tính năng tìm kiếm lai (hybrid search – kết hợp truy xuất vector dày đặc và xếp hạng từ khóa BM25 qua Tantivy) để đánh chỉ mục file văn bản.

from pathlib import Path
from agno.agent import Agent
from agno.models.openai import OpenAIChat
from agno.storage.agent.sqlite import SqliteAgentStorage
from agno.knowledge.text import TextKnowledgeBase
from agno.vectordb.lancedb import LanceDb, SearchType

# Cấu hình vector database lưu trữ cố định trên ổ đĩa cục bộ
vector_db = LanceDb(
    table_name="knowledge_store",
    uri="data/storage/lancedb",
    search_type=SearchType.hybrid,
)

# Khởi tạo knowledge base trỏ tới thư mục tài liệu
knowledge_base = TextKnowledgeBase(
    path=Path("data/docs"),
    vector_db=vector_db,
)

# Vector hóa tài liệu trong lần chạy đầu tiên; tái sử dụng index đã có khi khởi động lại
knowledge_base.load(recreate=False)

Bước 3: Gắn Persistent Storage và khởi tạo Agent

Tiếp theo, cấu hình lưu trữ SQLite. Thiết lập read_chat_history=True sẽ yêu cầu Agno truy vấn SQLite và nạp lại các hội thoại trước đó vào context của prompt cho các phiên đang tiếp diễn.

# Cấu hình bảng phiên làm việc cố định trong SQLite
storage = SqliteAgentStorage(
    table_name="agent_sessions",
    db_file="data/storage/sessions.db",
)

# Khởi tạo agent cùng các engine quản lý trạng thái
assistant = Agent(
    name="Trợ lý DevOps",
    model=OpenAIChat(id="gpt-4o-mini"),
    knowledge=knowledge_base,
    storage=storage,
    search_knowledge=True,
    read_chat_history=True,
    show_tool_calls=True,
    markdown=True,
    instructions=[
        "Luôn đối chiếu các quy tắc vận hành với knowledge base nội bộ trước tiên.",
        "Ghi nhớ thông tin cá nhân, tùy chọn hạ tầng và tên dịch vụ do người dùng cung cấp.",
        "Trả lời kỹ thuật súc tích, trực diện và không dùng từ ngữ xã giao rườm rà.",
    ],
)

Bước 4: Thực thi phiên tương tác với tính năng lưu trữ trạng thái

Để xác minh rằng trạng thái vẫn tồn tại sau khi tiến trình dừng chạy, hãy bọc phần thực thi trong một vòng lặp CLI gắn với session_id và user_id cụ thể. Thêm đoạn mã sau vào agent.py:

def run_chat_session(session_id: str, user_id: str):
    print(f"\n--- Phiên hoạt động: {session_id} | Người dùng: {user_id} ---")
    print("Nhập 'exit' hoặc 'quit' để kết thúc script.\n")
    
    while True:
        try:
            user_prompt = input("Bạn: ").strip()
            if user_prompt.lower() in ["exit", "quit"]:
                print("Đang đóng phiên làm việc...")
                break
            if not user_prompt:
                continue
                
            print("\nTrợ lý: ", end="")
            assistant.print_response(
                user_prompt,
                session_id=session_id,
                user_id=user_id,
                stream=True,
            )
            print()  # Xuống dòng sau khi hoàn thành streaming
        except KeyboardInterrupt:
            print("\nĐã tạm dừng phiên làm việc.")
            break

if __name__ == "__main__":
    # Các định danh cố định giúp kiểm tra khả năng lưu trữ trạng thái qua các lần khởi động lại script
    SESSION_ID = "infra-ops-room-42"
    USER_ID = "engineer-alex"
    run_chat_session(SESSION_ID, USER_ID)

Bước 5: Xác minh Memory và khả năng truy xuất

Khởi chạy vòng lặp tương tác từ terminal của bạn:

python agent.py

Chạy thử ba prompt kiểm tra cụ thể sau đây để xác thực từng tầng kiến trúc:

  1. Truy xuất Knowledge Base: Hỏi "Chính sách sao lưu database production của chúng ta là gì?". Agent sẽ truy vấn LanceDB, tìm tài liệu chính sách và thông báo lịch sao lưu hàng ngày lúc 02:00 UTC cùng quy định lưu trữ cold storage trong 365 ngày.
  2. Ngữ cảnh phiên làm việc (Session Context): Khai báo phạm vi vận hành của bạn: "Tôi quản lý các cụm Kubernetes chính ở ap-southeast-1.". Trợ lý sẽ ghi nhận phạm vi khu vực của bạn và lưu phiên trao đổi vào SQLite.
  3. Lưu trữ qua tiến trình (Process Persistence): Gõ exit để tắt hoàn toàn tiến trình Python. Khởi động lại bằng lệnh python agent.py và hỏi: "Tôi đang phụ trách vùng cloud và workload nào?".

Vì database SQLite đã lưu các lượt trao đổi trước đó của bạn theo phiên infra-ops-room-42, agent sẽ truy xuất lại các tin nhắn cũ ngay lập tức. Agent xác nhận rằng bạn quản lý Kubernetes tại ap-southeast-1—mà không cần đến bất kỳ thủ thuật prompt engineering nào.

Share: