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원칙
- 한 가지 일만 하기: 검색 Tool이 파일 저장까지 하지 않기
- 설명 명확히 쓰기:
description에 용도/입력을 분명히 - 입력 검증하기: Pydantic 스키마 사용
- 반환 형식 고정하기: 후속 Task가 파싱하기 쉽게
자주 나는 오류
| 증상 | 원인 | 수정 |
|---|---|---|
| Tool이 호출되지 않음 | Task에 Tool 사용 조건이 없음 | Task 지시에 "먼저 Tool 사용" 명시 |
| 파라미터가 이상함 | args_schema가 불명확 | Field(description=...) 보강 |
| 반환값 활용 어려움 | 자유 텍스트가 산만함 | 고정 섹션 또는 JSON 문자열 반환 |
다음 단계
Tool을 붙였다면 다음 핵심은 "출력 일관성"입니다.
다음 글에서 Pydantic으로 구조화합니다.
👉 구조화 출력 Pydantic