Sửa lỗi ValueError 'No tool found with name' trong CrewAI

Thông báo lỗi

Ít có điều gì gây khó chịu hơn việc hệ thống đa tác nhân (multi-agent) của bạn bị dừng đột ngột ngay khi nó bắt đầu suy nghĩ. Bạn có thể thấy một traceback như thế này ngay sau khi agent cố gắng thực hiện một hành động:

ValueError: No tool found with name 'search_tool'. Make sure you have registered the tool correctly.

Tại sao lỗi này xảy ra?

CrewAI rất nghiêm ngặt về ngữ cảnh thực thi. Không giống như các wrapper đơn giản khác, nó yêu cầu một liên kết trực tiếp giữa một agent và các công cụ (tools) mà nó được phép sử dụng. Lỗi này xảy ra khi LLM quyết định sử dụng một công cụ cụ thể, nhưng công cụ đó không nằm trong registry cục bộ của nó.

Thông thường, một trong ba nguyên nhân sau đây là thủ phạm:

Công cụ tồn tại trong script của bạn nhưng không được truyền vào constructor của Agent.
Bạn đã truyền một danh sách các chuỗi (tên) thay vì các đối tượng công cụ thực tế.
Có sự sai lệch tên giữa decorator @tool tùy chỉnh của bạn và kỳ vọng của agent.

Cách sửa 1: Đăng ký công cụ một cách rõ ràng với Agent

Nguyên nhân phổ biến nhất là thiếu mục nhập trong định nghĩa agent. Việc định nghĩa một công cụ trên toàn cục không tự động cấp quyền truy cập cho agent. Bạn phải truyền nó một cách rõ ràng thông qua tham số tools.

Cách làm sai:

from crewai import Agent
from crewai_tools import SerperDevTool

search_tool = SerperDevTool()

# Agent không nhận thấy search_tool ở đây
researcher = Agent(
  role='Researcher',
  goal='Find 2024 AI trends',
  backstory='Expert researcher',
  verbose=True
)

Cách làm đúng:

from crewai import Agent
from crewai_tools import SerperDevTool

search_tool = SerperDevTool()

# Truyền đối tượng công cụ vào trong một danh sách
researcher = Agent(
  role='Researcher',
  goal='Find 2024 AI trends',
  backstory='Expert researcher',
  verbose=True,
  tools=[search_tool] # Điều này liên kết đối tượng với agent
)

Cách sửa 2: Truyền đối tượng, không phải chuỗi

CrewAI yêu cầu một List[BaseTool], không phải List[str]. Nếu bạn cố gắng truyền tools=['search_tool'], agent sẽ thất bại. Nó không thể tự giải quyết một tên chuỗi thành một hàm có thể thực thi.

# SAI: Điều này sẽ kích hoạt ValueError
agent = Agent(..., tools=['search_tool'])

# ĐÚNG: Truyền instance
search_tool = SerperDevTool()
agent = Agent(..., tools=[search_tool])

Cách sửa 3: Đồng bộ tên công cụ tùy chỉnh

Nếu bạn sử dụng decorator @tool, tên hàm sẽ trở thành ID duy nhất của công cụ. Nếu bạn ghi đè tên trong decorator một cách thủ công, bạn phải đảm bảo LLM biết chính xác tên đó. Một lỗi đánh máy nhỏ ở đây sẽ làm hỏng vòng lặp thực thi.

from langchain.tools import tool

@tool("web_search_api")
def my_custom_search(query: str):
    """Hữu ích cho việc tìm kiếm web."""
    return "Kết quả..."

# Công cụ hiện được đăng ký là "web_search_api", KHÔNG PHẢI "my_custom_search"
researcher = Agent(
    role='Analyst',
    tools=[my_custom_search],
    verbose=True
)

Cách sửa 4: Kiểm tra việc gán công cụ ở cấp độ Task

Trong CrewAI v0.28.0 và các phiên bản mới hơn, bạn có thể giới hạn công cụ cho các task cụ thể. Nếu mô tả task yêu cầu rõ ràng một công cụ mà agent được chỉ định không có, hệ thống có thể bị lỗi. Hãy đảm bảo công cụ có sẵn ở cấp độ Task nếu bạn muốn an toàn.

task1 = Task(
  description='Search for 5 specific AI startups.',
  expected_output='A list of names.',
  agent=researcher,
  tools=[search_tool] # Cấp quyền sử dụng công cụ một cách rõ ràng cho task này
)

Xác minh: Chạy kiểm tra sức khỏe

Để xác nhận việc sửa lỗi, hãy thêm một câu lệnh print trước khi bạn bắt đầu crew. Điều này xác minh rằng agent thực sự "nhìn thấy" các công cụ mà bạn nghĩ rằng nó có.

Thêm print(f"Agent Tools: {researcher.tools}") vào script của bạn.
Chạy mã. Bạn sẽ thấy một danh sách các đối tượng như [<SerperDevTool name='search_tool'>].
Theo dõi log. Nếu verbose=True, bạn sẽ thấy Action: search_tool theo sau là Observation. Nếu vòng lặp tiếp tục, việc ánh xạ đã thành công.

Mẹo chuyên nghiệp để phòng ngừa

Giữ cho môi trường của bạn sạch sẽ. Chạy pip install --upgrade crewai crewai-tools để đảm bảo bạn không gặp phải các lỗi từ các phiên bản cũ hơn. Luôn sử dụng docstring mô tả trong các công cụ tùy chỉnh. CrewAI sử dụng các docstring đó để cho LLM biết chính xác khi nào và làm thế nào để sử dụng công cụ, ngăn chặn việc "ảo tưởng" tên công cụ không tồn tại trong registry của bạn.