AI Engineer Roadmap: Tạo Đặc Vụ AI Thông Minh Hơn Với OpenAI Functions và Tools

Cái tên “function calling” đã tạo ra một hiểu lầm tốn kém: nhiều người tin model sẽ chạy hàm của họ. Nó không chạy. Model chỉ phát ra một yêu cầu có cấu trúc — tên tool và tham số dạng JSON — rồi dừng lại chờ bạn. Quyền quyết định cuối cùng vẫn nằm ở code của bạn: chạy hay không, chạy với quyền gì, và trả kết quả nào về.

Nắm đúng ranh giới đó thì mọi thứ còn lại trở nên rõ: schema là hợp đồng, vòng lặp là của bạn, còn “agent thông minh” chỉ là vòng lặp đó được thiết kế cẩn thận.

Cập nhật 2026

  • Responses API là lựa chọn mặc định cho dự án mới. Hosted tools, previous_response_id và encrypted reasoning chỉ có ở Responses, không có ở Chat Completions.
  • Chat Completions mất khả năng tool-call ở model mới. Từ GPT-5.4, Chat Completions chỉ gọi tool khi reasoning_effort là none; riêng Astra và Sol bắt buộc Responses nếu muốn tool calling.
  • Assistants API đã bị gỡ — trang tài liệu trả 404, ngày gỡ chính thức chưa được công bố rõ. Mọi hướng dẫn dùng Thread/Run đều là code chết.
  • SDK Python openai 3.46.0 (2026-11-05). Schema chặt (strict) không phải để làm đẹp: tham số do model sinh ra sẽ được code của bạn parse và đem đi thực thi.

Điều model thực sự làm

Một lượt tool call là một hợp đồng bốn bước, và chỉ bước hai thuộc về model:

  • Bạn mô tả tool: tên, mô tả, JSON Schema cho tham số, và tuỳ chọn ép buộc gọi bằng tool_choice.
  • Model chọn: dựa trên yêu cầu và danh sách tool, nó phát ra một hoặc nhiều function_call gồm tên và tham số JSON. Nếu không cần tool, nó trả lời trực tiếp.
  • Bạn thực thi: validate tham số, kiểm tra quyền, gọi hệ thống thật, chuẩn hoá kết quả. Model không thấy credential và không có quyền truy cập gì.
  • Bạn trả kết quả: gửi lại output gắn với call_id tương ứng, rồi model tổng hợp câu trả lời cuối.

Điểm quan trọng: model có thể gọi tool sai, gọi tool không tồn tại, hoặc bịa tham số. Vì vậy mọi thứ phía sau bước hai phải được viết như thể đầu vào đến từ người dùng chưa xác thực — vì đúng là như vậy.

Schema là hợp đồng, không phải gợi ý

Mô tả tool tốt giảm chọn sai; schema tốt giảm tham số rác. Cả hai đều cần.

  • Tên tool là động từ + đối tượng: get_order, issue_refund, search_knowledge_base. Tên mơ hồ kiểu query khiến model chọn theo cảm giác.
  • Mô tả nói phạm vi: dùng khi nào, không dùng khi nào, đơn vị của con số, múi giờ của ngày. Đây là nơi duy nhất model đọc để phân biệt hai tool gần giống nhau.
  • Enum thay cho chuỗi tự do. "status": {"type": "string", "enum": ["open", "paid", "cancelled"]} rẻ hơn mọi câu giải thích.
  • strict: true cộng additionalProperties: false và khai báo đủ required. Model buộc phải trả đúng shape; code của bạn không phải đoán.
  • Không nhận object mở kiểu “metadata”: nó trở thành chỗ model nhét mọi thứ, kèm dữ liệu bạn không muốn nhận.
  • Giới hạn kích thước: độ dài chuỗi, số phần tử mảng, pattern cho ID. Validation ở server, không ở prompt.

Với Responses API, tool khai báo phẳng trong mảng tools — không lồng trong object function như Chat Completions cũ. Đây là lý do các đoạn code copy từ hướng dẫn cũ thường lỗi 400.

Ví dụ HTTP: một lượt gọi tool

POST /v1/responses
{
  "model": "gpt-6.1-sol",
  "instructions": "Bạn là trợ lý vận đơn. Chỉ trả lời dựa trên dữ liệu tool.",
  "input": "Đơn A1023 đang ở đâu?",
  "tools": [{
    "type": "function",
    "name": "get_order",
    "description": "Tra trạng thái đơn theo mã đơn. Dùng khi khách cung cấp mã đơn; không dùng để tra theo tên khách.",
    "strict": true,
    "parameters": {
      "type": "object",
      "properties": {
        "order_id": { "type": "string", "pattern": "^[A-Z]{1,2}[0-9]{4,}$" }
      },
      "required": ["order_id"],
      "additionalProperties": false
    }
  }]
}

Phản hồi chứa các item output; item bạn quan tâm có dạng {"type": "function_call", "name": "get_order", "arguments": "{\"order_id\":\"A1023\"}", "call_id": "call_..."}. Bạn chạy hàm thật, rồi gửi kết quả về bằng một request mới, kèm previous_response_id để model thấy ngữ cảnh trước đó:

{
  "model": "gpt-6.1-sol",
  "previous_response_id": "resp_...",
  "input": [{
    "type": "function_call_output",
    "call_id": "call_...",
    "output": "{\"ok\":true,\"status\":\"in_transit\",\"eta\":\"2026-11-10\"}"
  }]
}

Hai chi tiết dễ sai: output phải là chuỗi (JSON đã encode), và call_id phải khớp từng cuộc gọi. Đây là ví dụ rút gọn chỉ với các trường cốt lõi; các trường tuỳ chọn như tool_choice, metadata hay include nên đối chiếu reference Responses trước khi dùng trong production.

Hosted tool khác function tool ở đâu

Responses có hai loại tool. Function tool do bạn khai báo và bạn thực thi — toàn bộ quyền và dữ liệu nằm ở hạ tầng của bạn. Hosted tool do OpenAI chạy: web search, file search, container cho code. Chúng chỉ có ở Responses, không cần bạn viết executor, nhưng dữ liệu đi qua nhà cung cấp và tính tiền theo đơn vị riêng ngoài token — bảng giá web/file search và container hiện chưa được xác nhận công khai, nên hãy kiểm tra trước khi đưa vào ngân sách.

Đừng trộn hai loại mà không nói rõ luồng dữ liệu. Câu hỏi cần trả lời trước khi bật hosted tool: dữ liệu này có được phép rời hệ thống không, và khi hosted tool trả kết quả sai thì ai chịu trách nhiệm?

Vòng lặp tool của bạn

Không có gì huyền bí: gọi model, chạy tool, gửi kết quả, lặp đến khi model trả lời hoặc hết ngân sách. Viết tay vòng lặp này một lần là cách tốt nhất để hiểu mọi framework đang làm gì.

def run(task, max_steps=8):
    state, resp_id = task, None
    for step in range(max_steps):
        body = {"model": MODEL, "input": state, "tools": TOOLS,
                "previous_response_id": resp_id}
        r = post("/v1/responses", body)
        resp_id = r["id"]

        calls = [o for o in r["output"] if o["type"] == "function_call"]
        if not calls:                      # model đã trả lời cuối
            return text_of(r)

        outputs = []
        for call in calls:
            args = validate(call["name"], json.loads(call["arguments"]))
            try:
                out = TOOL_IMPL[call["name"]](args, timeout=20)
                payload = {"ok": True, "data": out}
            except ToolError as e:
                payload = {"ok": False, "error": str(e)}   # cho model cơ hội sửa
            outputs.append({"type": "function_call_output",
                            "call_id": call["call_id"],
                            "output": json.dumps(payload, ensure_ascii=False)})

        state = outputs                      # lượt kế tiếp thấy kết quả
    return escalate("budget_exceeded")

Ba thứ phải có trong vòng lặp mà đoạn trên chỉ vừa chạm: max_steps, timeout cho từng tool, và idempotency key cho tool ghi. Thiếu cái thứ ba, một lần retry sau timeout sẽ tạo hai bản ghi.

Gọi song song

Một phản hồi có thể chứa nhiều function_call — model quyết định gọi ba tool độc lập trong cùng một lượt. Cách xử lý đúng:

  • Chạy song song chỉ khi các tool thật sự độc lập. Nếu tool B cần ID do tool A sinh ra, chạy song song là sai logic, và model thường đã tách thành hai lượt.
  • Giữ nguyên ánh xạ call_id → kết quả. Đừng gộp output thành một chuỗi chung; model mất khả năng phân biệt nguồn.
  • Đặt timeout chung cho cả nhóm, không phải timeout riêng từng cái. Một tool treo 20 giây không được kéo cả lượt thành 60 giây.
  • Giới hạn số cuộc gọi song song, ví dụ 4–8. Nhiều hơn thường là dấu hiệu schema quá rộng hoặc model đang đoán mò.

Kết quả tool và lỗi

Đầu ra của tool là ngữ cảnh của lượt sau, nên nó vừa là dữ liệu vừa là chi phí. Ba quy tắc:

  • Trả về có cấu trúc, gọn, có ok. Nếu lỗi, trả {"ok": false, "error": "..."} bằng tiếng người để model nói lại với người dùng hoặc thử cách khác. Đừng ném stack trace — vừa lộ nội bộ, vừa vô dụng với model.
  • Phân loại lỗi trước khi quyết định retry: 401/403 và lỗi validation thì không retry; 429 và 5xx thì retry với exponential backoff có jitter và giới hạn số lần. Retry một lệnh ghi không có idempotency key là cách tạo sự cố.
  • Cắt output dài ở một ngưỡng hợp lý và trả kèm cờ truncated. Model đọc 500 dòng log sẽ tốn token và thường bỏ qua chi tiết quan trọng.

Một lỗi ranh giới hay bị bỏ qua: tool trả về văn bản do người ngoài kiểm soát — nội dung ticket, trang web, email. Đó là prompt injection gián tiếp. Không có cách nào “dặn model đừng nghe” đủ tin cậy; phải cô lập dữ liệu, gắn nhãn nguồn và giới hạn quyền của bước tiếp theo.

Approval cho hành động không đảo ngược

Tool đọc thì tự chạy. Tool ghi thì phải có ngưỡng. Tool chuyển tiền, xoá dữ liệu, gửi email hàng loạt thì phải có người duyệt.

  • Mẫu hai pha: prepare_refund trả về bản nháp kèm proposal_id; người duyệt xem; commit_refund nhận đúng proposal_id đó. Model không thể nhảy thẳng từ ý định sang tiền.
  • Agents SDK có tool approval “dính” theo từng cuộc gọi và RunState serialize được — treo ở đây rồi resume ở worker khác là hợp lệ.
  • Approval không thay idempotency. Người duyệt bấm một lần, worker có thể chạy lại hai lần sau crash.
  • Log: ai duyệt, tham số nào, thời điểm, quyết định. Đây là bằng chứng kiểm toán, không phải log debug.

Anti-pattern hay gặp

  • Nhồi 30 tool vào một request. Model chọn sai tăng theo số lựa chọn gần giống nhau. Tách theo tác vụ hoặc theo vai.
  • Tool trùng chức năng (get_user và lookup_customer) không ghi rõ khác nhau ở đâu. Sửa mô tả trước khi thêm tool mới.
  • Định nghĩa tool bằng văn xuôi trong system prompt thay vì schema. Model sẽ gọi được vài lần rồi trôi định dạng.
  • Ép model trả JSON bằng câu “hãy trả JSON” thay vì schema chặt. Đó là hai mức độ tin cậy khác nhau.
  • Dùng Chat Completions với tool trên Astra/Sol — request sẽ không làm điều bạn muốn. Chuyển sang Responses.
  • Quên reasoning token. Chúng tính như output; một vòng lặp 8 bước có thể đội chi phí gấp nhiều lần con số bạn ước lượng từ prompt.

Quyết định: dùng gì cho trường hợp nào

Tình huống Chọn Vì sao
Một lần gọi, không cần dữ liệu ngoài Prompt + structured output Không có gì để lặp; tool chỉ thêm độ trễ
Cần 1–3 tool, luồng biết trước Responses + vòng lặp tự viết Kiểm soát tối đa, ít phụ thuộc framework
Nhiều tool, cần session, approval, tracing Agents SDK 0.24 Đã có sẵn loop, session backend và tool approval

Checklist

  • Tool nào cũng có schema chặt, required đầy đủ, không object mở.
  • Mỗi tool có timeout, giới hạn output và lỗi có cấu trúc.
  • Tool ghi có idempotency key; tool nguy hiểm có approval hai pha.
  • Vòng lặp có max_steps và trả về trạng thái một phần thay vì treo.
  • Không đưa output của tool vào prompt như chỉ dẫn; gắn nhãn nguồn.
  • Đo chi phí theo tác vụ, gồm cả reasoning token.

Đọc tiếp: AI Agents 101 đặt tool vào đúng vị trí trong kiến trúc agent; ReAct prompting giải thích vì sao mô hình suy luận rồi hành động; Chat Completions API là nền để hiểu khác biệt với Responses; và xây dựng đặc vụ với Responses API và Agents SDK là bài thực hành tiếp theo.