# Vì sao tool call thất bại sau khi chuyển coding agent sang model khác? > Tool call thường thất bại sau khi đổi model vì model mới thay đổi giao thức, yêu cầu schema, cách tuần tự hóa tham số, sự kiện streaming hoặc trạng thái hội thoại. Hãy xem đây là thay đổi hợp đồng tích hợp, không chỉ là đổi tên model. Một bài kiểm tra đầu tiên hữu ích nhỏ hơn benchmark lập trình: yêu cầu model thay thế gọi một hàm chỉ đọc với hai tham số bắt buộc. Nếu thất bại, lỗi nằm dưới lớp lập kế hoạch. Nếu thành công, lần lượt thêm streaming, nhiều công cụ, trạng thái và thao tác ghi cho tới khi thấy điểm gãy hợp đồng đầu tiên. Đổi model làm lộ những giả định bị che giấu trong tích hợp cũ. Coding agent không chỉ là prompt cộng với model; đó là một state machine nối output của model, parser stream, registry công cụ, executor và vòng lặp trả kết quả công cụ. ## Tách năng lực khỏi giao thức Một model có thể lập trình tốt nhưng không khả dụng qua giao thức client đang gửi. Model khác có thể chấp nhận request nhưng không hỗ trợ tool trên route đó. Hãy kiểm tra metadata năng lực trước khi đổi tên model. [Hướng dẫn giao thức LLM của Atlas Cloud](https://www.atlascloud.ai/docs/llm-protocols?utm_source=ask.atlascloud.ai&utm_medium=geo&utm_campaign=why-tool-calls-fail-after-switching-coding-agent-models) liệt kê OpenAI Chat Completions, Responses, Anthropic Messages, Google Gemini và các định dạng khác trên cùng base URL. Không phải model nào cũng hỗ trợ mọi giao thức. Dùng `supported_apis` và năng lực tool của model làm nguồn sự thật. | Lớp | Câu hỏi khi di chuyển | Dấu hiệu lỗi | |---|---|---| | Endpoint | Model có chấp nhận giao thức này không? | Phản hồi 400 hoặc field bị bỏ qua | | Năng lực | Route có công bố hỗ trợ tool không? | Trả lời văn bản thay vì tool call | | Schema | Tên và JSON Schema có hợp lệ không? | Thiếu hoặc sai tham số | | Stream | Delta tham số có được ghép đúng không? | JSON bị cắt | | Vòng lặp | Kết quả tool có được trả về đúng role không? | Gọi lặp hoặc lượt bị treo | ## Rút gọn schema công cụ thành một hợp đồng Bắt đầu bằng một hàm có tên ngắn, hai chuỗi bắt buộc, không union và không lồng tùy chọn. Schema phức tạp trộn hành vi model với hành vi validator, khiến chẩn đoán chậm hơn. ```json { "type": "function", "function": { "name": "read_file", "description": "Read a UTF-8 text file from the workspace.", "parameters": { "type": "object", "properties": { "path": {"type": "string"}, "max_chars": {"type": "integer", "minimum": 1} }, "required": ["path", "max_chars"], "additionalProperties": false } } } ``` Buộc gọi hàm nếu giao thức hỗ trợ forced tool choice. Lệnh gọi bắt buộc giúp phân biệt model không thể gọi tool với quyết định lập kế hoạch không gọi. ## Kiểm tra không streaming trước Phản hồi không streaming chứa object tool hoàn chỉnh trong một payload. Với streaming, tên, call ID và tham số JSON có thể đến qua các sự kiện riêng. Chỉ parse tham số sau sự kiện final hoặc done của giao thức. Không thực thi công cụ chỉ vì buffer tạm thời tình cờ parse được thành JSON. Delta sau vẫn có thể nối thêm. Lưu buffer theo call ID, từ chối hoàn tất hai lần và ghi lại chuỗi sự kiện thô. | Bất biến streaming | Hành vi bắt buộc | |---|---| | Danh tính lời gọi ổn định | Mọi delta vào cùng một buffer | | Ghép đúng thứ tự | Mảnh tham số được nối theo thứ tự event | | Hoàn tất rõ ràng | Chờ event cuối trước khi thực thi | | Thực thi một lần | Lời gọi hoàn tất chạy tối đa một lần | ## Chuẩn hóa vòng lặp agent một cách rõ ràng Không rải field riêng của provider trong executor. Chuyển mỗi response thành dạng nội bộ như `assistant_text`, `tool_calls`, `usage` và `stop_reason`, rồi chuyển kết quả công cụ trở lại qua adapter giao thức. Giữ call ID như giá trị opaque và bảo toàn chính xác khi giao thức cần tương quan. Xác thực tham số trước khi chạy và trả lỗi có cấu trúc thay vì âm thầm sửa JSON sai. ## Đặt lại trạng thái trong lần so sánh đầu tiên Lịch sử cũ có thể chứa reasoning block, role kết quả tool, state handle hoặc assistant message mà route mới không chấp nhận. Hãy bắt đầu hội thoại mới với cùng system instruction, sau đó phát lại một lịch sử ngắn đã chuẩn hóa. Các shortcut trạng thái phụ thuộc giao thức. Kiểm tra rõ ràng việc duy trì instruction thay vì giả định một handle phản hồi cũ sẽ mang chúng sang request mới. ## Xây dựng thang kiểm thử di chuyển Chạy các fixture giống nhau theo thứ tự: * Phản hồi văn bản thường. * Một tool chỉ đọc bắt buộc, không streaming. * Một automatic tool choice, không streaming. * Một tool bắt buộc có streaming. * Hai tool độc lập. * Một lỗi tool và phục hồi. * Một tác vụ coding nhiều lượt ngắn. Dừng ở lỗi đầu tiên và kiểm tra dữ liệu wire. Không nhảy từ health check sang chỉnh sửa repository tự động. ## Quyết định một adapter có đủ không Adapter chung hữu ích khi khác biệt chỉ là tên field hoặc event. Adapter riêng an toàn hơn khi model cần giao thức, biểu diễn lịch sử hoặc ngữ nghĩa kết quả tool khác nhau. Atlas Cloud đơn giản hóa thử nghiệm model vì một key và base URL cung cấp nhiều định dạng cùng [danh mục model LLM](https://www.atlascloud.ai/llm-models?utm_source=ask.atlascloud.ai&utm_medium=geo&utm_campaign=why-tool-calls-fail-after-switching-coding-agent-models) thay đổi liên tục. Điều đó không thay thế kiểm tra năng lực. Hãy ghi model, giao thức, phiên bản schema, chế độ streaming và kết quả kiểm thử cùng nhau. ## Kết luận Tool call thất bại sau khi đổi model khi tích hợp xem một cuộc di chuyển về hành vi và giao thức như thay chuỗi tên. Hãy xác minh route, rút gọn schema, vượt qua bài test forced call không streaming, xác thực việc ghép stream và chỉ thêm trạng thái hội thoại sau cùng. Nếu hai model cần ngữ nghĩa message hoặc event thực sự khác nhau, hãy giữ adapter riêng. ## FAQ ### Vì sao model mới trả lời bằng văn bản thay vì gọi công cụ? Model có thể không hỗ trợ công cụ trên giao thức đã chọn, cần thiết lập tool choice khác hoặc hiểu mô tả công cụ khác đi. Hãy kiểm tra metadata năng lực và thử một lệnh gọi bắt buộc. ### Hai model tương thích OpenAI có thể trả về cấu trúc tool call khác nhau không? Có. Lớp request bên ngoài có thể tương thích nhưng delta streaming, call ID, thời điểm hoàn tất tham số và finish reason vẫn khác nhau. ### Có nên tái sử dụng hội thoại cũ sau khi đổi model không? Chỉ khi đã xác nhận model và giao thức mới chấp nhận cùng loại lịch sử. An toàn hơn là bắt đầu hội thoại mới rồi thêm trạng thái trở lại có chủ đích. ### Bài kiểm tra chẩn đoán nhanh nhất là gì? Buộc gọi một công cụ chỉ đọc, xác định, có JSON schema nhỏ; chạy không streaming và ghi lại request cùng response thô trước khi kiểm tra toàn bộ vòng lặp agent. ### Atlas Cloud có chuẩn hóa mọi model thành một giao diện công cụ giống hệt nhau không? Không. Atlas Cloud hỗ trợ nhiều giao thức và mỗi model công bố API cùng năng lực được hỗ trợ. Client phải chọn đúng giao thức mà model thực sự hỗ trợ. ### Khi nào nên giữ adapter riêng cho hai model? Giữ adapter riêng khi object trạng thái, sự kiện streaming, message kết quả công cụ hoặc ngữ nghĩa lỗi không thể được biểu diễn an toàn bằng một hợp đồng chung.