Gọi hàm Gemini 3.8 Flash: call_id, vòng lặp công cụ lặp và cách kiểm thử

Gemini 3.8 Flash đã ra mắt vào ngày 2 tháng 9 năm 2026, và Google đã xây dựng nó để “gọi công cụ một cách lặp đi lặp lại”: đối với một tác vụ khó, nó thực hiện một lệnh gọi, kiểm tra kết quả và thực hiện một lệnh gọi khác, thay vì đoán tất cả trong một lần. Đây là tin tốt cho các tác nhân và là một vấn đề đau đầu mới cho bất kỳ ai có vòng lặp công cụ đã được tinh chỉnh cho 3.7 Flash. Hai chi tiết API quan trọng hơn bất cứ điều gì khác. Mỗi kết quả hàm phải mang cả call_id và name, và Interactions API, chứ không phải generateContent, giờ đây là cách chính để chạy vòng lặp.

Hướng dẫn này trình bày toàn bộ luồng hai lượt trên Interactions API, chỉ ra dạng generateContent cũ mà bạn có thể vẫn đang chạy, giải thích tại sao mô hình mới dành nhiều lượt và token hơn cho các công cụ, và kết thúc bằng một thiết lập thử nghiệm mà bạn có thể chạy hàng ngày: giả lập backend của công cụ, nối chuỗi cả hai lượt và xác nhận call_id đi và về. Nếu bạn cần tổng quan về mô hình trước, hãy bắt đầu với Gemini 3.8 Flash là gì. Các tên trường dưới đây đến từ tài liệu gọi hàm của Google.

Mọi yêu cầu ở đây đều là HTTP thuần túy với JSON, vì vậy bạn có thể xây dựng và gỡ lỗi nó trong Apidog trước khi đưa vào mã ứng dụng.

Gọi hàm trên Gemini 3.8 Flash sơ lược

Mục	Gemini 3.8 Flash
ID mô hình	`gemini-3.8-flash` (ổn định, không có hậu tố bản xem trước)
API chính	Interactions API (`POST /v1beta/interactions`); `generateContent` là cũ nhưng được hỗ trợ đầy đủ
Khai báo công cụ	`tools: [{"type": "function", "name", "description", "parameters"}]`
Lệnh gọi của mô hình	Bước `function_call` với `id`, `name`, `arguments`
Phản hồi của bạn	`function_result` với `call_id` + `name` (cả hai đều bắt buộc) cộng với `previous_interaction_id`
Suy nghĩ	`thinking_level` `low` / `medium` (mặc định) / `high`; `minimal` trả về lỗi xác thực
Điểm sử dụng công cụ	Tau3-Banking 45%, +12 điểm so với 3.7 Flash (Phân tích nhân tạo, độc lập)
Chi phí Token	~48k token đầu ra mỗi tác vụ trên chỉ mục AA, +30% so với 3.7 Flash
Giá	$0.75 đầu vào / $3.75 đầu ra mỗi 1M token đến hết ngày 31/12/2026; suy nghĩ được tính phí như đầu ra

Bước 1: Khai báo công cụ

Trên Interactions API, một công cụ là một đối tượng phẳng: một `type` là `function`, một `name`, một `description` mà mô hình đọc để quyết định khi nào gọi nó, và một JSON Schema dưới `parameters`. Giữ mô tả cụ thể. “Tra cứu trạng thái vận chuyển hiện tại của một đơn hàng theo ID của nó” sẽ được gọi vào đúng thời điểm; “trợ giúp đơn hàng” sẽ được gọi ngẫu nhiên.

curl -X POST "https://generativelanguage.googleapis.com/v1beta/interactions" \
  -H "x-goog-api-key: $GEMINI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gemini-3.8-flash",
    "input": "Where is order A1029 right now?",
    "generation_config": {"thinking_level": "low"},
    "tools": [{
      "type": "function",
      "name": "get_order_status",
      "description": "Look up the current shipping status of an order by its ID.",
      "parameters": {
        "type": "object",
        "properties": {"order_id": {"type": "string"}},
        "required": ["order_id"]
      }
    }]
  }'

Hai lựa chọn trong yêu cầu này là có chủ ý. thinking_level là low vì một tra cứu đơn lẻ không cần medium mặc định; hướng dẫn về các cấp độ suy nghĩ sẽ đề cập khi nào nên nâng cao nó. Và không có temperature. Hướng dẫn Gemini 3 của Google là để nó ở giá trị mặc định 1.0, vì việc giảm nó có thể gây ra vòng lặp, điều cuối cùng bạn muốn trong một vòng lặp công cụ.

Bước 2: Đọc bước function_call

Interactions API không trả lời bằng một tin nhắn duy nhất. Nó trả về `id` của tương tác đó cộng với một danh sách các bước thực thi: suy nghĩ của mô hình, lệnh gọi công cụ và cuối cùng là bước `model_output` khi mô hình có câu trả lời. Khi mô hình quyết định cần công cụ của bạn, danh sách sẽ chứa bước `function_call` thay vì `model_output`:

{
  "type": "function_call",
  "id": "call_8f2d...",
  "name": "get_order_status",
  "arguments": {"order_id": "A1029"}
}

Ba trường này, và bạn cần cả ba. id là định danh bạn gửi lại dưới dạng call_id. name cho bạn biết hàm nào để chạy và cũng phải được trả về. arguments đã là JSON được phân tích cú pháp, vì vậy hãy xác thực nó theo các quy tắc của riêng bạn trước khi thực thi bất cứ điều gì; mô hình điền vào hình dạng bạn đã khai báo, nhưng nó không biết ID đơn hàng của bạn dài năm ký tự.

Đồng thời, hãy lưu trữ `id` của tương tác từ đầu phản hồi. Nó sẽ trở thành previous_interaction_id trong lượt tiếp theo.

Bước 3: Trả về kết quả với call_id và name

Chạy hàm của bạn, sau đó gửi một yêu cầu thứ hai mà `input` của nó là `function_result`. Cả call_id và name đều được yêu cầu trên Gemini 3.8 Flash. Thiếu một trong hai sẽ làm lệnh gọi thất bại, đây là lỗi phổ biến nhất khi các nhóm di chuyển các vòng lặp được viết cho các mô hình cũ hơn.

curl -X POST "https://generativelanguage.googleapis.com/v1beta/interactions" \
  -H "x-goog-api-key: $GEMINI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gemini-3.8-flash",
    "previous_interaction_id": "<interaction id from step 2>",
    "input": [{
      "type": "function_result",
      "name": "get_order_status",
      "call_id": "call_8f2d...",
      "result": [{"type": "text", "text": "{\"status\":\"in_transit\",\"eta\":\"2026-09-05\"}"}]
    }]
  }'

result là một danh sách các phần nội dung, và phần văn bản mang JSON của bạn dưới dạng một chuỗi. Bởi vì previous_interaction_id trỏ đến lượt trước đó, máy chủ đã giữ lời nhắc ban đầu, khai báo công cụ và lý luận của mô hình; bạn không cần gửi lại bất kỳ điều gì trong số đó. Phản hồi là một danh sách bước khác. Nếu nó kết thúc bằng model_output, bạn đã hoàn thành, và SDK hiển thị văn bản dưới dạng interaction.output_text. Nếu nó chứa một function_call khác, hãy quay lại bước 2. Vòng lặp đó là toàn bộ mẫu.

Trong Python, luồng là `client.interactions.create(model="gemini-3.8-flash", input=..., ...) ` với các trường JSON tương tự như đối số từ khóa, sau đó là một `create` thứ hai với `previous_interaction_id` và danh sách `function_result` làm `input`. Hướng dẫn sử dụng API Gemini 3.8 Flash bao gồm các khóa, luồng và đọc mức sử dụng token nếu điểm cuối này mới đối với bạn.

Tương đương generateContent cũ

Hầu hết mã Gemini hiện có vẫn gọi `models/gemini-3.8-flash:generateContent`, và Google nói rằng nó "vẫn được hỗ trợ đầy đủ" mà không có ngày ngừng hoạt động. Từ vựng khác nhau; quy tắc vẫn giống nhau. Các công cụ được khai báo dưới `functionDeclarations`, mô hình trả lời bằng một phần `functionCall`, và bạn trả lời bằng một phần `functionResponse`. Trên dạng cũ, phần `functionCall` của mô hình mang một `id`, và phần `functionResponse` của bạn phải lặp lại giá trị đó trong trường `id` của chính nó cùng với `name` và `response`. Đó là hợp đồng tương tự như `call_id` trên Interactions API dưới một tên trường khác, và hướng dẫn Gemini 3 của Google nói rõ rằng cả id và tên đều bắt buộc.

Hai khác biệt thực tế. Thứ nhất, `generateContent` là không trạng thái, vì vậy bạn tự mình quản lý cuộc trò chuyện: toàn bộ lịch sử `contents` được gửi lại trong mỗi lượt, bao gồm phần `functionCall` của mô hình và mọi chữ ký suy nghĩ mà nó đã trả về. Thứ hai, suy nghĩ được cấu hình dưới `generationConfig.thinkingConfig.thinkingLevel` thay vì `generation_config.thinking_level`:

{"generationConfig": {"thinkingConfig": {"thinkingLevel": "low"}}}

Các token suy nghĩ hiển thị dưới dạng `usageMetadata.thoughtsTokenCount` trong phản hồi và được tính phí như đầu ra. Nếu bạn đang lựa chọn giữa hai API cho một dự án mới, hãy chọn Interactions: trạng thái phía máy chủ loại bỏ các lỗi mà lịch sử được gửi lại thiếu chữ ký hoặc `call_id`.

Tại sao 3.8 Flash gọi công cụ lặp đi lặp lại và cách giới hạn vòng lặp

Bài đăng ra mắt của Google nói rằng mô hình "hoạt động chăm chỉ hơn": đối với các tác vụ phức tạp, nó "thực hiện thêm các bước suy luận, và gọi công cụ lặp đi lặp lại", thực hiện "các bước suy luận nhỏ hơn" và xác minh công việc của mình trong quá trình. Google cũng nói rằng nó "có thể sử dụng nhiều token hơn cho các tác vụ phức tạp và chạy lâu hơn, theo thiết kế". Artificial Analysis đã đo lường hiệu ứng: khoảng 48k token đầu ra mỗi tác vụ trên chỉ mục của họ, +30% so với 3.7 Flash, và chi phí mỗi tác vụ là 0.58 đô la ở chế độ `high` so với 0.40 đô la cho 3.7 Flash với cùng mức giá mỗi token. Chế độ medium là 0.41 đô la và low là 0.24 đô la.

Đối với một vòng lặp công cụ, điều này có nghĩa là nhiều bước `function_call` hơn cho mỗi tác vụ. Lợi ích là có thật: Tau3-Banking, đánh giá sử dụng công cụ của AA, đã tăng 12 điểm lên 45%. Nhược điểm là một vòng lặp không có giới hạn giờ đây chạy lâu hơn so với tháng Tám. Bốn biện pháp kiểm soát, theo thứ tự áp dụng:

Số lượt tối đa trong bộ điều khiển của bạn. Đếm các bước function_call cho mỗi tác vụ và dừng ở giới hạn bạn chọn; 6 đến 10 là một phạm vi khởi đầu hợp lý cho các tra cứu, cao hơn cho mã hóa tác nhân. Khi đạt giới hạn, gửi một lượt cuối cùng mà không có công cụ, hoặc trả về lỗi cho người dùng. Mô hình sẽ không tự giới hạn.
`thinking_level` cho mỗi lộ trình. `low` cho các tra cứu và công cụ một bước nhảy, `medium` (mặc định) cho các công việc nhiều bước, `high` chỉ khi việc xác minh bổ sung mang lại lợi ích. Không gửi `minimal`; 3.8 Flash trả về lỗi xác thực.
Thời gian chờ ở cả hai phía. Thời gian chờ mỗi yêu cầu đối với lệnh gọi Gemini và đồng hồ thời gian thực mỗi tác vụ trên vòng lặp. Các lần chạy suy luận cao của AA trung bình 2.5 phút mỗi tác vụ, 0.8 phút ở mức thấp.
Công cụ bất biến (Idempotent). Một mô hình lặp đi lặp lại. Đảm bảo `get_order_status` an toàn để gọi hai lần, và đảm bảo bất cứ điều gì có tác dụng phụ (hoàn tiền, gửi) đều yêu cầu bước xác nhận.

Nếu ngân sách của bạn không thể hấp thụ các lượt bổ sung, hướng dẫn di chuyển từ 3.7 sang 3.8 Flash sẽ đề cập đến việc giữ 3.7 Flash, vẫn được hỗ trợ đầy đủ, đằng sau một cờ cấu hình.

Chữ ký suy nghĩ, các lệnh gọi song song và đầu ra có cấu trúc

Chữ ký suy nghĩ. Các mô hình Gemini 3 đính kèm chữ ký vào quá trình suy luận của chúng. Với luồng Interactions được lưu trữ mặc định, `previous_interaction_id` sẽ xử lý chúng cho bạn. Nếu bạn đặt `store: false` cho một thiết lập không trạng thái, hoặc bạn sử dụng `generateContent`, bạn phải gửi các khối suy nghĩ và chữ ký trở lại chính xác như đã nhận, trên mọi loại phần. Không cắt bớt, sắp xếp lại, hoặc tái tuần tự hóa chúng; một chữ ký là không rõ ràng và bất kỳ chỉnh sửa nào cũng sẽ làm mất hiệu lực của nó. Tài liệu API Interactions của Google bao gồm sự đánh đổi giữa việc lưu trữ và không trạng thái.

Các lệnh gọi song song. Phản hồi là một danh sách, vì vậy nó có thể chứa nhiều hơn một bước `function_call` khi mô hình muốn nhiều tra cứu độc lập cùng một lúc. Tài liệu gọi hàm của Google xác nhận rằng các mô hình Gemini 3 trả về một id duy nhất với mỗi lệnh gọi chính xác để kết quả có thể trở lại theo bất kỳ thứ tự nào. Xử lý nó bằng cách trả về một `function_result` cho mỗi lệnh gọi trong cùng một mảng `input`, mỗi lệnh khớp với `call_id` của riêng nó. Chỉ khớp bằng `name` là không đủ; hai lệnh gọi đến cùng một hàm cần hai giá trị `call_id` khác nhau.

Đầu ra có cấu trúc. 3.8 Flash hỗ trợ đầu ra có cấu trúc và gọi hàm trên cùng một mô hình. Mô hình sạch sẽ là các công cụ cho vòng lặp và một JSON schema cho câu trả lời cuối cùng, để `model_output` đóng vòng lặp có thể đọc được bằng máy thay vì văn xuôi. Các trang gọi hàm và đầu ra có cấu trúc của Google tài liệu hóa cấu hình. Đừng làm giả bằng cách khai báo một công cụ giả và đọc `arguments` của nó; điều đó sẽ hỏng ngay khi mô hình quyết định nó không có gì để gọi.

Tất cả những điều trên đều giả định mô hình tiếp cận hệ thống của bạn thông qua các hàm đã khai báo. Google cũng liệt kê Computer use (Bản xem trước) cho 3.8 Flash; để biết khi nào một API có cấu trúc vượt trội hơn việc điều khiển màn hình một tác nhân, hãy xem sử dụng máy tính so với API có cấu trúc.

Kiểm tra vòng lặp công cụ trong Apidog

Một vòng lặp công cụ có ba điểm có thể bị lỗi: khai báo, vòng lặp id và câu trả lời cuối cùng. Bạn có thể bao gồm cả ba trong Apidog mà không cần chạm vào backend thực của bạn.

1. Giả lập backend của công cụ. Định nghĩa `GET /orders/{order_id}` là một điểm cuối và bật máy chủ giả lập của nó. Cung cấp cho nó một phần thân phản hồi cố định, `{"status": "in_transit", "eta": "2026-09-05"}`, để mỗi lần chạy nhận được đầu vào giống hệt nhau và bất kỳ thay đổi nào trong câu trả lời cuối cùng của mô hình là do mô hình, chứ không phải cơ sở dữ liệu của bạn. Hệ thống điều khiển của bạn trỏ đến URL giả lập trong môi trường thử nghiệm và đến dịch vụ thực trong sản xuất.

2. Nối chuỗi cả hai lượt trong một kịch bản thử nghiệm. Lưu trữ `GEMINI_API_KEY` dưới dạng biến môi trường và tham chiếu nó dưới dạng `{{GEMINI_API_KEY}}` trong tiêu đề `x-goog-api-key`. Sau đó xây dựng một kịch bản với ba bước:

Bước A: POST tới `/v1beta/interactions` với lời nhắc và khai báo `get_order_status`. Trích xuất `id` của tương tác và `id`, `name`, cùng `arguments.order_id` của bước `function_call` vào các biến.
Bước B: GET điểm cuối giả lập với `{{order_id}}`. Đây là bước "chạy hàm" của bạn.
Bước C: POST `function_result` với `call_id` được đặt thành `{{call_id}}`, `name` được đặt thành `{{tool_name}}`, `previous_interaction_id` được đặt thành `{{interaction_id}}`, và phần thân của Bước B là phần văn bản.

3. Khẳng định những gì quan trọng.

Bước A trả về 200 và chứa một bước có `type` là `function_call` với `name` bằng `get_order_status`.
`arguments.order_id` được trích xuất bằng `A1029`, điều này chứng minh mô hình đã phân tích lời nhắc và tuân thủ schema.
Bước C trả về 200 và kết thúc bằng một bước có `type` là `model_output` mà không có `function_call` thứ hai, điều này chứng minh `call_id` và `name` bạn đã gửi được chấp nhận và vòng lặp đã đóng trong một vòng.
Văn bản cuối cùng chứa `in_transit`, điều này chứng minh mô hình đã sử dụng kết quả của công cụ thay vì đoán của riêng nó.
Nếu bạn chạy cùng một kịch bản đối với `generateContent`, hãy thêm một giới hạn trên `usageMetadata.thoughtsTokenCount` cho mỗi `thinking_level`. Điều đó sẽ ngăn chặn sự tăng chi phí "hoạt động chăm chỉ hơn" trước khi nó ảnh hưởng đến hóa đơn của bạn.

Lên lịch chạy kịch bản hàng ngày. Hành vi của mô hình thay đổi qua các bản cập nhật ngầm, và một vòng lặp đã đóng trong một vòng vào tuần trước có thể bắt đầu cần hai vòng. Hướng dẫn kiểm thử API tác nhân AI đi sâu hơn về các khẳng định nhiều bước, và bạn có thể Tải xuống Apidog để xây dựng kịch bản với tầng miễn phí trước khi bạn chi một xu.

FAQ

`call_id` có bắt buộc trên Gemini 3.8 Flash không? Có. Trên Interactions API, mọi `function_result` đều cần `call_id` và `name`; trên `generateContent`, mọi `functionResponse` đều cần `id` và `name` của lệnh gọi. Mã cũ chỉ gửi tên sẽ thất bại trên các mô hình Gemini 3.

Tại sao vòng lặp công cụ của tôi chạy nhiều lượt hơn trên 3.8 Flash so với 3.7? Theo thiết kế. Google nói rằng mô hình “gọi công cụ một cách lặp đi lặp lại” và “có thể sử dụng nhiều token hơn cho các tác vụ phức tạp và chạy lâu hơn”. Giới hạn lượt trong hệ thống điều khiển của bạn và giảm `thinking_level`; hướng dẫn về cấp độ suy nghĩ có chi phí đo lường cho mỗi cấp độ.

Tôi có thể vẫn sử dụng `generateContent` cho việc gọi hàm không? Có. Google gọi nó là cũ nhưng nói rằng nó "vẫn được hỗ trợ đầy đủ" mà không có ngày ngừng hoạt động. Bạn tự mình mang lịch sử, bao gồm các chữ ký suy nghĩ, và ID lệnh gọi (ghi là `id` trên API này) cộng với `name` vẫn áp dụng.

`thinking_level` "minimal" có hoạt động với các công cụ không? Không. Nó trả về lỗi xác thực trên 3.8 Flash. Hãy sử dụng `low`.

Một tác vụ nặng công cụ tốn bao nhiêu chi phí? Giá mỗi token là $0.75 đầu vào và $3.75 đầu ra cho mỗi 1M token đến ngày 31 tháng 12 năm 2026, với suy nghĩ được tính phí là đầu ra. Artificial Analysis đo lường $0.58 mỗi tác vụ ở mức `high`, $0.41 ở mức `medium`, và $0.24 ở mức `low` trên chỉ mục của họ. Các tác vụ của bạn sẽ khác, vì vậy hãy khẳng định về số lượng token và đo lường.

Triển khai vòng lặp với một giới hạn

Khai báo công cụ, đọc bước `function_call` và trả về `function_result` với cả `call_id` và `name` dưới `previous_interaction_id`. Đó là toàn bộ hợp đồng. Điều thay đổi với Gemini 3.8 Flash là khả năng lặp lại của mô hình, vì vậy hệ thống điều khiển cần một giới hạn lượt, một `thinking_level` theo tuyến đường và một thời gian chờ trước khi đưa vào sản xuất. Giả lập backend, nối chuỗi hai lượt, xác nhận `id` đi và về, và lên lịch chạy. Trang Có gì mới trong Gemini 3.8 Flash của Google có các ghi chú di chuyển; hướng dẫn cốt lõi có mọi thứ khác về mô hình.