AgentScope – Nền Tảng AI Agent Nội Bộ Của Ecomobi

April 2026
M	T	W	T	F	S	S
	1	2	3	4	5
6	7	8	9	10	11	12
13	14	15	16	17	18	19
20	21	22	23	24	25	26
27	28	29	30

Từ “paste data lên ChatGPT” đến AI agent bảo mật, kết nối dữ liệu nội bộ, không cần IT — được xây dựng và vận hành hoàn toàn bởi Ecomobi.

Tổng Quan

AgentScope là GPTs / Gems — nhưng chạy bên trong Ecomobi, kết nối thẳng vào hệ thống nội bộ.

Vấn Đề Trước Đây	AgentScope Giải Quyết Như Thế Nào
Data rò rỉ — nhân viên tự paste data lên ChatGPT public	Toàn bộ chat đi qua hệ thống Ecomobi kiểm soát, data nội bộ không bao giờ bị đẩy raw ra ngoài
Phụ thuộc IT — muốn AI đọc database phải chờ dev viết code	Admin gắn sẵn MCP data source, user chọn tool khi tạo agent — không cần code
Không scale — mỗi phòng ban dùng tool AI riêng, không đo được	Agent library dùng chung, evaluation system đo chất lượng bằng metric thực

Quy trình sử dụng cơ bản: Đăng nhập → Chọn / Tạo Agent → Chat → Xuất Report

Bước 1: Đăng Nhập & Khám Phá Agent Library

Đăng Nhập

Truy cập URL nội bộ AgentScope → bấm Sign in with Google → chọn tài khoản @ecomobi.com.

Email ngoài domain công ty sẽ bị từ chối ngay tại bước xác thực — không cần nhớ mật khẩu riêng, không cần tạo tài khoản mới.

Khám Phá Agent Library

Vào menu Agents để xem danh sách agent mà các team khác đã chia sẻ. Mỗi agent có description rõ ràng — đọc để hiểu agent làm được gì, thử chat vài câu để cảm nhận trước khi dùng thật.

Visibility của Agent	Ai Nhìn Thấy
`private`	Chỉ mình bạn
`role`	Những người cùng role được admin cấp
`shared`	Toàn bộ nhân viên Ecomobi

💡 Tip: Đừng vội tạo agent mới nếu chưa browse library — rất có thể đồng nghiệp đã build sẵn một agent phù hợp với đặc thù công việc của bạn.

Bước 2: Hiểu Cách Agent Suy Luận — ReAct Loop

Đây là phần quan trọng nhất để dùng AgentScope hiệu quả. Agent không “đọc câu hỏi rồi trả lời ngay” như một chatbot thông thường — nó chạy vòng lặp Reason → Act → Observe cho đến khi có đủ thông tin.

Vòng Lặp ReAct Trong Thực Tế

User: "Doanh thu affiliate tuần này theo kênh là bao nhiêu?"

Iteration 1:
  REASON → "Câu hỏi này cần data từ hệ thống. Tôi sẽ gọi
            tool affiliate_stats với date range của tuần này."

  ACT    → affiliate_stats(date_from="2026-04-07",
                           date_to="2026-04-13",
                           group_by="channel")

  OBSERVE → {Google: 45M, Facebook: 30M, TikTok: 12M, ...}

  REASON → "Đã có đủ data. Tôi sẽ format thành bảng và trả lời."

FINAL ANSWER → stream về frontend

Mỗi bước được hiển thị real-time qua ThinkingCard (icon 🧠) trong chat UI — bạn thấy agent đang nghĩ gì, gọi tool nào, nhận kết quả gì, trước khi câu trả lời cuối xuất hiện. Thay vì “tin mù quáng”, bạn có thể kiểm tra từng bước logic của AI.

5 Thành Phần Cấu Hình Một Agent

Khi tạo agent, bạn đang quyết định 5 thứ sau:

Thành Phần	Vai Trò	Ví Dụ
System Prompt	Nhân cách, phạm vi, hành vi	“Bạn là trợ lý phân tích doanh thu Ecomobi…”
Model	LLM nào xử lý reasoning	Claude Sonnet, GPT-4o, Gemini 2.5 Flash
MCP Tools	Kết nối data nội bộ	`affiliate_stats`, `query_database`, REST APIs
Sub-Agents	Agent con chuyên biệt, gọi như tool	Agent tóm tắt, Agent dịch thuật
Skills	Hướng dẫn quy trình dạng text (SKILL.md)	“Khi user hỏi doanh thu, làm theo các bước…”

💡 Tip: Bật Enable reasoning khi tạo agent để thấy toàn bộ vòng lặp ReAct trong ThinkingCard. Với tác vụ phân tích quan trọng, đây là cách kiểm tra logic AI trước khi tin vào kết quả.

Bước 3: Viết System Prompt Hiệu Quả

System prompt là “bộ não” của agent — model đọc nó trước mỗi lượt suy luận, nên nó ảnh hưởng trực tiếp đến chất lượng output.

Cấu Trúc Khuyến Nghị

# [Tên vai trò]
Mô tả một câu: agent này là ai, làm gì, phục vụ ai.

## Phạm vi
- Những gì agent NÊN làm (bullet points)
- Những gì agent KHÔNG làm (boundary rõ ràng)

## Quy trình xử lý
Các bước cụ thể cho task chính của agent.

## Định dạng output
- Trả lời bằng tiếng Việt, trừ technical terms.
- Số liệu luôn kèm đơn vị (VND, %, ...).
- Dùng markdown table khi có dữ liệu dạng bảng.

Các Lỗi Thường Gặp

Lỗi	Triệu Chứng	Cách Sửa
Quá mơ hồ	Agent trả lời chung chung, không đúng phạm vi	Thêm ví dụ cụ thể và boundary rõ ràng
Quá dài, nhồi nhét	Agent bỏ qua một số instruction	Ưu tiên rule quan trọng nhất, dùng bullet points
Không khai báo output format	Mỗi lần format khác nhau	Khai báo rõ: table, bullet, markdown, ngôn ngữ
Thiếu boundary	Agent “giúp” những việc không liên quan	Thêm mục “Khi nào không xử lý”
Thiếu context về tool	Agent không biết khi nào gọi tool nào	Mô tả ngắn mỗi tool và trigger condition

Ví Dụ Thực Tế — Agent Phân Tích Affiliate

❌ Vague:
"Bạn là trợ lý thông minh, hãy giúp tôi phân tích data."

✅ Cụ thể:
# Affiliate Analytics Assistant
Bạn là trợ lý phân tích hiệu suất affiliate cho team
Performance Marketing và Finance của Ecomobi.

## Phạm vi
- Truy vấn: clicks, conversions, doanh thu, ROI
- So sánh theo kênh, chiến dịch, publisher, khoảng thời gian
- Nhận xét ngắn về trend (tăng/giảm so với kỳ trước)

## Ngoài phạm vi
- Không thực hiện thay đổi dữ liệu (chỉ đọc)
- Không xử lý câu hỏi HR, IT, vận hành không liên quan affiliate

## Output format
- Ngôn ngữ: tiếng Việt
- Số tiền: VND, format có dấu phẩy (1,234,567 VND)
- Luôn ghi rõ khoảng thời gian trong tiêu đề bảng

💡 Tip: Viết system prompt ngắn để định nghĩa nhân cách + boundary tổng quát. Đẩy quy trình nghiệp vụ chi tiết vào Skill riêng — khi quy trình thay đổi, chỉ cần cập nhật SKILL.md mà không phải sửa từng agent.

Link tham khảo: Anthropic Prompting Guide

Bước 4: Gắn Tool & Kết Nối Data Nội Bộ (MCP)

MCP (Model Context Protocol) là cách agent kết nối ra ngoài context window — gọi database, đọc REST API, lấy dữ liệu real-time. Thay vì copy-paste số liệu vào chat, agent tự gọi tool để lấy data mới nhất.

Cách MCP Hoạt Động Trong AgentScope

Agent reasoning: "Tôi cần gọi tool affiliate_stats"
         │
         ▼
engine/MCPManager ──► MCP Server (nội bộ Ecomobi)
         │                    │
         │              Query database / API
         │                    │
         ◄── Tool Result ──────┘
         │
         ▼ (sanitized, tối đa 2000 chars)
Inject vào context của ReAct → iteration tiếp theo

Lưu ý bảo mật: Chỉ có engine Python mới kết nối MCP — frontend không bao giờ chạm vào MCP server trực tiếp. Tool result được sanitize và truncate trước khi đưa vào context model, đảm bảo raw data nội bộ không bao giờ leak ra ngoài.

RBAC — Tại Sao Tôi Không Thấy Tool X?

Không phải mọi người thấy cùng một danh sách tool. RBAC giới hạn theo role:

Finance role   → Được gọi tool đọc báo cáo doanh thu
Agency role    → Được gọi tool đọc data campaign TikTok
Admin          → Bypass tự động, thấy toàn bộ tool

Nếu cần tool mà không thấy trong selector → liên hệ admin để được cấp quyền thêm.

Workflow Admin Thêm MCP Tool Mới

Vào Admin → MCP Servers → thêm server với URL và auth token
Enable server → engine tự discover danh sách tool
Vào Admin → Tool Permissions → cấp tool cho role phù hợp
User thấy tool trong selector khi tạo/sửa agent

💡 Tip: Chỉ gắn tool thực sự cần thiết cho nhiệm vụ của agent. Agent ít tool nhưng đúng mục đích sẽ hoạt động chính xác hơn agent gắn quá nhiều tool không liên quan.

Bước 5: Sub-Agents & Skills — Nâng Cao

Sub-Agents — Uỷ Quyền Cho Chuyên Gia

Sub-agent là một agent độc lập được bọc thành tool, để orchestrator agent gọi như gọi bất kỳ tool nào. Dùng khi một task quá phức tạp để xử lý trong một agent, hoặc cần tư duy chuyên biệt theo từng domain.

Ví dụ kiến trúc multi-agent:

Orchestrator Agent (GPT-4o)
  system_prompt: "Nhận yêu cầu báo cáo tổng hợp, điều phối các agent con"
  tools:
    - ask_data_analyst  → Sub-agent: truy vấn số liệu từ MCP tools
    - ask_writer        → Sub-agent: viết narrative từ số liệu
    - ask_translator    → Sub-agent: dịch output sang ngôn ngữ yêu cầu

Khi orchestrator gọi sub-agent, UI hiển thị SubAgentCard (icon 🤖) — khác với ToolCallCard (icon 🔧) của MCP tools — để bạn phân biệt được “agent đang gọi tool data” hay “agent đang nhờ agent con xử lý”.

Khi nào dùng sub-agent thay vì MCP tool:

Dùng MCP Tool	Dùng Sub-Agent
Query database, gọi REST API	Task cần LLM reasoning phức tạp
Lấy dữ liệu có cấu trúc cố định	Cần system prompt và model riêng
Kết quả trả về nhanh, deterministic	Task có thể song song, dispatch cho nhiều agent

Skills — Hướng Dẫn Quy Trình Dạng Text

Skill là file SKILL.md chứa hướng dẫn step-by-step mà agent đọc tại runtime. Khác với system prompt viết một lần trong agent config, skill có thể tái sử dụng giữa nhiều agent và cập nhật tập trung mà không cần sửa từng agent.

Cách skill hoạt động:

Agent nhận task → REASON:
  "Task này liên quan đến affiliate report.
   Tôi sẽ đọc SKILL.md trước."
         │
         ▼
view_text_file("ecomobi-affiliate-report/SKILL.md")
         │
         ▼
Agent đọc quy trình → thực hiện đúng từng bước

So sánh System Prompt vs Skill:

	System Prompt	Skill (SKILL.md)
Scope	Toàn bộ agent, mọi task	Một loại task cụ thể
Thay đổi	Phải sửa từng agent	Cập nhật một file, áp dụng cho tất cả agent dùng skill đó
Tái sử dụng	Không (gắn liền với agent)	Có — nhiều agent share cùng skill
Khi nào dùng	Nhân cách, giọng điệu, boundary tổng quát	Quy trình nghiệp vụ chi tiết theo loại request

💡 Tip: Khi một quy trình nghiệp vụ được nhiều agent cần dùng (ví dụ: cách lấy báo cáo affiliate), hãy đưa vào SKILL.md. Khi quy trình thay đổi, chỉ cần update một file — không đụng đến agent config nào cả.

Bước 6: Chat, Xuất Report & Clone Agent

Chat Với Agent

Bấm vào agent → gõ câu hỏi → kết quả hiển thị real-time token-by-token qua SSE streaming. Trong chat, bạn sẽ thấy 3 loại card:

Card	Icon	Hiển Thị Gì
ThinkingCard	🧠 Brain	Từng bước reasoning của AI (collapsible)
ToolCallCard	🔧 Wrench	Tool đang được gọi, status, result
SubAgentCard	🤖 Bot	Khi agent chính gọi thêm sub-agent

Agent cũng có long-term memory theo từng cặp (agent, user) — nhớ ngữ cảnh từ các cuộc hội thoại trước, không cần giải thích lại bối cảnh mỗi lần chat mới.

Xuất Report PDF

AgentScope tự detect khi agent trả về dữ liệu dạng bảng. Nút Create Report xuất hiện dưới message — bấm vào để mở trang report với DataTable (filter + sort) và biểu đồ tự động (Recharts). Bấm Export PDF để tải về dùng ngay cho meeting hoặc email.

💡 Tip: Để report có đủ biểu đồ, yêu cầu agent trả về bảng với cột số liệu rõ ràng. Ví dụ: “Trả về bảng gồm các cột: SKU, GMV, GPM, AOV, số đơn.”

Clone Agent Của Người Khác

Tình Huống	Nên Làm Gì
Muốn dùng agent của đồng nghiệp, không cần chỉnh	Chat trực tiếp, không cần clone
Muốn chỉnh system prompt / model / tool list	Clone → sửa trong workspace riêng
Muốn lấy làm starting point cho team	Clone → cập nhật → đổi visibility thành `shared`

Dành Cho Admin — Quản Lý & Đánh Giá Chất Lượng

Công Cụ Admin

Tính Năng	Mô Tả
MCP Server CRUD	Thêm / sửa / xoá data source kết nối vào engine
Role & Tool Permissions	Cấp tool nào cho role nào
Menu Permissions Grid	Tick chọn menu nào role nào nhìn thấy
Evaluation System	Đo chất lượng agent bằng ACEBench

Evaluation System — Ra Quyết Định Bằng Metric Thực

Khi cần chọn giữa 2 cấu hình agent (khác model hoặc khác system prompt), đừng đoán mò:

Admin tạo evaluation run
         │
Chọn agent + bộ test case chuẩn (ACEBench)
         │
Hệ thống trả về:
  • Accuracy        → Kết quả cuối đúng không?
  • Process Accuracy → Agent đi đúng luồng không?
         │
So sánh metric giữa các agent/model → Ra quyết định

Best Practices Summary

DO ✓

Browse Agent Library trước khi tạo mới — tránh làm lại việc đã có
Viết system prompt có cấu trúc rõ ràng — vai trò, phạm vi, output format, boundary
Bật reasoning với tác vụ phân tích quan trọng — kiểm tra logic AI qua ThinkingCard
Đẩy quy trình nghiệp vụ vào SKILL.md — tái sử dụng và cập nhật tập trung
Clone và chia sẻ agent đã được cải thiện — đổi visibility sang shared để cả team hưởng lợi

DON’T ✗

Paste data nội bộ nhạy cảm lên ChatGPT public khi đã có AgentScope
Gắn quá nhiều tool không liên quan vào một agent
Dùng system prompt vague kiểu “hãy giúp tôi làm việc hiệu quả hơn”
Nhồi nhét toàn bộ quy trình nghiệp vụ vào system prompt thay vì dùng Skill
Giữ agent hay ở visibility private — chia sẻ để cả team được lợi

FAQ Nhanh

Dữ liệu có bị gửi ra ngoài không? Prompt chat sẽ đến LLM provider (Anthropic / OpenAI / Google) để sinh response — điều này không tránh được khi dùng API LLM. Nhưng dữ liệu nội bộ từ MCP tool không bao giờ bị đẩy raw lên LLM — engine sanitize result trước khi inject vào context.

Tại sao không thấy tool X? RBAC giới hạn tool theo role. Liên hệ admin để được cấp quyền thêm.

Agent có nhớ conversation trước không? Có — long-term memory lưu theo từng cặp (agent, user). User mới thì memory rỗng, agent vẫn chạy bình thường.

Khi nào dùng sub-agent thay vì MCP tool? Khi task cần LLM reasoning phức tạp, hoặc cần agent con có system prompt và model riêng biệt.

Khi nào nên clone thay vì dùng trực tiếp? Khi muốn chỉnh system prompt, model, hoặc tool list mà không ảnh hưởng bản gốc của người khác.

Làm sao biết agent nào hoạt động tốt hơn? Dùng Evaluation System (admin): tạo evaluation run với ACEBench, so sánh metric Accuracy và Process Accuracy giữa các cấu hình.

Checklist Bắt Đầu

□ Đăng nhập bằng tài khoản @ecomobi.com
□ Browse Agent Library trước khi tạo mới
□ Hiểu vòng lặp ReAct — bật reasoning để xem ThinkingCard
□ Viết system prompt có cấu trúc: vai trò + phạm vi + output format
□ Chỉ gắn tool thực sự cần thiết, không gắn thừa
□ Đẩy quy trình nghiệp vụ phức tạp vào SKILL.md
□ Clone agent hay → chỉnh → đổi visibility thành shared
□ Export PDF khi cần gửi report cho meeting / email

Core Value: Nhân viên Ecomobi tự tạo và sử dụng AI agent kết nối vào dữ liệu nội bộ — không cần IT can thiệp, không rò rỉ dữ liệu ra ngoài.

Calendar