Phần lớn code function calling trên internet vẫn là Chat Completions với gpt-4o. Với stack tháng 11/2026, mẫu đó sai ở hai điểm: model mới không còn tool-call qua Chat Completions theo cách cũ, và API đúng là Responses. Tệ hơn, nhiều người vẫn tin model “gọi hàm” giúp họ — nó chỉ đề xuất một call, còn việc thực thi và phân quyền là của bạn.
Bài này đi qua schema tool, hai API của OpenAI, function calling của Gemini, và những lỗi thực tế khiến agent gọi sai tool hoặc trả kết quả rác. Toàn bộ ví dụ dùng HTTP thô để bạn thấy rõ payload, không phụ thuộc tên method trong SDK.
Mục lục
Cập nhật 2026
- Responses là API được khuyến nghị cho mọi dự án mới. Hosted tools,
previous_response_idvà encrypted reasoning chỉ có trên Responses. - Với các model từ GPT-5.4 trở đi, Chat Completions không tool-call được trừ khi
reasoning_effortlànone. Riêng Astra và Sol bắt buộc dùng Responses nếu muốn tool calling. - Assistants API đã biến mất; đừng xây mới trên đó.
- Gemini: SDK
google-genai3.0.0;gemini-2.5-flashbị deprecate và từ 2026-12-01 request sẽ tự route sanggemini-3.5-flash-lite.
Function calling thực sự là gì
Model không chạy code. Nó nhận danh sách tool kèm schema, rồi quyết định có nên trả về một “đề xuất gọi” thay vì câu trả lời. Đề xuất đó gồm tên tool và tham số. Ứng dụng của bạn parse tham số, kiểm tra hợp lệ, thực thi hàm thật, rồi gửi kết quả trở lại như một lượt mới. Model dùng kết quả đó để viết câu trả lời cuối hoặc đề xuất call tiếp theo.
Ba hệ quả thiết kế:
- Tool schema là prompt. Mô tả tool và tham số là thứ model đọc để chọn; viết mơ hồ thì model đoán.
- Model không có quyền. Quyền nằm ở lớp thực thi của bạn. Model đề xuất
delete_userkhông có nghĩa là được xóa. - Kết quả tool là đầu vào không tin cậy. Nó có thể chứa chỉ dẫn độc hại từ web, file, ticket. Đây là indirect prompt injection, không phải chuyện hiếm.
Thiết kế schema tool trước khi viết code
Một tool tốt có tên động từ rõ nghĩa, mô tả nêu khi nào dùng và khi nào không, tham số có kiểu và enum, và output nhỏ. Bốn lỗi thường gặp:
- Một tool làm quá nhiều việc —
manage_order(action, ...)với 12 nhánh. Model phải chọn action trong lòng tool, sai nhiều hơn. Tách thànhget_order,cancel_order,refund_order. - Tham số tự do —
query: stringcho mọi thứ. Hãy dùng enum cho trạng thái, ngày theo ISO 8601, ID theo pattern, vàadditionalProperties: falseđể chặn field lạ. - Mô tả không nói giới hạn — thiếu “chỉ dùng cho đơn đã thanh toán”, model sẽ gọi cho mọi đơn.
- Output quá lớn — trả cả object 40 field. Model tốn token đọc và dễ bỏ qua field quan trọng. Trả 5–8 field cần cho bước tiếp theo.
OpenAI: Responses, không phải Chat Completions
Trên Responses, tool được khai báo phẳng: type, name, description, parameters ở cùng một cấp. Đây là khác biệt cú pháp lớn so với Chat Completions, nơi mọi thứ nằm lồng trong object function.
POST https://api.openai.com/v1/responses
Authorization: Bearer $OPENAI_API_KEY
Content-Type: application/json
{
"model": "gpt-6.1-sol",
"input": "Thời tiết Hà Nội hôm nay thế nào?",
"tools": [{
"type": "function",
"name": "get_current_weather",
"description": "Lấy thời tiết hiện tại cho một thành phố. Chỉ dùng khi người dùng hỏi thời tiết hiện tại, không dùng cho dự báo dài hạn.",
"parameters": {
"type": "object",
"properties": {
"location": {"type": "string", "description": "Tên thành phố, ví dụ Hà Nội"},
"unit": {"type": "string", "enum": ["celsius", "fahrenheit"]}
},
"required": ["location"],
"additionalProperties": false
}
}],
"tool_choice": "auto"
}
Response không trả về tool_calls như Chat Completions. Nó trả về một mảng output, trong đó phần tử cần quan tâm có type: "function_call", một call_id, tên tool, và arguments là chuỗi JSON, không phải object.
// response (rút gọn)
{"id":"resp_abc","output":[
{"type":"function_call","call_id":"call_1","name":"get_current_weather",
"arguments":"{\"location\":\"Hà Nội\",\"unit\":\"celsius\"}"}]}
// lượt tiếp theo: gửi kết quả thực thi
{"model":"gpt-6.1-sol","previous_response_id":"resp_abc",
"input":[{"type":"function_call_output","call_id":"call_1",
"output":"{\"temp_c\":27,\"condition\":\"cloudy\"}"}]}
Hai chi tiết dễ sai: bạn phải giữ call_id khớp chính xác, và output của function_call_output cũng là chuỗi. Nếu bạn dùng previous_response_id, chỉ cần gửi phần mới; nếu không, phải gửi lại cả các item trước đó theo đúng thứ tự. Đừng trộn hai kiểu trong cùng một luồng.
Chat Completions vẫn tồn tại, nhưng hãy coi nó là legacy cho tool calling. Cú pháp cũ vẫn là tools[].function.name, kết quả ở choices[0].message.tool_calls, và kết quả tool là message role: "tool" kèm tool_call_id. Nếu bạn buộc phải dùng nó với model mới, kiểm tra điều kiện reasoning_effort: "none"; với Astra và Sol thì đúng là không có đường nào ngoài Responses.
Gemini: cùng ý tưởng, khác cú pháp
Gemini dùng tools[].functionDeclarations[] và trả kết quả trong candidates[0].content.parts[]. Tham số trả về là object, không phải chuỗi JSON — một khác biệt nhỏ nhưng làm hỏng nhiều đoạn code copy từ OpenAI.
POST https://generativelanguage.googleapis.com/v1beta/models/gemini-3.8-flash:generateContent
x-goog-api-key: $GEMINI_API_KEY
Content-Type: application/json
{
"contents": [{"role": "user", "parts": [{"text": "Thời tiết Hà Nội hôm nay?"}]}],
"tools": [{"functionDeclarations": [{
"name": "get_current_weather",
"description": "Lấy thời tiết hiện tại cho một thành phố.",
"parameters": {
"type": "object",
"properties": {
"location": {"type": "string"},
"unit": {"type": "string", "enum": ["celsius", "fahrenheit"]}
},
"required": ["location"]
}
}]}]
}
// response (rút gọn)
{"candidates":[{"content":{"role":"model","parts":[
{"functionCall":{"name":"get_current_weather","args":{"location":"Hà Nội"}}}]},
"finishReason":"STOP"}]}
// gửi kết quả: thêm một part functionResponse vào contents
{"contents":[
{"role":"user","parts":[{"text":"Thời tiết Hà Nội hôm nay?"}]},
{"role":"model","parts":[{"functionCall":{"name":"get_current_weather","args":{"location":"Hà Nội"}}}]},
{"role":"user","parts":[{"functionResponse":{"name":"get_current_weather",
"response":{"temp_c":27}}}]}
]}
Gemini trả về functionCall.args dạng object nên bạn có thể validate trực tiếp. Nhưng đừng bỏ qua validation: model vẫn có thể điền thiếu trường hoặc dùng sai enum. Với Gemini 3, một số part có thể kèm signature suy luận mà bạn phải giữ nguyên khi gửi lại — hãy kiểm tra tài liệu của đúng model bạn dùng trước khi tự ghép contents bằng tay.
Song song, lỗi và phê duyệt
Cả hai API đều có thể trả nhiều call trong một lượt. Với OpenAI, đó là nhiều item function_call; với Gemini, nhiều part functionCall. Cách xử lý đúng:
- Chạy song song nhưng có trần. Dùng
asyncio.gathervới semaphore, ví dụ tối đa 5 call đồng thời. Một lượt 20 call là dấu hiệu schema quá rộng hoặc model đang đoán. - Trả đủ kết quả trong một lượt. Thiếu một
call_idhoặc mộtfunctionResponsethì lượt sau sẽ lỗi. Đừng gửi từng kết quả một. - Lỗi phải là dữ liệu, không phải exception. Trả về
{"ok": false, "error": "not_found", "hint": "Dùng search_order trước"}để model sửa hướng đi. Đừng ném stack trace vào context. - Giới hạn một lần sửa. Nếu model gửi tham số sai, cho nó đúng một lần thử lại với thông báo lỗi; lần hai vẫn sai thì trả lời người dùng hoặc hạ xuống luồng tất định.
Validation tối thiểu trước khi thực thi: parse JSON, kiểm tra trường bắt buộc, kiểu, enum, độ dài, và quyền của người dùng hiện tại. Đừng bao giờ dùng tham số model trả về làm điều kiện phân quyền.
# File: tools/validate_call.py
import json
ALLOWED_UNITS = {"celsius", "fahrenheit"}
def parse_call(name: str, arguments: str, allowed: set[str]) -> dict | None:
if name not in allowed:
return None
try:
args = json.loads(arguments)
except json.JSONDecodeError:
return None
if not isinstance(args, dict) or not args.get("location"):
return None
if args.get("unit", "celsius") not in ALLOWED_UNITS:
return None
return {"location": str(args["location"])[:80],
"unit": args.get("unit", "celsius")}
Phê duyệt là lớp riêng. Mọi tool có side effect không thể hoàn tác — chuyển tiền, xóa dữ liệu, gửi email hàng loạt, đổi quyền — cần một gate: người duyệt, hoặc policy engine. Log lại ai duyệt, tham số gì, quyết định gì. Và nhớ: approval không phải idempotency; nếu request bị retry sau khi duyệt, tool vẫn phải có idempotency key để không thực thi hai lần.
Chi phí và giới hạn cần nhớ
- Schema tool tốn input token mỗi request. Một catalog 20 tool với mô tả dài là vài nghìn token mỗi lượt, trước cả khi model làm gì. Giữ catalog hẹp theo tác vụ.
- OpenAI tính 2x input và 1,5x output khi request vượt 272K token, áp cho toàn bộ request. Đừng nhét toàn bộ lịch sử hội thoại vào một call chỉ vì context 1,05M còn trống.
- Gemini 4 Argon có 1.048.576 token context dùng chung cho input và output, output mặc định 65.536; giá $2/$10 chỉ đến 2026-11-30, sau đó $4/$20. Đừng lập ngân sách trên giá khuyến mãi.
- Gemini 3.8 Flash giá $0,75/$3,75 đến 2026-12-31, sau đó $1,50/$7,50. Output price đã bao gồm thinking token, nhưng vẫn là token bạn trả tiền.
Cạm bẫy
- Tin vào tên tool model trả về — model có thể bịa tool không tồn tại. Allowlist theo tên là bắt buộc, và trả lỗi có cấu trúc thay vì crash.
- Không validate tham số —
unit: "Celsius"viết hoa,qty: "3"dạng chuỗi, ngày sai format. Chuẩn hoá trước khi gọi hàm thật. - Trả output tool quá lớn — một trang HTML 50 KB vào context vừa tốn tiền vừa làm model lạc. Cắt, tóm tắt, hoặc trả về trường cụ thể.
- Để tool output chứa chỉ dẫn — nội dung web/file là untrusted. Không bao giờ thực thi chỉ dẫn nằm trong kết quả tool mà không có kiểm tra.
- Dùng Chat Completions với model mới — tool call không hoạt động như mong đợi; đây là lỗi cấu hình, không phải lỗi model.
OpenAI hay Gemini?
| Tiêu chí | OpenAI Responses | Gemini generateContent |
|---|---|---|
| Khai báo tool | Phẳng, name/parameters |
functionDeclarations |
| Tham số trả về | Chuỗi JSON | Object |
| Kết quả tool | function_call_output + call_id |
Part functionResponse |
| Nối lượt | previous_response_id |
Gửi lại toàn bộ contents |
Chọn theo hệ sinh thái bạn đang dùng, không theo benchmark. Nếu bạn cần hosted tools và state phía provider, Responses tiện hơn. Nếu bạn cần một SDK duy nhất cho Developer API và Vertex AI, google-genai làm được cả hai, còn Vertex thêm IAM, VPC-SC và provisioned throughput.
Checklist triển khai
- Chốt schema trước: tên, mô tả, enum,
required,additionalProperties: false. - Dùng Responses cho OpenAI; chỉ dùng Chat Completions khi có lý do và đúng điều kiện model.
- Parse và validate tham số ở lớp tool, không ở prompt.
- Giữ
call_id/functionResponsekhớp và trả đủ kết quả trong một lượt. - Đặt trần song song, trần retry, và idempotency key cho tool có side effect.
- Gate các hành động không thể hoàn tác; log người duyệt và tham số.
- Đo token của schema và cảnh báo khi catalog tool phình ra.
Hướng tới 2027
Tool calling đang bị hút vào hai lớp chuẩn hoá: MCP ở tầng kết nối tool và Responses ở tầng state của provider. Điều đó nghĩa là code ứng dụng sẽ ít phụ thuộc vào cú pháp từng provider hơn, nhưng validation, phân quyền và idempotency vẫn là việc của bạn. Không có giao thức nào thay bạn kiểm tra tham số trước khi xóa một bản ghi.
Đọc tiếp: thiết kế công cụ và xử lý lỗi, MCP bản 2026-07-28, tool tìm kiếm, REPL và API, và prompt injection và sandboxing.