Agno và AgentOS: tự vận hành nền tảng agent, từ SDK tới bàn biên tập
Đăng ngày 12/10/2026
Mục lục bài nghiên cứu
Agno trong một trang: SDK, runtime AgentOS và khi nào nên chọn
Agno tự mô tả là framework và runtime cho nền tảng agent (tác tử AI biết gọi công cụ và tự quyết định từng bước): dựng agent bằng SDK Python, chạy chúng thành dịch vụ qua AgentOS, quản trị bằng giao diện web. README nhấn mạnh việc tự sở hữu ngăn xếp: dữ liệu, bộ nhớ và phân quyền dựa trên JWT nằm trong hạ tầng của đơn vị triển khai. [1][3]
Điểm khác một thư viện thông thường là runtime. Cookbook AgentOS mô tả ứng dụng FastAPI biến agent, team, workflow và kho tri thức thành khoảng 80 endpoint REST, kèm giao diện MCP, A2A, AG-UI, Slack, Telegram, WhatsApp [7]; README lại ghi “50+ endpoint” [1]. Con số chính xác nên đọc từ /openapi.json của bản đang chạy.
Khuyến nghị: cân nhắc Agno khi cần phục vụ nhiều agent cho nhiều người dùng qua một API chung có lưu phiên, phân quyền, phê duyệt, lịch chạy, và có người vận hành được Python lẫn PostgreSQL. Không nên chọn cho một script gọi mô hình đơn lẻ hay cho đội chưa tự quản được cơ sở dữ liệu và khóa bí mật.
Khoảng trống giữa một agent chạy được và một nền tảng vận hành được
Dựng một agent biết gọi công cụ chỉ mất vài dòng; quickstart của Agno minh họa bằng agent dùng Gemini với bộ công cụ Yahoo Finance [3]. Việc khó bắt đầu khi agent phải nhớ hội thoại sau khi tiến trình khởi động lại, phân biệt người dùng, dừng chờ người duyệt trước thao tác có hậu quả và để lại dấu vết kiểm toán.
Quickstart sắp các năng lực ấy thành bậc thang: công cụ, đầu ra có kiểu, lưu hội thoại, bộ nhớ, trạng thái, tri thức, học hỏi, guardrail (rào chắn kiểm tra đầu vào), phê duyệt, team, workflow. Bảng mô hình tư duy phân định: storage giữ bản ghi hội thoại, memory giữ dữ kiện bền vững về một người, state giữ dữ liệu có cấu trúc thay đổi được, knowledge là thứ agent tìm kiếm. [3]
Bài toán Agno nhắm tới vì thế là hạ tầng bao quanh agent, không phải trí thông minh của agent. Năm agent rời rạc, mỗi cái tự lưu dữ liệu và kiểm quyền một kiểu, sẽ khó trả lời câu hỏi “ai đã chạy agent nào với dữ liệu gì”. Quickstart cũng nói rõ ví dụ của nó dạy kiến trúc agent, không phải lời khuyên đầu tư [3].
Ba tầng: SDK dựng agent, AgentOS phục vụ, control plane quản trị
Tầng SDK có ba khối: Agent gắn mô hình với công cụ; Team để trưởng nhóm ủy quyền động cho thành viên; Workflow quy định thứ tự bước tường minh. Quickstart khuyên chỉ thêm team khi chuyên gia độc lập thật sự cải thiện câu trả lời, chỉ dùng workflow khi thứ tự thao tác phải dự đoán được [3]. Thư mục ví dụ team còn có định tuyến, broadcast, team lồng nhau, chế độ task; vài ví dụ cần PostgreSQL, LanceDB hoặc Infinity [6].
Tầng runtime là AgentOS. Một đối tượng agent gắn được vào nhiều giao diện mà không nhân bản chỉ dẫn, công cụ hay trạng thái; GET /config mô tả agent, mô hình, cơ sở dữ liệu và giao diện đã đăng ký. Cookbook còn có vòng đời lượt chạy (chạy nền, hủy, tiếp tục, checkpoint), bộ lập lịch, quan sát và factory dựng agent theo từng yêu cầu từ danh tính tin cậy. [7]
Tầng quản trị là control plane: quickstart hướng dẫn mở os.agno.com, khai báo localhost:7777 làm endpoint để trò chuyện, xem phiên, trace (dấu vết thực thi), bộ nhớ và tri thức [3]. Runtime chạy trong hạ tầng người dùng, còn giao diện được phục vụ từ tên miền của Agno; các tệp đã đọc không mô tả điều khoản hay đường đi dữ liệu của giao diện này.
Một lượt chạy đi đâu: từ yêu cầu REST tới hàng trong bảng agno_runs
Ghép từ các tài liệu đã đọc, luồng dữ liệu như sau. Client gọi AgentOS qua REST, SSE (luồng sự kiện máy chủ đẩy) hoặc websocket [1]. Nếu bật bảo mật, JWT được kiểm tính hợp lệ, audience (khi bật) và phạm vi quyền trước khi tới route [8]. Agent ghép chỉ dẫn, lịch sử phiên, bộ nhớ, kết quả tìm tri thức, gọi mô hình, chạy công cụ rồi trả kết quả.
Từ v3.0, mỗi lượt chạy là một hàng trong bảng agno_runs với cột lọc được như session_id, agent_id, user_id, status, còn nội dung lượt vẫn là một giá trị JSON; lượt của thành viên team mang parent_run_id liên kết với lượt chạy cha [9]. Khi dừng chờ con người, yêu cầu đang chờ được tuần tự hóa trong tools, requirements hoặc step_requirements tùy agent, team hay workflow, rồi gửi lại route /continue sau khi quyết định [11].
Hai dòng dữ liệu nữa cần có trên sơ đồ: prompt và ngữ cảnh rời hạ tầng mỗi khi gọi API mô hình đám mây; và telemetry mà README nói được gửi mỗi lượt chạy, không kèm prompt, tin nhắn hay đầu ra, tắt được bằng AGNO_TELEMETRY=false. [1]
Bài học từ đợt đổi cách lưu trữ ở v3.0
Ở bản 2.x, cột runs của bảng phiên giữ cả danh sách lượt chạy trong một khối JSON, nên lưu lượt thứ N lại ghi lại cả N lượt; hướng dẫn di chuyển gọi đó là khuếch đại ghi tăng theo bình phương. Việc chuyển sang v3.0 được thiết kế không phá hủy: cột cũ giữ làm bản sao đóng băng tới khi người vận hành chủ động xóa, lượt chạy của phiên còn tự di chuyển dần khi được lưu lại. [9]
Ngoại lệ là bộ nhớ thực thể đặt namespace="user". Trước v3.0, khóa hàng không chứa thành phần người dùng, nên hai người ghi cùng tên và loại thực thể dùng chung một hàng, dữ kiện người này có thể lọt vào ngữ cảnh mô hình của người kia. Bước tạo lại khóa không tự chạy, phải làm trước khi nhận lưu lượng, không đảo ngược được; hàng đã trộn dữ liệu bị chuyển sang namespace quarantined_user. [9]
Bảng metrics chưa di chuyển hoặc di chuyển dở thì hỏng im lặng: tùy hệ quản trị, API trả lỗi 500, trả danh sách rỗng hoặc ghi số liệu người này vào hàng người kia. Tài liệu cũng tách hiện trạng với kế hoạch: ClickHouse vẫn lưu lượt chạy trong phiên, được hẹn xử lý ở bản sau [9]. Bài học: mỗi lần nâng phiên bản cần bước MigrationManager, sao lưu và kiểm tra sau nâng cấp.
Năng lực có bằng chứng trong cookbook và nhật ký kiểm thử
README công bố: API production có SSE, websocket; lưu phiên, bộ nhớ, tri thức, trace trong cơ sở dữ liệu của người dùng; hơn 100 tích hợp; context provider đọc Slack, Drive, wiki, MCP; phê duyệt; OpenTelemetry và nhật ký kiểm toán; RBAC (phân quyền theo vai trò) dựa trên JWT với cô lập đa người dùng; giao diện Slack, Telegram, WhatsApp, Discord, AG-UI, A2A; lập lịch kiểu cron. [1]
Nhật ký kiểm thử quickstart ngày 23/07/2026 ghi Agno 2.8.0, mô hình gemini-3.6-flash, 12/12 ví dụ đạt cùng phần AgentOS: đầu vào sai định dạng bị từ chối trước khi gọi mô hình, phiên được khôi phục ở tiến trình mới, guardrail chặn PII, prompt injection, spam. Nhật ký do chính dự án ghi, trên một commit gốc cộng thay đổi chưa commit [4]. Kế hoạch kiểm thử đi kèm chấm theo hành vi chứ không theo giá cổ phiếu biến động [5].
Về phê duyệt, AgentOS có hai hợp đồng tạm dừng. Các cờ requires_confirmation, requires_user_input, external_execution tạo yêu cầu tạm thời trên lượt chạy đã lưu; @approval(type="required") tạo thêm bản ghi bền vững để quản trị viên giải quyết qua API hoặc trang Approvals; kiểu audit ghi lại kết quả quyết định tạm thời. [11]
Ai nên đọc kỹ Agno, ai chỉ cần tham khảo
Hưởng lợi rõ nhất là đội kỹ thuật nội bộ phải cung cấp nhiều agent cho nhiều phòng ban qua một API: công ty phần mềm, đơn vị truyền thông, bộ phận chuyển đổi số. Họ cần lưu trữ riêng, phân quyền, quan sát, giao diện nhắn tin như README liệt kê, hơn là một lớp gọi mô hình. [1]
Lĩnh vực có quy trình duyệt nhiều tầng như báo chí, pháp chế, dịch vụ khách hàng tận dụng được phê duyệt bền vững và cô lập dữ liệu theo người dùng [8][11]. Startup chỉ cần một tính năng chat sẽ thấy runtime đầy đủ là quá nhiều thứ phải vận hành.
Người xây hệ thống tri thức kiểu “bộ não thứ hai”, như cách phamvanthu.com gom chuỗi nghiên cứu thành kho tham khảo, có thể học cách Agno tách storage, memory, knowledge và learning [3]: dữ kiện nào thuộc một người, dữ kiện nào dùng chung, bài học nào phải được duyệt trước khi một người dạy lại cho tất cả.
Đề xuất cho một tòa soạn báo điện tử: agent chuẩn bị, con người xuất bản
Tình huống giả định: một tòa soạn báo điện tử có vài chục phóng viên, biên tập viên muốn rút ngắn khâu tra tư liệu và kiểm chứng nhưng không để máy tự đưa bài lên trang. Đề xuất chạy AgentOS trong hạ tầng tòa soạn với PostgreSQL [1], nhận JWT từ hệ thống đăng nhập sẵn có theo cách tự mang bên cấp token mà tài liệu bảo mật minh họa bằng WorkOS [8].
Ba agent ban đầu. Trợ lý tư liệu tìm trên kho bài đã đăng và sổ tay biên tập, trả lời kèm mã bài gốc. Tổ kiểm chứng là một team: một thành viên gom bằng chứng ủng hộ, một thành viên tìm bằng chứng ngược, trưởng nhóm nêu chỗ bất đồng, giống ví dụ hai nhà phân tích đối lập trong quickstart [3][4]. Workflow điểm tin sáng chạy theo lịch: thu thập từ nguồn được phép, tóm tắt, soạn nháp [7].
Ranh giới then chốt: công cụ đẩy bản nháp sang CMS gắn @approval(type="required"), mỗi lần gọi sinh bản ghi phê duyệt để thư ký tòa soạn quyết định; không agent nào có công cụ xuất bản [11]. Tin bạn đọc gửi qua guardrail PII và prompt injection [4]. Phóng viên có agents:run, rất ít tài khoản giữ agent_os:admin vì quyền này vượt qua cô lập; user_isolation=True bảo vệ phiên của các đề tài điều tra [8].
Tòa soạn còn phải tự kiểm chất lượng tìm kiếm tiếng Việt có dấu, và lưu ý README không liệt kê Zalo trong các giao diện, nên dùng Zalo phải tự viết cầu nối qua REST API [1]. Mọi chi tiết ở trên là thiết kế giả định, cần được thử trước khi tin.
Đưa AgentOS vào vận hành: cơ sở dữ liệu, phiên bản và lịch chạy
README gợi ý giao cho coding agent nhân bản mẫu agentos-railway, chạy bằng Docker để có REST API, PostgreSQL cho dữ liệu và trace, máy chủ MCP và control plane; các mẫu khác nhắm AWS, GCP, Azure, Fly, Render, Modal, Helm [1]. Các mẫu nằm ở kho riêng; bài chưa đọc mã nên không đánh giá.
Cơ sở dữ liệu là trung tâm. Cookbook có bài riêng về chọn backend production và quản lý di chuyển schema; bộ lập lịch cần gói phụ agno[scheduler] cùng PostgreSQL [7]. Trong AgentOS, MigrationManager chỉ gọi được qua route /databases/.../migrate khi ứng dụng đã chạy, nên bước di chuyển phải nằm trong quy trình triển khai, trước khi phục vụ lưu lượng [9].
Ghim phiên bản là bắt buộc: nhật ký quickstart ghi Agno 2.8.0 [4] trong khi cùng commit đã có hướng dẫn thay đổi lưu trữ v3.0 [9]. Quy trình đề xuất: ghim gói, chạy lại ví dụ trên staging, kiểm di chuyển dữ liệu rồi mới nâng production. Cũng cần định trước nơi lưu trace, thời hạn giữ và ai được đọc, vì trace thường chứa nguyên văn prompt và kết quả công cụ.
JWT, phạm vi quyền và cô lập người dùng: công tắc nào phải bật có chủ đích
Tài liệu bảo mật AgentOS đi từ ngoài vào trong: xác thực người gọi, kiểm token có được cấp cho đúng AgentOS, phân quyền route, cô lập dữ liệu từng người. Chi tiết dễ sót: phải đặt authorization=True thì scope mới bảo vệ route, nếu không JWT hợp lệ chỉ được xác thực; các route /, /health, /info, /docs, /redoc, /openapi.json luôn công khai. [8]
user_isolation=True ghim người gọi không phải admin vào giá trị sub của token. Nội dung tri thức không chủ sở hữu thì mọi người đọc được nhưng chỉ admin xóa được; lịch chạy không chủ sở hữu vô hình với người dùng bị giới hạn nhưng vẫn kích hoạt. Token tài khoản dịch vụ agno_pat_ chỉ hiện một lần, hạn mặc định 90 ngày, kết quả xác minh được đệm 30 giây nên việc thu hồi lan tới worker khác có độ trễ [8], cần ghi vào quy trình ứng phó sự cố.
Về quyền riêng tư, hệ thống từng chạy 2.x với bộ nhớ thực thể theo người dùng phải tạo lại khóa và rà namespace quarantined_user [9]. Telemetry theo README không chứa nội dung nhưng nên tắt ở môi trường nhạy cảm [1]. Guardrail PII và prompt injection có ích [4], song không thay được đánh giá rủi ro theo pháp luật về bảo vệ dữ liệu cá nhân.
Apache-2.0 cho mã; control plane, mô hình và mẫu triển khai nằm ngoài phạm vi
Văn bản ở thư mục gốc, đọc tại commit khảo sát, là Apache License 2.0 với dòng bản quyền 2025-2026 của Agno Inc.; libs/agno/LICENSE trong thư mục mã thư viện mang đúng nội dung đó. Giấy phép cho phép dùng, sửa, phân phối lại, có điều khoản cấp quyền sáng chế, yêu cầu giữ thông báo bản quyền và ghi chú thay đổi khi phân phối bản sửa [2][10]. Hai tệp LICENSE riêng trong libs/agno_infra và libs/agnoctl chưa được đọc.
Giấy phép không bao trùm control plane trên os.agno.com, tài liệu trên docs.agno.com, các kho mẫu agentos-*, mô hình Gemini hay OpenAI gọi qua API, công cụ bên thứ ba và dữ liệu [1][3][7]. Các tệp đã đọc không cho biết control plane có gói trả phí hay giới hạn nào, nên không thể kết luận toàn chuỗi là miễn phí.
Ranh giới phiên bản: tính năng culture thử nghiệm bị gỡ hẳn ở v3.0, bảng agno_culture cũ bị bỏ lại; người dùng 2.x phải đối chiếu danh sách thay đổi phá vỡ trước khi nâng [9]. Siêu dữ liệu GitHub lúc thu thập ghi bản phát hành mới nhất v3.1.2; bài không đối chiếu bản đó với mã.
Ước lượng nguồn lực cho một nền tảng agent tự vận hành
Không có phí bản quyền, nhưng có chi phí vận hành; bài không đưa giá. Giả định một tổ chức vừa chạy vài agent cho vài chục người dùng: cần máy chủ hoặc dịch vụ container cho AgentOS, PostgreSQL có sao lưu, nơi lưu trace và môi trường staging để thử di chuyển schema [7][9].
Chi phí biến đổi chủ yếu là lời gọi mô hình và embedding: mỗi agent khai báo mô hình riêng, bộ nhớ có mô hình riêng, tri thức dùng embedder riêng, nên một câu hỏi có thể kéo theo nhiều lời gọi; team và workflow nhân thêm [3]. Nhật ký ghi workflow ba bước chạy khoảng 30 giây trong một lần kiểm, nhưng đó là quan sát đơn lẻ của dự án, không dùng để dự báo [4].
Khoản lớn nhất thường là con người: kỹ sư Python viết công cụ, người quản trị cơ sở dữ liệu và khóa bí mật, người nghiệp vụ soạn bộ câu hỏi đánh giá, thời gian của người duyệt. Với tòa soạn, thước đo hợp lý là chi phí trên mỗi bản nháp được biên tập viên giữ lại.
Đặt Agno cạnh các lối đi khác
Lối tự viết dùng SDK của nhà cung cấp mô hình, FastAPI và cơ sở dữ liệu sẵn có: ít phụ thuộc, nhưng phải tự làm phiên, phân quyền, phê duyệt, lịch chạy. Hợp lý khi chỉ có một hai agent đơn giản.
Lối thứ hai dùng thư viện điều phối như LangChain, LangGraph, Pydantic AI hoặc framework đa agent theo vai trò như CrewAI, AutoGen, rồi tự dựng lớp dịch vụ. Lối thứ ba là nền tảng kéo thả như Langflow, Dify khi người không viết mã cần tham gia. Lối thứ tư là thuê hẳn dịch vụ agent của một nhà cung cấp đám mây: nhẹ việc vận hành, đổi lại phụ thuộc vào nơi giữ dữ liệu. Các dự án vừa kể chỉ được nêu như ví dụ về cách tiếp cận, chưa được khảo sát mã.
Điểm riêng của Agno là SDK và runtime đi cùng nhau, ghép được agent từ xa qua A2A, kể cả dịch vụ Google ADK theo bài 20_remote [7]. Tiêu chí chọn: số agent và người dùng, nhu cầu phê duyệt bền vững, năng lực vận hành PostgreSQL, và mức chấp nhận thay đổi phá vỡ giữa các bản lớn [9].
Khi nào Agno quá nặng hoặc chưa đủ
Agno thay đổi nhanh: cùng commit có nhật ký kiểm thử của 2.8.0 và hướng dẫn thay đổi phá vỡ của 3.0, có tính năng bị gỡ hẳn [4][9]. Tổ chức không có người đọc changelog và chạy di chuyển schema sẽ tích tụ rủi ro.
Ngữ nghĩa phân quyền tinh vi: quên authorization=True thì scope vô hiệu, admin vượt qua cô lập, lịch không chủ vẫn chạy, thu hồi token có độ trễ [8]. Tài liệu chủ yếu ở dạng cookbook, nhiều ví dụ cần dịch vụ phụ hoặc khóa OpenAI [6][7]. Nhật ký lịch sử còn ghi một lần treo chưa rõ nguyên nhân và một sai lệch giữa cách guardrail báo chặn với nhánh bắt ngoại lệ trong ví dụ [4].
Không nên dùng khi nhu cầu là tự động hóa quy tắc cố định, khi dữ liệu không được rời hạ tầng mà chưa có mô hình nội bộ đạt chất lượng, hoặc khi mọi giao diện quản trị bắt buộc tự lưu trữ trong khi vai trò của control plane trên os.agno.com chưa được làm rõ [3].
Thử nghiệm tám tuần với ngưỡng dừng định trước
Tuần 1 đến 2: dựng AgentOS trên staging với PostgreSQL, JWT từ hệ thống đăng nhập, authorization=True, user_isolation=True, telemetry tắt. Chạy ma trận kiểm scope theo mẫu test_scopes.py của cookbook bảo mật, vốn không gọi mô hình, và thêm ca cho các vai trò tòa soạn [8]. Điều kiện qua: không ca nào đọc được phiên người khác.
Tuần 3 đến 5: chạy trợ lý tư liệu và tổ kiểm chứng trên bộ câu hỏi có đáp án và một tập nhận định sai cài sẵn; như kế hoạch kiểm thử của dự án, mỗi lần chạy ghi commit, phiên bản, mã mô hình [5]. Tuần 6 đến 8: bật workflow điểm tin có phê duyệt bền vững, đối chiếu nhật ký CMS để chắc mọi lần đẩy nháp đều có bản ghi phê duyệt, thử cả nhánh từ chối [11].
Chỉ số: tỷ lệ trích đúng bài nguồn, tỷ lệ nhận định sai lọt qua, số nháp bị trả lại, thời gian chờ duyệt. Điều kiện dừng: một sự cố lộ dữ liệu giữa người dùng; tỷ lệ trích sai vượt ngưỡng chốt trước; chi phí mỗi bản nháp được giữ vượt ngân sách; hoặc nâng cấp làm hỏng dữ liệu không khôi phục được.
Kết luận: sở hữu ngăn xếp agent cũng là sở hữu việc vận hành nó
Agno đáng chú ý vì đặt agent vào một runtime có API, lưu trữ, phân quyền, phê duyệt và lập lịch, thay vì để mỗi agent là một script riêng lẻ [1][7]. Với tổ chức muốn giữ dữ liệu trong hạ tầng của mình, đây là hướng đi có cơ sở.
Cái giá là trách nhiệm kỹ thuật: bật đúng công tắc bảo mật, chạy di chuyển dữ liệu mỗi lần nâng cấp, theo dõi thay đổi phá vỡ, làm rõ vai trò control plane [8][9]. Với tòa soạn, agent chuẩn bị, con người quyết định; cơ chế approval ghi lại quyết định ấy chứ không thay nó [11].
Bước kế tiếp hợp lý là một thử nghiệm nhỏ, ghim phiên bản, đo trên dữ liệu tiếng Việt của chính đơn vị.
Nguồn tham khảo, commit và giới hạn của nghiên cứu
Agno vào chuỗi “100 nghiên cứu ứng dụng về mã nguồn mở xuất hiện trong GitHub Trending năm 2026” nhờ một quan sát trong kho lưu độc lập các trang GitHub Trending: ngày 01/02/2026, danh sách Python xếp kho ở vị trí thứ 9 [12]. Dữ liệu tuyển chọn của chuỗi ghi ba lần quan sát, lần cuối ngày 04/10/2026. Kho lưu này chỉ chép bốn danh sách ngôn ngữ Python, Go, JavaScript, Swift và vắng hai ngày 03/09, 12/10, nên không thể coi là bảng Top 100 chính thức.
Trang lưu trữ ngày đó mô tả kho là công cụ xây hệ thống đa agent biết học qua mỗi lần tương tác [12]; câu giới thiệu hiện tại là xây, chạy và quản trị nền tảng agent [1], cho thấy trọng tâm đã dịch về runtime. Mọi đối chiếu kỹ thuật dựa trên commit ccd1a0224ccda2a9c6d222a93311f12880f5430f (ngày commit 12/10/2026), kiểm tra ngày 12/10/2026, với README, hai tệp LICENSE, bảy tài liệu cookbook và hướng dẫn di chuyển v3.0 [2][3][4][5][6][7][8][9][10][11].
Phương pháp là đọc và đối chiếu tài liệu với sự hỗ trợ của AI: Agno không được cài, không được chạy, không bị đo hiệu năng trong quá trình viết, và bài không phải công trình khoa học qua phản biện. Số liệu chỉ lấy từ tệp nguồn; phần tòa soạn, chi phí, so sánh và kế hoạch thử là đề xuất. Tài liệu trên docs.agno.com cùng mã các kho mẫu nằm ngoài phạm vi đọc.