Chuyển đến nội dung
MINH VO Ghi chép từ công việc
của một kỹ sư tại Việt Nam
Cơ bản9 phút đọc

Hiểu vòng gọi công cụ qua ví dụ tra cứu thời tiết

Theo dõi lời gọi thời tiết qua kiểm tra, thực thi và gắn kết quả; chạy bộ thực thi nhỏ để phân biệt lỗi tham số, thiếu số đo và hết thời gian.

Sổ tay mở với các hình khối trừu tượng và sợi chỉ màu ô liu nối những mảnh giấy

Với lập trình viên đang thêm công cụ vào ứng dụng LLM, mô hình đề xuất lời gọi, còn ứng dụng quyết định có thực thi hay không và thực thi thế nào. Kết quả sau đó có thể được trả về mô hình để tạo đáp án cho người dùng. Tên công cụ do mô hình sinh là yêu cầu thực hiện một thao tác, chưa phải bằng chứng thao tác đã xảy ra.

Tra cứu thời tiết chỉ đọc là ví dụ khởi đầu hữu ích vì tác động nhỏ và quan sát được. Giả sử người dùng hỏi “Thời tiết Đà Nẵng thế nào?” Ứng dụng cung cấp công cụ nhận mã địa điểm và đơn vị nhiệt độ. Ta cần kiểm tra được từng bước từ câu hỏi đó tới đáp án hiển thị.

Mô tả hợp đồng của công cụ

Ứng dụng định nghĩa tên công cụ được phép, mục đích và schema cho tham số. Schema dưới đây là hợp đồng ứng dụng rút gọn, không phải toàn bộ thân yêu cầu của API từ nhà cung cấp cụ thể:

{
  "name": "get_current_weather",
  "description": "Read current observed weather for one supported location.",
  "parameters": {
    "type": "object",
    "properties": {
      "location_id": {"type": "string"},
      "unit": {"type": "string", "enum": ["celsius", "fahrenheit"]}
    },
    "required": ["location_id", "unit"],
    "additionalProperties": false
  }
}

Mô tả ghi “thời tiết đang quan sát” để tránh hiểu nhầm đây là dịch vụ dự báo. Mã địa điểm giúp tránh tên thành phố dạng văn bản có thể mơ hồ. Trong ứng dụng thực tế, mô hình có thể cần bước tìm địa điểm riêng hoặc hỏi rõ trước khi có mã hợp lệ.

Tài liệu gọi hàm của OpenAI, truy cập ngày 20 tháng 9 năm 2026, mô tả luồng nhiều bước trong đó ứng dụng thực thi hàm được yêu cầu rồi trả kết quả. Cấu trúc bao ngoài khác nhau giữa API và phiên bản. Điều cần giữ là ranh giới giữa lời gọi được đề xuất và việc ứng dụng thực sự thực thi.

Theo dõi một dấu vết cụ thể

Giả sử mô hình trả về lời gọi mã call-17, tên get_current_weather, với tham số cho địa điểm được hỗ trợ vn-da-nang. Ứng dụng phân tích tham số, kiểm tra schema, rồi kiểm tra công cụ có được phép dùng cho yêu cầu hiện tại không và mã địa điểm có tồn tại không.

Chỉ sau các bước đó, ứng dụng mới gọi dịch vụ thời tiết. Giả sử dịch vụ trả về số đo giả định 29 độ C cùng thời điểm quan sát. Ứng dụng gắn kết quả với cùng mã lời gọi. Mô hình lúc này có thể giải thích số đo và độ cũ của nó cho người dùng.

Yêu cầu công cụ thời tiết đi qua kiểm tra và thực thi trước khi số đo có cùng mã lời gọi được trả về mô hìnhMở ảnh kích thước đầy đủ ↗

Nhiệt độ trong hình chỉ để minh họa, không phải thông tin thời tiết hiện tại. Mã lời gọi đặc biệt quan trọng khi một phản hồi chứa nhiều lời gọi được đề xuất: mỗi kết quả phải gắn với đúng yêu cầu tạo ra nó. Gắn thời tiết thành phố này vào yêu cầu của thành phố khác sẽ tạo đáp án nghe hợp lý nhưng sai.

Ứng dụng cần tách việc truyền tin thành công khỏi việc công cụ thành công. Phản hồi HTTP có thể về bình thường nhưng cho biết địa điểm không tồn tại hoặc không có số đo. Mô hình cần trạng thái đúng như no_observation, không phải đối tượng thành công rỗng khiến nó tự điền phần thiếu.

Kiểm tra nhiều hơn hình dạng JSON

Schema có thể từ chối đơn vị không hỗ trợ, trường thiếu hoặc thuộc tính thừa. Nó không chứng minh địa điểm thuộc tổ chức của người dùng hay thao tác được phép. Đó là kiểm tra của ứng dụng. Với thời tiết, kiểm tra này có thể đơn giản; với công cụ tìm khách hàng nội bộ, nó quyết định dữ liệu nhạy cảm có bị lộ không.

Cũng cần xử lý mô tả công cụ theo nguồn gốc của nó. Đặc tả công cụ MCP phiên bản 2025-06-18 định nghĩa thông điệp khám phá và gọi công cụ. Tương thích giao thức không biến mọi máy chủ kết nối thành nguồn đáng tin. Host phải đánh giá mô tả do máy chủ đưa ra trong chính sách bảo mật của mình.

Kết quả công cụ cũng có thể chứa văn bản không đáng tin. Trường mô tả của nhà cung cấp thời tiết không được có quyền yêu cầu tải tệp lên chỉ vì mô hình đọc được nó. Bộ thực thi chỉ cho phép năng lực nằm trong tác vụ, bất kể kết quả chứa lời nhắc gì.

Thực thi một lời gọi trước khi xây vòng lặp

Một bộ thực thi nhỏ làm ranh giới này quan sát được. Hàm Python sau nhận cấu trúc lời gọi đã được phân tích, có id dạng chuỗi không rỗng và không trùng, name dạng chuỗi cùng trường arguments. Ứng dụng bên ngoài chịu trách nhiệm kiểm tra cấu trúc bao và tính duy nhất. Hàm kiểm tra tham số riêng của công cụ trước khi gọi adapter dịch vụ được truyền vào; nó không tra cứu tùy ý hàm thực thi theo tên sinh ra.

def execute_weather(call, read_weather, allowed_locations):
    def reply(status, **fields):
        return {"call_id": call["id"], "status": status, **fields}

    if call["name"] != "get_current_weather":
        return reply("unsupported_tool")
    args = call["arguments"]
    if (type(args) is not dict
            or set(args) != {"location_id", "unit"}
            or type(args["location_id"]) is not str
            or type(args["unit"]) is not str
            or args["unit"] not in {"celsius", "fahrenheit"}):
        return reply("invalid_arguments")
    if args["location_id"] not in allowed_locations:
        return reply("unsupported_location")
    try:
        observation = read_weather(args["location_id"], args["unit"])
    except TimeoutError:
        return reply("unavailable")
    if observation is None:
        return reply("no_observation")
    return reply("observed", observation=observation)

calls = []
def stub(location, unit):
    calls.append((location, unit))
    return {"value": 29, "unit": "celsius", "observed_at": "2026-09-21T01:00:00Z"}

call = {"id": "call-17", "name": "get_current_weather",
        "arguments": {"location_id": "vn-da-nang", "unit": "celsius"}}
print(execute_weather(call, stub, {"vn-da-nang"}))
print(len(calls))

Ví dụ nguyên trạng trả về observed, giữ call-17 và gọi stub một lần. Thời điểm cùng nhiệt độ đều là dữ liệu kiểm thử giả định. Đổi đơn vị thành kelvin hoặc thêm tham số user_id: trạng thái trở thành invalid_arguments, dịch vụ không nhận thêm lời gọi. Tập địa điểm được phép phải đến từ cấu hình ứng dụng hoặc phạm vi đã xác thực, không phải danh sách do mô hình cung cấp.

Hợp đồng của adapter cũng quan trọng. Stub tối thiểu chỉ cung cấp phản hồi Celsius đang minh họa. Adapter thật phải kiểm tra dữ liệu của nhà cung cấp và trả đúng đơn vị yêu cầu, số đo hữu hạn, thời điểm dùng được hoặc lỗi rõ ràng. Bộ thực thi này giả định adapter đáp ứng hợp đồng đó; nó không kiểm tra mọi dictionary kết quả tùy ý. Cần thử adapter Fahrenheit riêng để tham số đúng không dẫn tới giá trị Celsius bị gắn nhãn Fahrenheit. Ngoại lệ adapter ngoài dự kiến phải đi vào xử lý lỗi có kiểm soát của ứng dụng, không bị che thành số đo rỗng hợp lệ.

Các kết quả của bộ thực thi phân biệt có số đo, thiếu số đo, hết thời gian và tham số bị từ chối trước khi gọi dịch vụMở ảnh kích thước đầy đủ ↗

Thay stub bằng hàm trả None, rồi hàm ném TimeoutError: mỗi hàm được gọi một lần nhưng trạng thái khác nhau. Tiếp theo thực thi call-17 và call-18 cho hai địa điểm được hỗ trợ, giữ nguyên mã dù triển khai bất đồng bộ sau này hoàn thành chúng theo thứ tự ngược lại. Bên gọi phải từ chối mã trùng trước khi gửi đi; hàm xử lý một lời gọi này không tự bảo đảm tính duy nhất giữa nhiều yêu cầu.

Bài kỹ thuật Anthropic của Ken Aizawa ngày 11 tháng 9 năm 2025 khuyến nghị đọc bản ghi công cụ thô cùng kết quả tác vụ và số lỗi. Cách đó giúp phân biệt chọn sai công cụ với thực thi thất bại. Hướng dẫn đánh giá của nguồn nhắm tới tác vụ thực tế; stub thời tiết xác định ở đây chỉ kiểm tra hành vi bộ thực thi, chưa cho thấy mô hình hiểu câu hỏi thời tiết của người dùng thật.

Giới hạn vòng lặp

Một số yêu cầu cần thêm lời gọi sau kết quả đầu. Nếu địa điểm mơ hồ, trợ lý có thể tìm địa điểm rồi mới lấy thời tiết. Nếu nhà cung cấp lỗi tạm thời, ứng dụng có thể thử lại. Cần đặt số lời gọi tối đa và thời hạn tổng để các đường đi này không lặp vô hạn.

Trạng thái kết thúc nên rõ ràng: hoàn thành với số đo, cần làm rõ, tạm thời không khả dụng hoặc bị từ chối vì yêu cầu không hỗ trợ. Đáp án cuối phải phản ánh trạng thái ấy. Nói “tôi đã kiểm tra thời tiết” là sai nếu dịch vụ hết thời gian trước khi trả được quan sát nào.

Với kiểm thử đầu tiên, dùng dịch vụ stub có phản hồi biết trước. Xác minh tham số hợp lệ gọi dịch vụ một lần, đơn vị không hợp lệ gọi không lần nào và hết thời gian dẫn tới đáp án không khả dụng. Thêm trường hợp hai lời gọi để kiểm tra mã tương quan. Những phép thử này kiểm tra vòng xử lý ứng dụng, không cần nhà cung cấp thời tiết thật hay kết luận về chất lượng mô hình.

Khi vòng xử lý đã đúng, mới đánh giá mô hình có chọn đúng công cụ và tham số từ cách hỏi thực tế không. Giữ phép đánh giá đó riêng với độ đúng của bộ thực thi. Bộ thực thi hoàn hảo không sửa được mọi câu hỏi bị hiểu sai; mô hình chính xác cũng không nên phải bù cho việc thiếu kiểm tra quyền hoặc xử lý kết quả mơ hồ.

Nguồn tham khảo & đọc thêm

  1. OpenAI function calling guide
  2. MCP tools specification, 2025-06-18
  3. Ken Aizawa: Writing effective tools for agents — with agents
← Về trang bài viết

Hình minh họa

100%