Sổ tay kỹ thuật

Troubleshooting AI agent và MCP

troubleshooting#agents#mcp#claude-code· cập nhật 2026-11-06

Xử lý agent không gọi tool, lặp vô hạn, tràn context, MCP server không kết nối và lỗi schema khi gọi tool.

Sửa trang này
Mục lục

Triệu chứng chính: agent trả lời bịa thay vì gọi tool, gọi đi gọi lại một tool, báo hết context, /mcp hiện server failed, hoặc API trả 400 invalid_request_error liên quan tools / tool_use.

Lỗi thường gặp

Triệu chứng Nguyên nhân Cách xử lý
Tool không bao giờ được gọi Description mơ hồ, tên trùng ý với tool khác, tool không có trong request Viết rõ "dùng khi...", kiểm tra tools thực gửi đi / /mcp thấy tool chưa
Model đoán kết quả thay vì gọi tool System prompt không yêu cầu dùng tool Thêm "luôn kiểm tra bằng tool, không đoán trạng thái thiết bị"; thử tool_choice={"type": "any"}
Gọi lặp một tool với cùng input Tool trả lỗi mơ hồ hoặc output không đổi Trả lỗi có hướng dẫn sửa; giới hạn số lượt (MAX_TURNS, recursion_limit)
Loop vô hạn giữa agent và tools Không có điều kiện dừng Đếm vòng, timeout tổng, dừng khi lặp cùng (tool, input) N lần
prompt is too long / context đầy Tool trả output lớn (show run, log) tích luỹ qua nhiều lượt Lọc output trong tool, phân trang; Claude Code: /compact, /clear, /context để xem cái gì chiếm chỗ
/mcp báo server failed Lệnh khởi động sai, thiếu dependency, sai thư mục Chạy y nguyên command args trong terminal, xem stderr
MCP kết nối rồi rớt, lỗi JSON Server print() ra stdout (stdio) Log ra stderr
Server HTTP không kết nối Sai URL path (/mcp), TLS, header auth curl -i tới URL, kiểm tra --header, claude mcp get <name>
Server trong .mcp.json không chạy Server project-scope chưa được duyệt Mở Claude Code trong project và chấp nhận; claude mcp reset-project-choices để hỏi lại
400 ... tool_use ids were found without tool_result blocks Thiếu tool_result cho một tool_use Trả đủ kết quả cho mọi tool_use.id trong một message user
400 liên quan input_schema Schema không hợp lệ (thiếu "type": "object", required chứa field không có) Validate schema bằng jsonschema, xem mẫu ở Thiết kế tool
Tool nhận sai kiểu ("3" thay vì 3) Thiếu kiểu trong schema / type hint Khai báo integer, enum; validate và trả lỗi rõ
Hook chặn nhầm / không chặn Matcher sai, exit code sai Xem settings và hooks: chặn phải exit 2

Các bước khoanh vùng

  1. Tool có tới được model không? Claude Code: /mcp xem danh sách tool. API: log tools trong request.
  2. Tool chạy độc lập có đúng không? Gọi hàm trực tiếp trong Python, hoặc dùng MCP Inspector (viết MCP server).
  3. Model nhận lại gì? In tool_result ra log: có quá dài, lỗi có rõ không.
  4. Vòng lặp có điểm dừng không? Kiểm tra stop_reason, giới hạn lượt, và điều kiện kết thúc trong graph.
  5. Context có bị chiếm bởi output cũ không? Đếm token (resp.usage.input_tokens tăng nhanh qua mỗi lượt là dấu hiệu).

Kiểm tra nhanh

# Claude Code + MCP
claude mcp list
claude mcp get netops
claude --debug=mcp                             # log chi tiết kết nối MCP
uv run --directory /opt/netops-mcp server.py   # chạy tay: phải đứng chờ stdin, không in gì ra stdout
 
# MCP Inspector
npx @modelcontextprotocol/inspector uv run --directory /opt/netops-mcp server.py
 
# Schema tool hợp lệ?
python3 -c 'import json,jsonschema; jsonschema.Draft202012Validator.check_schema(json.load(open("tool_schema.json"))); print("OK")'
 
# Settings hợp lệ?
python3 -m json.tool .claude/settings.json > /dev/null && echo OK
claude doctor

Khi agent hành xử lạ, thử lại với ít tool hơn. Mỗi tool thừa là một lựa chọn sai tiềm năng và tốn context cho phần mô tả.