CrewAI Tools 연동: Agent가 진짜로 찾고, 읽고, 실행하게 만들기

3 min read

Tool 없는 Agent는 이론은 많은데 키보드가 없는 엔지니어와 같습니다.
말은 잘하지만 결과물을 못 냅니다.

자주 쓰는 내장 Tool

  • SerperDevTool: 웹 검색
  • FileReadTool: 파일 읽기
  • FileWriterTool: 파일 쓰기
  • ScrapeWebsiteTool: 웹페이지 수집

Agent에 Tool 붙이기

from crewai import Agent
from crewai_tools import SerperDevTool
 
search_tool = SerperDevTool()
 
researcher = Agent(
    role="Researcher",
    goal="Find trustworthy sources about the topic",
    backstory="You validate facts before writing.",
    tools=[search_tool],
    allow_delegation=False,
    verbose=True,
)

💡 같은 search_tool을 여러 Agent가 공유할 수 있습니다. 매번 새로 만들 필요 없습니다(DRY).

커스텀 Tool 최소 템플릿

from crewai.tools import BaseTool
from pydantic import BaseModel, Field
 
class QueryInput(BaseModel):
    keyword: str = Field(description="Search keyword")
 
class KeywordTool(BaseTool):
    name: str = "Keyword Tool"
    description: str = "Return a short explanation for a keyword."
    args_schema: type[BaseModel] = QueryInput
 
    def _run(self, keyword: str) -> str:
        return f"Result for: {keyword}"

Tool 설계 4원칙

  1. 한 가지 일만 하기: 검색 Tool이 파일 저장까지 하지 않기
  2. 설명 명확히 쓰기: description에 용도/입력을 분명히
  3. 입력 검증하기: Pydantic 스키마 사용
  4. 반환 형식 고정하기: 후속 Task가 파싱하기 쉽게

자주 나는 오류

증상 원인 수정
Tool이 호출되지 않음 Task에 Tool 사용 조건이 없음 Task 지시에 "먼저 Tool 사용" 명시
파라미터가 이상함 args_schema가 불명확 Field(description=...) 보강
반환값 활용 어려움 자유 텍스트가 산만함 고정 섹션 또는 JSON 문자열 반환

다음 단계

Tool을 붙였다면 다음 핵심은 "출력 일관성"입니다.
다음 글에서 Pydantic으로 구조화합니다.
👉 구조화 출력 Pydantic