Vòng lặp agent

Một lượtLượtTurnMọi thứ từ lúc gửi tin nhắn đến khi nhận câu trả lời: kiểm tra, lệnh gọi mô hình, dùng công cụ, tạm dừng chờ bạn, và câu trả lời. Lượt vẫn chạy khi bạn đóng tab.Mở trong Thuật ngữ — một tin nhắn của bạn cùng mọi việc agent làm để trả lời nó — là một vòng lặp agentVòng lặp agentAgentic loopChu trình agent lặp lại trong một lượt: gọi mô hình, chạy công cụ mô hình yêu cầu, đọc kết quả, rồi gọi lại mô hình cho đến khi trả lời được.Mở trong Thuật ngữ: nhiều lần gọi mô hìnhLệnh gọi mô hìnhModel callMột yêu cầu gửi tới mô hình. Một lượt có thể gọi nhiều lần, và mỗi lần được ghi lại kèm chi phí riêng.Mở trong Thuật ngữ, không phải một. Câu trả lời không phải một chuỗi văn bản mà là danh sách các khối có kiểu, theo đúng thứ tự, và mọi agent đều chạy trên cùng một host dùng chung.

Quy tắc chính

1. Một host phục vụ mọi agent. Agent là một gói cấu hình được nạp ở mỗi lần gọi; tạo agent không bao giờ triển khai thêm runtime.
2. Tin nhắn là các khối có kiểu. Thinking, text, tool use và tool result, lưu theo thứ tự.
3. Bạn không bao giờ thấy chuỗi suy luận thô. Chỉ có tóm tắt suy luận, khối tool và phê duyệt, câu hỏi và văn bản cuối.
4. Chi phí ghi theo từng lần gọi mô hình, gom theo lượt khi hiển thị.
5. Không viết lại byte đã gửi. Mỗi lần gọi chỉ nối thêm, nhờ vậy prompt cache vẫn có hiệu lực.

Một host, nhiều agent

Agent của phòng ban hay agent cá nhân đều là dữ liệu trong cơ sở dữ liệu của portal: chỉ dẫn, danh sách tool được phép, tham chiếu kho tri thức và mô hình. Ở mỗi lần gọi, portal nạp gói đó và đưa vào một host tham số hoá duy nhất. Không có runtime riêng cho từng agent, nên tạo, sửa hay xoá agent đều không triển khai gì cả.

Gói cấu hình gồm những gì và từng phần đến host bằng cách nào được liệt kê ở Cấu hình agent.

Một lượt lặp như thế nào

Mỗi vòng bắt đầu bằng một lần gọi mô hình, và lý do dừng của lần gọi đó quyết định bước tiếp theo:

Mô hình dừng vì…	Vòng lặp làm gì
Cần dùng tool (tool_use)	Chạy tool nếu được phép, nối kết quả tool vào, rồi gọi mô hình lần nữa. Với Ask before each action (hỏi trước mỗi thao tác), trước hết lưu một yêu cầu phê duyệt và tạm dừng đến khi có người duyệt.
Cần bạn trả lời (câu hỏi làm rõ)	Lưu câu hỏi, tạm dừng, rồi tiếp tục đúng nhiệm vụ đó bằng một lần gọi mô hình mới khi bạn trả lời.
Đã xong (end_turn)	Văn bản cuối là câu trả lời. Lượt kết thúc.
Giới hạn của nhà cung cấp hoặc lỗi	Lượt bị bỏ dở.

Cách tạm dừng hoạt động — ai quyết định, thẻ hiển thị gì, từ chối thì sao — có ở Thực thi agent.

Vòng lặp tuân theo vài quy tắc:

Quy tắc	Chi tiết
Khối có kiểu	Thinking, text, tool_use và tool_result được lưu theo thứ tự, để lịch sử phát lại được và giao diện vẽ được hoạt động của tool.
Những gì bạn thấy	Tóm tắt suy luận an toàn, khối tool và phê duyệt, yêu cầu làm rõ và văn bản cuối. Không có gì khác.
Chi phí theo lần gọi	Mọi lần gọi mô hình đều được ghi. Chat gom các lần gọi theo lượt để hiển thị; nhật ký kiểm tra và chat giữ thời hạn lưu trữ riêng.
Ai điều khiển vòng lặp	SDK của agent nắm vòng lặp tool. Hoàn tất thì kết thúc lượt, ngắt thì tạm dừng, lỗi nhà cung cấp thì để lượt dở dang. Runtime không đặt giới hạn số bước, cũng không giới hạn tổng token.
Tín hiệu sống	Khi một lần gọi mô hình đang suy luận mà chưa tạo ra gì khác, runtime gửi nhịp heartbeat. Portal gia hạn thời hạn chờ theo nhịp đó và không lưu lại gì.
Bỏ dở	Nếu không còn ai đọc, chính lần gọi mô hình bị huỷ — không chỉ vòng lặp bao quanh — để lượt không ai đọc ngừng bị tính tiền. Mỗi lời gọi tới portal cũng mang thời hạn riêng vì cùng lý do.
Hướng dẫn runtime	Một đoạn ngắn được gộp vào system prompt của agent, trả phí ở mọi lần gọi mô hình (bốn đến sáu lần mỗi lượt). Xem Vì sao lại như vậy.

Tiến trình và câu trả lời

• Văn bản viết ra trong một vòng có dùng tool sau đó được giữ thành khối riêng, không bao giờ ghép vào câu trả lời — nên một lượt đã thử, thất bại rồi thử lại vẫn giữ nguyên dấu vết đó.
• Lượt hiển thị theo thứ tự khối: công việc, câu mô tả công việc đó, thêm công việc, rồi câu trả lời.
• Khi đã có câu trả lời, phần tường thuật phía trên thu nhỏ một cỡ và nhạt màu đi, ngay tại chỗ. Khi lượt còn chạy — và ở lượt kết thúc mà không trả lời — phần tường thuật giữ nguyên cỡ.
• Câu hỏi làm rõ là một lần tạm dừng được lưu: câu hỏi và câu trả lời của bạn được lưu trước khi đúng nhiệm vụ đó tiếp tục.
• Mỗi vòng gửi lại lịch sử cùng kết quả tool, nên ngữ cảnh tăng nhanh hơn tuyến tính. Cache phần đầu ổn định là cách kiểm soát chi phí chính; nó được bật trên mô hình đang phục vụ, không theo từng lần gọi. Xem Danh mục mô hình và Danh sách tin nhắn.
• Khi lần gọi tiếp theo sẽ lấp đầy 85% cửa sổ ngữ cảnh của mô hình, lượt sẽ thay lịch sử bằng một bản tóm tắt (nén ngữ cảnh) rồi chạy tiếp. Xem Dựng prompt.

Tóm tắt suy luận

Suy luận của mô hình không bao giờ rời khỏi runtime. Thay vào đó, mô hình nền của tổ chức viết vài câu, ngay trong runtime, về những gì trợ lý đã cân nhắc và quyết định: mỗi lượt một tóm tắt suy luậnTóm tắt suy nghĩThinking summaryMô tả ngắn, an toàn về điều agent đang cân nhắc, hiện trong lúc nó làm việc. Suy luận thô của mô hình không bao giờ được hiển thị.Mở trong Thuật ngữ, viết trong lúc câu trả lời vẫn đang đến.

• Tổ chức không có mô hình nền thì không có tóm tắt — và cũng không báo lỗi.
• Báo cáo sử dụng ghi tên mô hình đã viết tóm tắt, và portal tính giá lần gọi đó như một việc riêng.

Kết thúc

Mô hình dừng ở đâu thì đó là câu trả lời, và văn bản cuối được truyền ra ngay khi đang viết. Hướng dẫn cho phép một lần tra cứu không có kết quả kết thúc lượt. SDK chạy đến khi mô hình xong, bạn dừng nó, hoặc lỗi làm gián đoạn.

Điều xảy ra	Kết quả
Chạm giới hạn đầu ra của nhà cung cấp trong câu trả lời	Ghi nhận là agent_output_limit_exceeded. Lượt sau nhận được lý do lỗi đó, kể cả khi không có khối hoàn chỉnh nào được lưu.
Chạm giới hạn khi mô hình đang viết tham số của lời gọi tool	Các lời gọi đó trả về dưới dạng kết quả thất bại kèm lý do, và mô hình gửi lại. Không có gì phía sau chạy, vì tham số chưa bao giờ được tin dùng.
Tham số lời gọi tool không bao giờ đến dưới dạng JSON hợp lệ	Runtime giữ các khối mà phản hồi đã tạo, trả lời lời gọi không đọc được kèm lý do, và mô hình viết lại lời gọi.
Một trong hai trường hợp trên, mà phản hồi không nêu lời gọi nào	Lỗi dừng hẳn: phần bị cắt chính là câu trả lời, chạy tiếp sẽ lưu nửa câu làm câu trả lời của lượt.

Mức suy luận

Một lượt chạy ở một trong bốn mức suy luận. Người tạo agent chọn mức, và từng tin nhắn có thể ghi đè (xem Mô hình và mức suy luận). Mức suy luận quyết định số token suy luận cho mỗi lần gọi mô hình:

Mức	Token suy luận mỗi lần gọi
OFF	0 — tắt suy luận
LOW	1.024
MEDIUM	4.096
HIGH	16.384

• Mô hình không hỗ trợ suy luận thì không nhận ngân sách suy luận ở bất kỳ mức nào.
• Mỗi lần gọi được dùng dung lượng đầu ra công bố của mô hình trong danh mục mô hình, tính cả phần suy luận. Ngân sách suy luận luôn nhỏ hơn hẳn dung lượng đó, theo yêu cầu của nhà cung cấp.
• Portal không thêm giới hạn đầu ra theo agent hay theo bản triển khai, không giới hạn số bước, không giới hạn tổng token.
• Mã được sinh ra không bị portal giới hạn số ký tự, ở cả ranh giới tool lẫn API.
• Cửa sổ lịch sử, bản xem trước kết quả tool, ngân sách phòng ban, việc huỷ và thời hạn truyền tải vẫn áp dụng như thường.

Lập kế hoạch cho việc nặng

Lượt lập kế hoạch nhiều hay ít tuỳ yêu cầu:

Yêu cầu	Kế hoạch
Trả lời được bằng một hai lần tra cứu	Không cần
Việc rõ ràng, ba đến năm bước	Một danh sách việc
Việc lớn hoặc mơ hồ — báo cáo từ nhiều nguồn, một bộ slide	Bản đặc tả → kế hoạch → danh sách việc

Bản đặc tả và kế hoạch là các tệp bình thường trong không gian làm việc của cuộc hội thoại, spec.md và plan.md, do hai skill dựng sẵn viết:

• brainstorming đọc yêu cầu và các nguồn rồi viết bản đặc tả. Skill này chỉ đặt câu hỏi làm rõ khi câu trả lời làm thay đổi thứ sẽ được bàn giao.
• writing-plans biến bản đặc tả thành các việc, mỗi việc nêu đầu vào, đầu ra và cách kiểm tra.

Cả hai đều không dừng chờ phê duyệt. Bản thân danh sách việc không phải tệp; nó do tool update_tasks giữ, được mô tả ở Artifact và skill.

Danh sách tin nhắn

Một số hook có thể thay đổi những gì lượt gửi cho mô hình:

• bộ thu thập bằng chứng mà báo cáo được đối chiếu;
• phần nén thay thế một kết quả tool dài;
• phần cắt bớt tham số tài liệu sau khi thao tác ghi đã chạy;
• phần phục hồi đánh dấu thất bại cho lời gọi mô hình chưa viết xong;
• phần sửa tham số của một lời gọi;
• bộ đọc nhận những gì bạn gõ trong khi lượt đang chạy (nhắn chen giữa lượt).

Chúng được gắn ở một chỗ, theo một thứ tự, và cùng một quy tắc: mỗi lần gọi mô hình chỉ thêm tin nhắn, không bao giờ viết lại byte mà lần gọi trước đã gửi.

Vì sao phần đầu quan trọng

Prompt cache của gateway khớp theo phần đầu không đổi đó. Một hook sửa tin nhắn cũ sẽ khiến mọi lần gọi sau phải trả lại cho toàn bộ ngữ cảnh, theo giá ghi cache thay vì giá đọc cache rẻ hơn. Phần cắt tài liệu tuân thủ quy tắc bằng cách chạy sớm: cắt tham số trước lần gọi đầu tiên mang nó.

Thả bớt hình ảnh

Hình ảnh là ngoại lệ có chủ đích. Lưu một tệp đòi hỏi kiểm tra từng trang, mỗi trang đến dưới dạng một hình, và hình ở lại trong danh sách suốt phần còn lại của lượt — nên một tài liệu 37 trang sẽ đưa 37 hình vào mọi lần gọi sau. Khi một lượt giữ hơn hai mươi hình, nhà cung cấp giới hạn mỗi hình ở 2.000 điểm ảnh mỗi cạnh và từ chối lần gọi có hình lớn hơn.

Vì vậy khi một lần gọi sắp mang hơn hai mươi hình:

1. Hình trong mọi kết quả tool, trừ kết quả mới nhất, được thay bằng một ghi chú rằng chúng đã được xem và có thể kiểm tra lại.
2. Thao tác lưu vẫn qua được, vì hồ sơ kiểm tra mà nó dựa vào nằm trong runtime.
3. Hình bạn đính kèm không bao giờ bị thả.
4. Riêng lần gọi đó phải trả lại cache; sau đó danh sách lại tăng bằng cách nối thêm đến khi vượt hai mươi lần nữa.

Cấu hình agent

Gói được lưu gồm: chỉ dẫn, mô hình, danh sách tool được phép, tham chiếu skill, liên kết kho tri thức, chính sách bộ nhớ và phạm vi hiển thị. Portal lấy giao với quyền truy cập thực tế của bạn trước khi host chạy — xem Xác định quyền truy cập.

Phần	Đến host bằng cách nào
System prompt, mô hình, tham số lấy mẫu, cờ bộ nhớ	Trong payload của lần gọi.
Danh sách tool được phép	Một lời gọi riêng. Host chỉ đăng ký những tool được báo, không có tool tuỳ chọn nào nếu lời gọi đó thất bại, và không bao giờ quảng bá tool mà portal không nêu tên.
Id kho tri thức	Không bao giờ được gửi. Phía máy chủ xác định cho từng lần tìm kiếm, từ các liên kết của lượt, thu hẹp theo quy tắc của chính bạn.
Danh mục skill tuỳ chỉnh	Tên và mô tả bạn được phép xem, do backend cung cấp. Skill chọn bằng /slug đưa chỉ dẫn vào trực tiếp; chỉ dẫn tuỳ chỉnh khác được nạp qua backend có kiểm tra quyền.
Skill dựng sẵn	Có sẵn trong image agent dưới skills/, liệt kê dạng builtin:<slug> và nạp cục bộ, không có dòng cơ sở dữ liệu hay liên kết. Runtime gộp cả hai danh mục.
Các liên kết khác	Phạm vi hiển thị được chốt khi lượt bắt đầu, trước khi gọi host.

Truyền dữ liệu có thể nối lại

Bạn có thể tải lại trang hay mất kết nối giữa lượt mà không mất công việc:

• Sự kiện của agent đi vào Redis Streams và đến trình duyệt dưới dạng server-sent events (SSE). Lịch sử và các khối đã hoàn tất được lưu bền trong PostgreSQL; Redis chỉ là bộ đệm phát lại cho lần chạy đang diễn ra.
• Mỗi lượt có một run id cố định và mỗi sự kiện một số thứ tự, nên khi kết nối lại sẽ tiếp tục đúng sau sự kiện cuối cùng trình duyệt đã nhận.
• Việc lưu loại trùng theo tin nhắn và số thứ tự, nên một sự kiện phát lại không thay đổi gì và không lặp lại tác dụng phụ nào.

Toàn bộ cơ chế — con trỏ, cửa sổ phát lại, khung quá lớn và lần chạy bị bỏ dở — có ở Vòng đời của một lượt.

Vì sao lại như vậy

Bên trong hệ thống

Liên quan