Agent Spec là gì? Mẫu giao việc rõ ràng cho một AI Agent

Agent Spec là bản đặc tả xác định một AI agent được giao mục tiêu gì, đóng vai trò nào, được làm những việc gì, dùng dữ liệu và công cụ nào, phải tạo đầu ra ra sao, có giới hạn gì và được đánh giá theo tiêu chuẩn nào. Spec càng rõ, agent càng ít phải tự đoán phạm vi công việc.

Cách hiểu này phù hợp với cấu trúc của các agent framework hiện đại. OpenAI Agents SDK mô tả một agent là mô hình được cấu hình bằng instructions, tools và các hành vi bổ sung như handoffs, guardrails hoặc structured outputs.

Trong tài liệu P2.1 Brain Engineer – Non-IT Track, FUNiX cũng đặt trọng tâm vào việc cá nhân hóa assistant bằng thông tin nền, phong cách, preference, memory/reference files và giới hạn hành động; workflow được xác định bằng input, procedure/skill, trigger, output, evidence và human approval. Đây là nền tảng rất gần với tư duy viết một Agent Spec có kiểm soát.

Agent Spec không phải chỉ là một prompt dài

Một lỗi dễ gặp là coi Agent Spec như một đoạn prompt mô tả:

Bạn là một trợ lý chuyên nghiệp. Hãy làm việc cẩn thận và trả lời chính xác.

Đoạn này có thể là một phần của instruction, nhưng chưa đủ để trở thành một spec tốt.

Nó chưa trả lời:

• Agent đang tối ưu cho mục tiêu nào?
• Nhiệm vụ nào thuộc phạm vi của agent?
• Agent được truy cập dữ liệu nào?
• Có được gửi email, sửa file hoặc ghi dữ liệu không?
• Input bắt buộc là gì?
• Output phải có cấu trúc ra sao?
• Trường hợp nào phải dừng?
• Thế nào được coi là kết quả đạt?

Trong OpenAI Agents SDK, instructions được dùng như system prompt của agent, còn tools quyết định những hành động agent có thể thực hiện. Structured outputs có thể ép đầu ra theo một schema thay vì chỉ trả văn bản tự do.

Vì vậy, một Agent Spec nên được xem là thiết kế công việc, còn instruction là phần chuyển thiết kế đó thành chỉ dẫn mà agent thực thi.

Vì sao cần viết Agent Spec trước khi giao việc cho AI Agent?

Agent càng có khả năng sử dụng tool và thực hiện hành động, việc chỉ nói “hãy giúp tôi” càng tạo nhiều khoảng trống để hệ thống tự suy đoán.

Một spec rõ giúp giải quyết bốn vấn đề.

Giảm sự mơ hồ

So sánh:

Hãy research đối thủ.

với:

Thu thập thông tin công khai về ba đối thủ được cung cấp, tập trung vào thay đổi sản phẩm trong 30 ngày gần nhất, lưu nguồn cho từng nhận định và không đưa ra kết luận nếu chưa có bằng chứng.

Hai yêu cầu đều cùng chủ đề, nhưng phiên bản sau cho agent biết rõ phạm vi, thời gian, evidence và điều không được làm.

Kiểm soát quyền hành động

AI agent khác một chatbot chỉ trả lời văn bản ở chỗ agent có thể được cấp tools để lấy dữ liệu hoặc thực hiện hành động. OpenAI Agents SDK mô tả tools là cơ chế cho phép agent lấy dữ liệu, chạy code, gọi API hoặc tương tác với máy tính.

Vì vậy, spec cần xác định rõ:

được đọc gì → được tạo gì → được sửa gì → hành động nào cần xin phép.

Kiểm tra được chất lượng

Nếu yêu cầu chỉ là:

Viết báo cáo tốt.

rất khó kết luận agent đã hoàn thành hay chưa.

Nếu spec quy định:

• Có executive summary.
• Mỗi phát hiện quan trọng có evidence.
• Không có nhận định vượt ngoài dữ liệu.
• Tách fact và recommendation.
• Ghi rõ phần chưa chắc chắn.

thì kết quả có thể review theo checklist.

Giữ con người ở điểm quyết định quan trọng

PD P2.1 Brain Engineer nhấn mạnh con người luôn giữ quyền kiểm soát và workflow cần có kiểm tra chất lượng, privacy, bảo mật, chi phí và phê duyệt cuối cùng.

Ở cấp framework, OpenAI Agents SDK cũng hỗ trợ human-in-the-loop để tạm dừng trước tool call nhạy cảm cho đến khi con người approve hoặc reject.

Agent Spec vì thế nên ghi rõ khi nào agent được tự làm và khi nào phải dừng.

Khung Agent Spec gồm những gì?

Một mẫu thực dụng có thể gồm tám thành phần.

Phần dưới đây đi lần lượt từng mục.

1. Mục tiêu: Agent phải tạo ra kết quả gì?

Mục tiêu trả lời:

Agent này tồn tại để làm gì?

Không nên viết mục tiêu bằng mô tả quá rộng như:

Hỗ trợ công việc marketing.

Thay vào đó:

Giúp Marketing Manager chuẩn bị bản research đối thủ hàng tuần có nguồn, nêu các thay đổi đáng chú ý và các câu hỏi cần con người xem xét.

Mục tiêu tốt thường chứa:

đối tượng phục vụ + kết quả + bối cảnh sử dụng.

Mục tiêu không cần liệt kê từng thao tác. Các thao tác nằm ở phần nhiệm vụ.

2. Vai trò AI Agent: Agent chịu trách nhiệm phần nào?

“Vai trò” giúp xác định góc nhìn và phạm vi trách nhiệm.

Ví dụ:

Bạn là Research Assistant hỗ trợ Marketing Manager tổng hợp thông tin công khai về đối thủ.

Tốt hơn:

Bạn là một AI thông minh biết mọi thứ về marketing.

Vai trò đầu tiên giới hạn đúng domain và người nhận kết quả. Vai trò thứ hai quá rộng, khiến agent khó biết đâu là phạm vi trách nhiệm.

PD P2.1 cũng nhấn mạnh việc giao đúng việc, đúng phạm vi và thiết lập assistant với ranh giới hành động rõ.

3. Nhiệm vụ: Agent thực sự phải làm những bước nào?

Phần nhiệm vụ chuyển mục tiêu thành công việc cụ thể.

Ví dụ với Research Agent:

1. Nhận danh sách đối thủ.
2. Tìm thông tin từ các nguồn được phép.
3. Trích xuất thay đổi liên quan đến sản phẩm.
4. Lưu nguồn cho từng phát hiện.
5. Loại nội dung không liên quan.
6. Tổng hợp kết quả.
7. Đánh dấu thông tin chưa đủ bằng chứng.

Nhiệm vụ nên dùng động từ có thể quan sát:

• Thu thập.
• Kiểm tra.
• So sánh.
• Phân loại.
• Tóm tắt.
• Tạo draft.
• Trích nguồn.
• Đánh dấu.

Tránh những yêu cầu khó đánh giá như:

• Hãy thông minh.
• Hãy suy nghĩ thật kỹ.
• Làm thật chuyên nghiệp.
• Tạo kết quả tốt nhất.

Các câu này có thể bổ trợ instruction nhưng không thay thế task definition.

4. Quyền hạn: Agent được phép làm đến đâu?

Đây là phần rất quan trọng khi agent có tool.

Một Agent Spec có thể phân quyền theo ba lớp:

Được đọc

Ví dụ:

• File do người dùng cung cấp.
• Website công khai.
• Thư mục research nội bộ đã được cấp quyền.

Được tạo hoặc sửa

Ví dụ:

• Tạo draft báo cáo.
• Tạo file trong thư mục nháp.
• Cập nhật bảng research.

Cần phê duyệt

Ví dụ:

• Gửi email.
• Xuất bản nội dung.
• Ghi dữ liệu vào hệ thống chính.
• Xóa file.
• Chia sẻ dữ liệu ra bên ngoài.

Tài liệu P2.1 yêu cầu assistant có giới hạn hành động rõ ràng, đồng thời đặt human approval vào workflow như một thành phần kiểm soát dữ liệu và kết quả.

Với các hệ thống hỗ trợ tool approval, hành động nhạy cảm còn có thể được chặn ở cấp thực thi, không chỉ ghi bằng instruction.

5. Input: Agent cần gì trước khi bắt đầu?

Một agent khó làm đúng nếu thiếu dữ liệu đầu vào nhưng vẫn được yêu cầu tự suy đoán.

Input nên ghi rõ:

• Dữ liệu bắt buộc.
• Dữ liệu tùy chọn.
• Format.
• Thời gian hoặc phạm vi.
• Nguồn nào được coi là hợp lệ.

Ví dụ:

Input bắt buộc

• Tên ba đối thủ.
• Thị trường cần theo dõi.
• Khoảng thời gian research.

Input tùy chọn

• Danh sách URL ưu tiên.
• Sản phẩm cần so sánh.
• Báo cáo tuần trước.

Nếu thiếu input bắt buộc

Không bắt đầu research. Yêu cầu người dùng bổ sung thông tin.

Đây là một giới hạn tốt hơn việc agent tự đoán tên đối thủ hoặc thời gian cần phân tích.

6. Output: Agent phải bàn giao kết quả thế nào?

Output càng rõ, việc đưa kết quả sang workflow tiếp theo càng đơn giản.

Ví dụ:

Output bắt buộc

1. Tóm tắt 5–7 dòng.
2. Bảng phát hiện:
   • Đối thủ.
   • Thay đổi.
   • Ngày.
   • Nguồn.
   • Mức độ liên quan.
3. Ba điểm cần theo dõi.
4. Phần “Chưa đủ bằng chứng”.
5. Danh sách nguồn.

Nếu hệ thống yêu cầu dữ liệu để phần mềm khác xử lý, structured output có thể hữu ích. OpenAI Agents SDK cho phép cấu hình output_type, khi đó agent sử dụng structured outputs thay vì chỉ trả plain text.

Với người dùng non-IT, không nhất thiết phải dùng JSON. Một bảng hoặc template Markdown cố định cũng có thể đủ nếu mục đích chính là con người đọc và review.

7. Giới hạn: Agent không được làm gì?

Giới hạn không nên chỉ có một câu:

Không làm điều nguy hiểm.

Hãy viết cụ thể.

Ví dụ:

• Không tự tạo fact nếu nguồn không có.
• Không dùng dữ liệu ngoài phạm vi được phép.
• Không gửi email.
• Không đăng nội dung.
• Không xóa dữ liệu.
• Không tự thay đổi danh sách đối thủ.
• Không kết luận “tốt nhất”, “lớn nhất”, “dẫn đầu” nếu không có dữ liệu hỗ trợ.
• Nếu hai nguồn mâu thuẫn, phải ghi nhận mâu thuẫn thay vì tự chọn một bên.
• Nếu thiếu input quan trọng, dừng và hỏi người dùng.

Các giới hạn này tương ứng với tinh thần của P2.1: kiểm soát chất lượng, privacy, bảo mật, quyền truy cập, chi phí và xử lý lỗi trong vận hành assistant.

Trong framework kỹ thuật, guardrails có thể được dùng để kiểm tra input hoặc output của agent, nhưng guardrail kỹ thuật không thay thế việc định nghĩa rõ ranh giới nghiệp vụ trong spec. OpenAI Agents SDK hỗ trợ input/output guardrails như một phần cấu hình agent.

8. Tiêu chuẩn chất lượng: Làm sao biết agent đã hoàn thành?

Đây là phần biến Agent Spec từ “mô tả” thành “yêu cầu có thể nghiệm thu”.

Ví dụ một report được coi là đạt khi:

• Mọi phát hiện quan trọng đều có nguồn.
• Nguồn thực sự hỗ trợ cho nhận định đi kèm.
• Không có dữ liệu tự suy đoán.
• Không trộn fact với recommendation.
• Có đánh dấu phần chưa chắc chắn.
• Output đúng format.
• Không vượt phạm vi thời gian được giao.
• Không thực hiện hành động cần human approval.

Có thể chia quality criteria thành bốn nhóm.

Correctness

Thông tin có đúng và có evidence không?

Completeness

Có thiếu mục bắt buộc nào không?

Format

Kết quả có đúng cấu trúc để người hoặc hệ thống tiếp theo sử dụng không?

Safety

Agent có tuân thủ quyền truy cập, privacy và approval không?

P2.1 Brain Engineer dùng chính tư duy này khi yêu cầu workflow có evidence, Quality & Safety Checklist và phê duyệt của con người.

Mẫu Agent Spec có thể dùng ngay

Dưới đây là một khung đơn giản để bắt đầu.

Tên Agent

1. Mục tiêu

Agent tồn tại để:

• [Kết quả chính]
• [Người sử dụng kết quả]
• [Bối cảnh sử dụng]

2. Vai trò

Bạn là:

• [Vai trò chuyên môn]
• Phục vụ: [người/nhóm]
• Chỉ chịu trách nhiệm cho: [phạm vi]

3. Nhiệm vụ

Agent phải:

1. […]
2. […]
3. […]
4. […]

4. Quyền hạn

Được phép đọc:

• […]

Được phép tạo/sửa:

• […]

Phải xin phê duyệt trước khi:

• […]

5. Input

Bắt buộc:

• […]

Tùy chọn:

• […]

Nếu thiếu input bắt buộc:

• [Dừng / yêu cầu bổ sung / dùng giá trị mặc định đã được quy định]

6. Output

Kết quả phải gồm:

1. […]
2. […]
3. […]

Format:

• [Bảng / Markdown / structured fields / file]

7. Giới hạn

Agent không được:

• […]
• […]
• […]

Agent phải dừng khi:

• […]
• […]

8. Tiêu chuẩn chất lượng

Output chỉ được coi là đạt nếu:

• ☐ Mọi nhận định quan trọng có evidence.
• ☐ Không thiếu phần bắt buộc.
• ☐ Không vượt phạm vi.
• ☐ Output đúng format.
• ☐ Các điểm không chắc chắn được ghi rõ.
• ☐ Hành động nhạy cảm đã có human approval.

Ví dụ Agent Spec: Research Assistant theo dõi đối thủ

Giả sử một Marketing Manager muốn dùng AI agent để chuẩn bị research hàng tuần.

Tên Agent

Competitor Research Assistant

Mục tiêu

Chuẩn bị bản research hàng tuần về những thay đổi đáng chú ý của các đối thủ được chỉ định để Marketing Manager đọc và quyết định bước tiếp theo.

Vai trò

Bạn là Research Assistant.

Bạn chịu trách nhiệm thu thập, kiểm tra và tổng hợp thông tin công khai về các đối thủ được cung cấp.

Bạn không chịu trách nhiệm đưa ra quyết định kinh doanh cuối cùng.

Nhiệm vụ

1. Nhận danh sách đối thủ và khoảng thời gian.
2. Kiểm tra các nguồn được phép.
3. Ghi nhận thay đổi liên quan đến sản phẩm, nội dung hoặc hoạt động được yêu cầu.
4. Lưu evidence cho từng phát hiện.
5. Loại kết quả trùng.
6. Tạo báo cáo.
7. Đánh dấu những điểm chưa thể xác minh.

Quyền hạn

Được phép:

• Đọc nguồn công khai.
• Đọc reference files do người dùng cung cấp.
• Tạo draft báo cáo.

Không được tự thực hiện:

• Gửi email cho đối thủ.
• Đăng nội dung.
• Thay đổi file gốc.
• Chuyển dữ liệu cho bên khác.

Mọi hành động bên ngoài việc research và tạo draft cần human approval.

Input

Bắt buộc:

• Danh sách đối thủ.
• Thị trường.
• Khoảng thời gian.
• Chủ đề cần theo dõi.

Nếu thiếu một trong bốn mục trên, yêu cầu bổ sung trước khi chạy.

Output

Báo cáo gồm:

1. Executive summary.
2. Bảng phát hiện.
3. Evidence/source cho từng phát hiện.
4. Điểm mới so với lần research trước nếu có dữ liệu đối chiếu.
5. Các vấn đề chưa xác minh.
6. Ba câu hỏi đề xuất để Marketing Manager xem xét.

Giới hạn

• Không tự tạo số liệu.
• Không suy đoán ý định của đối thủ.
• Không dùng nguồn không truy xuất được làm evidence chính.
• Không đưa thông tin ngoài khoảng thời gian được yêu cầu vào phần “thay đổi mới”.
• Không biến recommendation thành fact.

Tiêu chuẩn chất lượng

Bản research chỉ đạt khi:

• Mỗi phát hiện quan trọng có nguồn.
• Fact và nhận định được tách rõ.
• Không có dữ liệu không kiểm chứng được trình bày như sự thật.
• Không thiếu đối thủ nào trong input.
• Format đúng mẫu.
• Không thực hiện hành động vượt quyền.

Spec này không quyết định agent phải chạy lúc nào. Phần lịch chạy và quy trình lặp lại thuộc về workflow.

Agent Spec khác Workflow Spec như thế nào?

Hai khái niệm liên quan nhưng không nên trộn thành một.

Agent Spec

Trả lời:

Agent này là ai và được làm gì?

Nó tập trung vào:

• Mục tiêu.
• Vai trò.
• Nhiệm vụ.
• Quyền hạn.
• Input/output.
• Ranh giới.
• Tiêu chuẩn chất lượng.

Workflow Spec

Trả lời:

Công việc chạy như thế nào từ đầu tới cuối?

PD P2.1 mô tả workflow lặp lại bằng:

input → procedure/skill → trigger/lịch chạy → output → evidence, đồng thời có human approval và kiểm soát chất lượng.

Ví dụ:

Agent Spec nói:

Research Assistant được phép research đối thủ và tạo draft báo cáo.

Workflow nói:

8h thứ Hai → nhận danh sách đối thủ → research → tạo report → kiểm tra evidence → người dùng duyệt.

Một Agent có thể tham gia nhiều workflow.

Một workflow cũng có thể sử dụng nhiều agent.

Agent Spec khác “instruction cho agent” như thế nào?

Instruction là nội dung trực tiếp hướng dẫn model cách hành xử trong runtime.

OpenAI Agents SDK khuyến nghị cung cấp instructions cho agent và mô tả đây là system prompt của agent. Agent còn có thể được cấu hình thêm tools, handoffs, guardrails và output type.

Có thể hình dung:

Agent Spec = bản thiết kế

↓

Instruction + tool config + output schema + guardrails + approval rules = cách triển khai bản thiết kế

Ví dụ Agent Spec ghi:

Agent không được gửi email nếu chưa có người duyệt.

Khi triển khai, có thể có hai lớp:

Instruction

Luôn yêu cầu approval trước khi gửi.

Execution control

Tool gửi email được cấu hình yêu cầu human approval.

Lớp thứ hai giúp hạn chế việc chỉ dựa vào model “nhớ” instruction. OpenAI Agents SDK hỗ trợ cơ chế pause để người dùng approve hoặc reject sensitive tool calls.

Cách viết Agent Spec trong 7 bước

Bước 1: Bắt đầu từ một công việc cụ thể

Không bắt đầu bằng:

Tôi muốn một AI agent thật thông minh.

Hãy bắt đầu:

Tôi muốn một agent tạo draft báo cáo tuần từ dữ liệu bán hàng đã có.

Bước 2: Xác định tiêu chí hoàn thành trước

Hỏi:

Nhìn vào output, điều gì khiến tôi nói “task đã xong”?

Ví dụ:

• Có đủ 5 mục.
• Số liệu khớp nguồn.
• Có phần anomaly.
• Không tự gửi email.

Bước 3: Liệt kê input tối thiểu

Agent không thể làm đúng nếu input cần thiết chưa được xác định.

Hãy ghi rõ đâu là bắt buộc và đâu là tùy chọn.

Bước 4: Định nghĩa quyền truy cập

Với mỗi tool hoặc nguồn dữ liệu, quyết định:

• Read.
• Write.
• Execute.
• Approval required.
• Not allowed.

Bước 5: Chốt output trước khi viết instruction

Nếu output dùng cho con người, quy định headings hoặc bảng.

Nếu output được hệ thống khác xử lý, cân nhắc structured output. OpenAI Agents SDK hỗ trợ schema cho output thay vì bắt buộc dùng plain text.

Bước 6: Viết failure rules

Hãy xác định agent phải làm gì khi:

• Input thiếu.
• Tool lỗi.
• Không tìm được evidence.
• Hai nguồn mâu thuẫn.
• Task vượt quyền.
• Cần hành động nhạy cảm.

Không định nghĩa failure behavior đồng nghĩa để agent tự lựa chọn cách xử lý.

Bước 7: Test bằng tình huống thật

Chạy agent với:

• Case bình thường.
• Input thiếu.
• Input sai.
• Dữ liệu mâu thuẫn.
• Yêu cầu vượt quyền.
• Một hành động cần approval.

Sau mỗi lần test, sửa spec nếu vấn đề đến từ yêu cầu chưa rõ; đừng chỉ vá từng prompt riêng lẻ.

7 lỗi thường gặp khi viết Agent Spec

Lỗi 1: Chỉ định nghĩa persona

Bạn là chuyên gia research 20 năm kinh nghiệm.

Câu này không xác định task, input, output hay quyền hạn.

Role cần thiết, nhưng role không phải toàn bộ spec.

Lỗi 2: Mục tiêu quá rộng

Giúp tôi làm marketing.

Một agent như vậy phải tự quyết định quá nhiều thứ.

Hãy giảm phạm vi:

Tổng hợp thay đổi của ba đối thủ thành báo cáo hàng tuần.

Lỗi 3: Không xác định output

Nếu không có output format, mỗi lần chạy agent có thể bàn giao kết quả theo một cấu trúc khác.

Điều này đặc biệt gây khó khi output được dùng trong workflow lặp lại.

Lỗi 4: Cho quyền tool rộng hơn nhu cầu

Một agent chỉ cần đọc lịch để chuẩn bị brief cuộc họp không nhất thiết phải có quyền chỉnh sửa hoặc xóa sự kiện.

Quyền hạn nên bám đúng nhiệm vụ.

Lỗi 5: Không nói khi nào phải dừng

Agent cần biết:

• Thiếu input → hỏi lại.
• Không có evidence → không kết luận.
• Yêu cầu vượt quyền → từ chối thực hiện và báo người dùng.
• Hành động nhạy cảm → chờ approval.

Lỗi 6: Dùng tiêu chuẩn “tốt”, “chuyên nghiệp”, “đầy đủ”

Các từ này khó nghiệm thu.

Thay bằng tiêu chí quan sát được:

Mọi con số có nguồn, report có 5 phần, không vượt 1.000 từ, phần chưa xác minh nằm trong mục riêng.

Lỗi 7: Gộp Agent Spec và toàn bộ workflow vào một prompt khổng lồ

Spec nên định nghĩa agent tương đối ổn định.

Workflow định nghĩa cách agent được sử dụng cho một quy trình cụ thể.

Tách hai lớp này giúp dễ sửa, kiểm thử và tái sử dụng hơn.

Checklist kiểm tra một Agent Spec trước khi sử dụng

Một spec tương đối hoàn chỉnh khi bạn trả lời được:

1. Agent tồn tại để tạo kết quả gì?
2. Vai trò của agent là gì?
3. Những nhiệm vụ nào thuộc phạm vi?
4. Những nhiệm vụ nào không thuộc phạm vi?
5. Agent được truy cập nguồn dữ liệu nào?
6. Agent được phép sử dụng tool nào?
7. Tool nào chỉ được read?
8. Hành động nào cần human approval?
9. Input tối thiểu là gì?
10. Nếu thiếu input thì làm gì?
11. Output phải có cấu trúc nào?
12. Fact có cần evidence không?
13. Agent phải xử lý uncertainty thế nào?
14. Trường hợp nào agent phải dừng?
15. Tiêu chuẩn pass/fail của output là gì?

Nếu nhiều câu vẫn chưa có câu trả lời, vấn đề thường không nằm ở model mà nằm ở bản giao việc chưa đủ rõ.

Kết luận

Agent Spec là một khung giao việc giúp biến một AI agent từ “trợ lý làm mọi thứ” thành một thành phần có trách nhiệm, quyền hạn và tiêu chuẩn đầu ra rõ ràng.

Một spec thực dụng nên định nghĩa ít nhất:

mục tiêu → vai trò → nhiệm vụ → quyền hạn → input → output → giới hạn → tiêu chuẩn chất lượng.

Sau đó, spec có thể được chuyển thành instructions, tool permissions, output format, guardrails và approval rules tùy nền tảng triển khai. OpenAI Agents SDK hiện hỗ trợ chính các lớp cấu hình như instructions, tools, guardrails, handoffs và structured outputs.

Trong tư duy của P2.1 Brain Engineer, cấu trúc này cũng phù hợp với nguyên tắc cá nhân hóa assistant, xác định ranh giới hành động, thiết kế workflow có input/output/evidence và luôn giữ con người ở vị trí kiểm soát cuối cùng.