🤗 04. HF Agents Course 본편 3 - CodeAgent에 커스텀 툴 연결하기

이번 편 목표는 smolagents의 CodeAgent에 직접 만든 툴을 연결해서, “질문 → 도구 실행 → 최종 답변” 흐름을 재현하는 것입니다.

flowchart LR
    U[사용자 질문] --> A[CodeAgent]
    A --> T1[WebSearchTool]
    A --> T2[CustomCalcTool]
    T1 --> A
    T2 --> A
    A --> R[최종 응답 + 근거]

1) 준비

도구

• Python 3.10+
• 터미널
• Hugging Face 계정(선택: 모델 접근용)

입력

• 실습 폴더: hf-agents-ep04
• 질문 예시: "서울과 도쿄의 현재 시차를 계산해줘"

실행 명령

mkdir -p hf-agents-ep04 && cd hf-agents-ep04
python -m venv .venv
source .venv/bin/activate
pip install -U smolagents duckduckgo-search

성공 판정

• pip 에러 없이 설치 완료
• 가상환경 활성화 상태에서 python -c "import smolagents; print('ok')"가 ok 출력

2) 최소 실행 코드

main.py:

from smolagents import CodeAgent, DuckDuckGoSearchTool, tool
 
@tool
def time_diff_hours(city_a: str, city_b: str, utc_offset_a: int, utc_offset_b: int) -> str:
    """두 도시의 UTC 오프셋으로 시차(시간)를 계산한다."""
    diff = utc_offset_a - utc_offset_b
    return f"{city_a} - {city_b} 시차: {diff}시간"
 
agent = CodeAgent(
    tools=[DuckDuckGoSearchTool(), time_diff_hours],
    model=None,  # 로컬/기본 설정 기반. 환경에 맞게 교체 가능
)
 
question = "서울(+9)과 도쿄(+9)의 시차를 계산하고, 확인 근거를 한 줄로 덧붙여줘"
result = agent.run(question)
print(result)

실행 명령

python main.py

성공 판정

• 에이전트가 time_diff_hours를 호출해 시차 결과를 출력
• 필요 시 검색 툴을 사용한 근거 문장이 함께 출력

3) 초보자 포인트

• @tool 데코레이터를 붙이면 일반 함수를 에이전트 툴로 등록할 수 있습니다.
• 툴 설명(독스트링)은 짧고 명확할수록 호출 품질이 좋아집니다.
• 처음에는 입력/출력이 단순한 툴 1~2개로 시작하세요.

4) 실무 적용 포인트

• 사내 API 호출 함수를 @tool로 감싸면 “자연어 질의 인터페이스”를 빠르게 만들 수 있습니다.
• 툴 결과를 로그로 남기면(입력, 출력, 실행시간) 품질 검증과 장애 대응이 쉬워집니다.
• 운영 전에는 “실패 응답 포맷”을 고정해두면 자동화 파이프라인 연결이 안정적입니다.

5) 다음 편 예고

다음 편에서는 **툴 실패 재시도 + 가드레일(허용 도메인/명령 제한)**을 붙여 운영 안정성을 높이겠습니다.

참고 링크

1. https://github.com/huggingface/agents-course
2. https://huggingface.co/learn/agents-course
3. https://huggingface.co/docs/smolagents