Hướng dẫn định tuyến tác vụ cho AI Agent với Gemini Decisions API

TL;DR

Để định tuyến các tác vụ của AI agent bằng Gemini Decisions API, hãy gửi tiêu đề và phần mô tả tác vụ tới gemini-decision-1 cùng ba câu hỏi: câu hỏi dạng choice để chọn Agent tiếp nhận, câu hỏi dạng score để đánh giá độ khó, và câu hỏi dạng noul để xác định liệu có cần con người quyết định trước hay không. Tự động giao việc khi độ tin cậy vượt qua ngưỡng bạn thiết lập. Giữ lại tất cả các trường hợp còn lại để con người xem xét.

Giới thiệu

Bất kỳ đội ngũ nào vận hành nhiều coding agent rồi cũng sẽ đối mặt với cùng một công việc tẻ nhạt: ai đó phải đọc từng tác vụ mới và quyết định ai sẽ đảm nhận. Agent backend hay agent frontend? Dùng mô hình tiết kiệm chi phí hay mô hình mạnh mẽ? Tác vụ đã sẵn sàng thực hiện, hay vẫn đang chờ một quyết định nào đó?

Ngày 11 tháng 11 năm 2026, Google đã ra mắt một công cụ chuyên biệt để giải quyết công việc này. Gemini Decisions API trả lời các câu hỏi đóng bằng xác suất đã được hiệu chuẩn thay vì tạo văn bản. Google sử dụng công cụ này trong Gemini Notebook để điều hướng từng truy vấn đến đúng phân cấp mô hình và mức độ tư duy (thinking level) phù hợp, đồng thời cho biết giải pháp này giúp giảm độ trễ cho các truy vấn thường nhật tới 40%.

Bài viết này sẽ hướng dẫn cách xây dựng một bộ định tuyến tương tự cho bảng quản lý agent: một lệnh gọi cho mỗi tác vụ, ba câu hỏi, một ngưỡng tin cậy, và quy trình chuyển giao rõ ràng cho con người khi bộ định tuyến không chắc chắn. Nếu bạn muốn có một bảng quản trị để chạy thử, Sharkly cho phép bắt đầu hoàn toàn miễn phí. Đối với chính sách định tuyến (những tác vụ nào cần đến mô hình mạnh), hãy đọc bài viết định tuyến tác vụ của agent theo độ khó trước. Còn bài viết này sẽ tập trung vào lệnh gọi API dùng để áp dụng chính sách đó.

Gemini Decisions API hoạt động như thế nào

Gemini Decisions API là một endpoint đánh giá các câu hỏi có định kiểu dựa trên cùng một đầu vào chung và trả về xác suất cùng điểm tin cậy cho từng câu hỏi. API này không sinh văn bản, nên số token đầu ra luôn bằng không. Mã nguồn của bạn có thể rẽ nhánh trực tiếp dựa trên các con số này mà không cần bước phân tích cú pháp (parse).

Ba loại câu hỏi đáp ứng nhu cầu định tuyến gồm:

Một yêu cầu có thể chứa tới 1.000 câu hỏi cho cùng một đầu vào. Theo tài liệu Decisions API, các câu hỏi được xử lý trong một lượt truyền thuận (forward pass) duy nhất và không phụ thuộc vào nhau, nên việc thêm câu hỏi sẽ không làm thay đổi câu trả lời của các câu hỏi khác. Google công bố độ trễ đầu-cuối từ 150 đến 250 ms, gần như giữ nguyên từ 1 đến 100 câu hỏi.

Nếu bạn đã đọc bài viết của chúng tôi về Jev và các mô hình ra quyết định cho coding agent, cấu trúc này sẽ trông rất quen thuộc. Điểm khác biệt ở đây mang tính thực tiễn: một mô hình do Google vận hành, ba câu hỏi được định nghĩa tường minh, cùng kết nối trực tiếp vào bảng quản lý công việc.

Lệnh gọi định tuyến: ba câu hỏi cho mỗi tác vụ

Dưới đây là bộ định tuyến. Nó yêu cầu thư viện google-genai phiên bản 3.2 trở lên và một GEMINI_API_KEY từ Google AI Studio.

import json
from google import genai

client = genai.Client(http_options={"api_version": "v1beta"})

AGENTS = {
    "backend": "Server code, APIs, database migrations, and backend tests.",
    "frontend": "UI components, styling, client state, and frontend tests.",
    "docs": "README files, docs pages, and changelogs. No code changes.",
    "other": "Work that fits none of the options above.",
}

DIFFICULTY = [
    "Trivial: one file, obvious change, no design decision.",
    "Routine: a few files, follows a pattern already in the repo.",
    "Involved: several modules or a new pattern, needs new tests.",
    "Hard: cross-cutting, touches auth or data migrations, or the spec is thin.",
]

def ask(task):
    state = json.dumps({
        "title": task["title"],
        "description": task["description"][:8000],
    })
    result = client.decisions.create(
        model="gemini-decision-1",
        input=state,
        questions={
            "agent": {
                "type": "choice",
                "instructions": "Which agent should take the task in `title` and `description`?",
                "criteria": AGENTS,
            },
            "difficulty": {
                "type": "score",
                "instructions": "How hard is this task for a coding agent working alone?",
                "criteria": DIFFICULTY,
            },
            "needs_human": {
                "type": "noul",
                "instructions": "Does a person need to make a decision before any agent starts?",
                "criteria": {
                    "true_description": "The spec is ambiguous, contradicts itself, or asks for a product, security, or pricing call.",
                    "false_description": "The spec is clear enough to implement as written.",
                },
            },
        },
    )
    return result.answers

Bốn chi tiết trong đoạn mã trên được dẫn trực tiếp từ tài liệu hướng dẫn và rất dễ bị bỏ sót.

Mô hình không bao giờ nhìn thấy các khóa (key) của bạn. Nó chỉ đọc instructions và criteria, vì vậy hãy viết đầy đủ câu hỏi trong instructions và mô tả chi tiết từng tùy chọn.

Các khóa tùy chọn được sắp xếp theo thứ tự bảng chữ cái. API sắp xếp các khóa lựa chọn theo thứ tự byte UTF-8 trước khi tính điểm. Đó là lý do tại sao phương án bao quát được đặt là other thay vì none_of_the_above, vì none_of_the_above sẽ bị xếp trước các lựa chọn thực tế khác.

Các mức điểm phải tuyến tính. Điểm score trả về là giá trị trung bình có trọng số theo xác suất của các chỉ số mức độ (ở đây là từ 0 đến 3). Hãy giữ các mức liền kề có sự phân biệt rạch ròi.

Chỉ gửi những gì câu hỏi thực sự cần. Tài liệu lưu ý rằng nội dung không liên quan sẽ làm giảm độ chính xác. Tiêu đề và mô tả thường mang lại hiệu quả tốt hơn việc đưa vào toàn bộ chuỗi bình luận.

Xác định ngưỡng tin cậy từ chính các tác vụ của bạn

Giá trị câu trả lời cho biết bạn nên làm gì. Độ tin cậy cho biết liệu bạn có thể thực hiện việc đó mà không cần hỏi lại hay không. Với câu trả lời dạng choice, độ tin cậy bằng xác suất của phương án cao nhất. Với dạng noul, giá trị này là max(noul, 1 - noul).

Dưới đây là tầng ra quyết định:

AUTO = 0.75      # assign without a person above this
HARD = 2.4       # difficulty score that earns the strong-model Agent

def decide(a):
    if a["needs_human"].noul >= 0.5:
        return ("human", "needs a decision first")
    if a["agent"].choice == "other" or a["agent"].confidence < AUTO:
        return ("human", f"router unsure ({a['agent'].confidence:.2f})")
    tier = "strong" if a["difficulty"].score >= HARD else "default"
    return (f"{a['agent'].choice}-{tier}", "auto")

Đừng rập khuôn con số 0.75 một cách mù quáng. Hướng dẫn của Google khuyên bạn nên thiết lập ngưỡng từ các mẫu dữ liệu thực tế đã được gắn nhãn của chính mình. Hãy lấy 50 đến 100 tác vụ đã đóng gần nhất, ghi nhận Agent nào đã hoàn thành từng việc, rồi chạy qua ask(). Chọn mức ngưỡng thấp nhất mà tại đó các tác vụ được tự động định tuyến khớp với quyết định của đội ngũ bạn. Một lượt định tuyến tự động sai sẽ dẫn đến chạy lỗi và phải phân công lại; trong khi việc giữ lại chờ người xem xét không cần thiết chỉ tốn vài phút. Hãy cân nhắc giữa hai tổn thất đó thay vì dựa vào một con số làm tròn ngẫu nhiên.

Hai cạm bẫy cần tránh: Xác suất noul không bao giờ vượt quá 0.99, vì vậy điều kiện kiểm tra như > 0.99 sẽ không bao giờ được kích hoạt. Thêm vào đó, điểm score ở mức 1.5 có thể mang nghĩa “lưỡng lự giữa mức 1 và 2” hoặc “không chắc chắn giữa cả bốn mức”. Khi cần độ chính xác cao, hãy đọc thêm trường probabilities.

Tích hợp bộ định tuyến vào bảng quản lý Sharkly

Bộ định tuyến này là mã Python thuần túy, nên có thể chạy ở bất kỳ đâu. Trên bảng Sharkly, thời điểm kích hoạt hợp lý nhất là ngay khi một tác vụ chuyển sang trạng thái sẵn sàng để thực hiện.

1. Tạo một Agent cho mỗi luồng và phân cấp. Ví dụ: backend-default, backend-strong, frontend-default. Theo tài liệu Sharkly Agents, theo mặc định mỗi Agent sẽ dùng mô hình của Runtime tương ứng, và hàng Model cho phép bạn chọn một mô hình khác từ danh mục của Runtime đó. Đây chính là nơi độ khó được chuyển đổi thành việc lựa chọn mô hình.

2. Áp dụng quyết định bằng sharkly CLI.

import subprocess

def apply(task_id, target, reason, a):
    note = (f"Router: agent={a['agent'].choice} ({a['agent'].confidence:.2f}), "
            f"difficulty={a['difficulty'].score:.1f}, "
            f"needs_human={a['needs_human'].noul:.2f}")
    if target == "human":
        subprocess.run(["sharkly", "task", "comment", task_id,
                        "--body", f"{note}. Held for a person: {reason}."], check=True)
        return
    subprocess.run(["sharkly", "task", "edit", task_id,
                    "--delegate-agent", target], check=True)
    subprocess.run(["sharkly", "task", "comment", task_id, "--body", note], check=True)

Việc phân công Agent sẽ kích hoạt lượt chạy của agent đó ngay khi tác vụ ở trạng thái sẵn sàng. Ghi lại các giá trị xác suất vào phần bình luận có ý nghĩa lớn hơn bạn tưởng: đây là cách giúp bạn kiểm tra lại hoạt động của bộ định tuyến sau một tháng nữa.

3. Kích hoạt khi có thay đổi trạng thái. Một Automation trên Sharkly lưu trữ các chỉ dẫn, Agent được phân công và các trigger. Hãy cung cấp cho một Router Agent nhỏ gọn chỉ dẫn “run route.py on the task that triggered you” (chạy route.py trên tác vụ đã kích hoạt bạn), sau đó thêm một trigger theo trạng thái tác vụ ứng với trạng thái mà đội ngũ bạn dùng cho “ready”. Các lượt chạy được khởi động bởi trigger trạng thái tác vụ sẽ liên kết ngược lại tác vụ đó, giúp lịch sử định tuyến luôn đi liền với công việc. Thao tác từ CLI:

sharkly automation trigger create <automation-id> --kind task_event --to-status "Ready"

Chi phí cho một lệnh gọi định tuyến

Theo bài viết ra mắt của Google, Gemini Decision 1 có giá 0,10 USD cho mỗi 1 triệu token đầu vào và 0 USD cho token đầu ra. Phần đầu vào dùng chung chỉ tính phí một lần trên mỗi yêu cầu, bất kể bạn đặt bao nhiêu câu hỏi.

Chi phí cho bộ định tuyến này thấp hơn chi phí chạy một agent cho một tác vụ đơn lẻ. Google cũng cung cấp gói miễn phí trong AI Studio để thử nghiệm nguyên mẫu.

Những giới hạn cần biết trước khi đưa vào vận hành

API này hiện được phát hành dưới dạng phiên bản v1beta trên Gemini Developer API, còn tính năng tích hợp Gemini trong Google Cloud được liệt kê là “sắp ra mắt”. Tài liệu nêu rõ API này chưa hỗ trợ context caching, Batch API, hay các chế độ suy luận Flex và Priority, do đó dữ liệu đầu vào lặp lại vẫn bị tính toàn bộ token mỗi lần gửi. Giới hạn tần suất gọi theo gói được công bố trên trang rate limits của Google; hãy kiểm tra hạn mức của bạn trước khi định tuyến toàn bộ tác vụ qua một API key duy nhất.

Hãy xem mô tả tác vụ là dữ liệu đầu vào không đáng tin cậy. Tài liệu cảnh báo rằng văn bản do người dùng cung cấp có thể chứa nội dung định hướng để tự phân loại theo ý họ. Nếu bất kỳ ai ngoài đội ngũ của bạn đều có thể tạo tác vụ, hãy luôn duy trì quy trình kiểm duyệt thủ công đối với bất cứ điều gì đụng chạm đến xác thực, thanh toán hoặc dữ liệu môi trường production, bất kể bộ định tuyến đưa ra kết quả gì.

Các tuyên bố benchmark của Google (mức sai số hiệu chuẩn thấp nhất trong bộ công cụ của hãng, rẻ hơn gần 5 lần so với Gemini 3.5 Flash-Lite qua Interactions API) là những con số từ phía Google. Chính những tác vụ thực tế đã được gắn nhãn của bạn mới là thước đo đáng tin cậy nhất.

Khi nào không nên dùng lệnh gọi định tuyến

Hãy sử dụng Decisions API khi các tác vụ xuất hiện nhanh hơn khả năng phân loại thủ công của con người và các phương án đã được cố định: một tập hợp các Agent, một tập hợp các phân cấp mô hình, hoặc một cổng điều kiện có/không. Hãy dùng quy tắc thông thường nếu nhãn đã tự quyết định điều đó. Nếu mọi tác vụ gắn thẻ docs đều được chuyển đến docs Agent, thì một câu lệnh if vừa tiết kiệm chi phí hơn vừa không bao giờ sai.

Thay vào đó, hãy sử dụng mô hình tạo sinh khi bạn cần bộ định tuyến diễn giải lý do bằng câu chữ, viết lại bản đặc tả hoặc chia nhỏ tác vụ thành các nhiệm vụ con. Decisions API chỉ trả về các con số, không trả về văn bản. Để phân chia công việc cho nhiều vai trò, mô hình Crew với nhóm trưởng phụ trách bóc tách mục tiêu sẽ phù hợp hơn; xem thêm tại bài viết định tuyến mô hình cho các nhóm agent (Crews).

Kết luận

Định tuyến là một bài toán ra quyết định trong tập hữu hạn, và Gemini Decisions API được tạo ra chuyên để phục vụ mục đích đó: một lượt gọi, các câu trả lời có định kiểu, điểm tin cậy có thể đặt ngưỡng, cùng chi phí chỉ tính bằng một phần nhỏ của một xu. Phần việc còn lại thuộc về bạn: viết mô tả rõ ràng cho các tùy chọn, hiệu chuẩn ngưỡng dựa trên các tác vụ đã hoàn thành thực tế của chính bạn, và chuyển các trường hợp có độ tin cậy thấp cho con người xử lý.

Hãy bắt đầu với một luồng công việc. Thử định tuyến các tác vụ backend mới trong một tuần, so sánh lựa chọn của bộ định tuyến với quyết định thực tế của nhóm bạn, rồi sau đó mở rộng thêm. Để chạy bộ định tuyến trên một bảng quản lý thực tế tích hợp sẵn Agents, Automations và quy trình con người xem xét tập trung tại một nơi, hãy bắt đầu với Sharkly.

Câu hỏi thường gặp

Gemini Decisions API là gì?

Đây là một endpoint của Gemini API, được ra mắt vào ngày 11 tháng 11 năm 2026, chuyên trả lời các câu hỏi dạng có/không, trắc nghiệm lựa chọn và chấm điểm về văn bản, hình ảnh, âm thanh, video hoặc PDF. API sử dụng mô hình gemini-decision-1 để trả về xác suất và độ tin cậy đã được hiệu chuẩn thay vì tạo văn bản.

Gemini Decision 1 có giá bao nhiêu?

Google niêm yết mức giá 0,10 USD cho mỗi 1 triệu token đầu vào và 0 USD cho token đầu ra, trong đó đầu vào dùng chung chỉ tính phí một lần trên mỗi yêu cầu. Google AI Studio cũng có gói miễn phí để phục vụ thử nghiệm nguyên mẫu.

Một yêu cầu có thể đặt bao nhiêu câu hỏi?

Từ 1 đến 1.000 câu hỏi, bị giới hạn bởi cửa sổ ngữ cảnh 262.144 token tính trên toàn bộ đầu vào và tất cả các câu hỏi. Các câu hỏi dạng lựa chọn có thể nhận từ 2 đến 255 phương án.

Nên sử dụng ngưỡng tin cậy nào cho việc định tuyến?

Không có một con số chung cho mọi trường hợp. Google khuyến nghị nên thiết lập ngưỡng từ các ví dụ thực tế đã được gắn nhãn của chính bạn. Hãy chạy lại thử nghiệm với 50 đến 100 tác vụ đã đóng và chọn mức ngưỡng mà tại đó các quyết định tự động khớp với lựa chọn của đội ngũ bạn.

Decisions API có thể chọn mô hình mà agent sẽ sử dụng không?

Có thể thực hiện gián tiếp. Đặt câu hỏi dạng score để đánh giá độ khó, sau đó ánh xạ các mức điểm cao tới một Agent được cấu hình mô hình mạnh hơn. Trong Sharkly, mỗi Agent có thể được chỉ định một mô hình từ danh mục của Runtime tương ứng.

Gemini Decisions API đã có trên Vertex AI chưa?

Hiện tại thì chưa. Bài viết ra mắt của Google cho biết tính năng hỗ trợ cho Gemini trên Google Cloud sẽ sớm xuất hiện. Hiện nay API hoạt động trên Gemini Developer API dưới dạng v1beta.