CrewAI 커스텀 도구 만들기: 날씨 API를 붙여 AI 에이전트에 실시간 정보 넣는 법

핵심 메시지

• 도구란 AI 에이전트가 바깥 세계와 실제로 상호작용할 수 있게 해주는 기능이나 함수를 말한다.
• 언어 모델의 지식만으로 답할 수 없는 실시간 정보는 외부 API를 도구로 붙여야 채울 수 있다.
• 에이전트는 질문을 받으면 추가 정보가 필요한지 판단하고, 필요한 도구를 골라 호출한 뒤 그 결과를 답변에 반영한다.
• 도구 함수의 독스트링은 필수다. 모델이 그 함수가 무엇을 하는지 판단하는 근거가 되기 때문이다.
• 도구를 붙인 뒤에는 에이전트의 목표와 배경 설명, 그리고 과제의 기대 산출물까지 함께 고쳐야 실제로 도구가 쓰인다.

쉽게 이해하기

다중 에이전트 시스템을 만들다 보면 곧바로 벽에 부딪히는 지점이 있다. 언어 모델은 학습한 범위 안의 지식만 갖고 있어서, 지금 이 순간의 날씨나 경기 점수처럼 계속 바뀌는 정보에는 답할 수 없다. 이 영상은 그 빈틈을 메우는 방법으로 커스텀 도구를 소개한다. 도구는 검색, 데이터베이스 조회, 일정 생성과 수정, 계산, 그리고 임의의 사내 API까지 형태가 다양하다.

동작 순서는 단순하다. 사용자가 '오늘 파리 날씨가 어때'라고 물으면 에이전트가 먼저 추가 정보가 필요한지 판단하고, 등록된 도구 중 무엇을 써야 할지 고른다. 그다음 도구가 실행돼 결과가 돌아오고, 에이전트는 그 결과를 근거로 답을 만든다. 모델이 아는 것과 모르는 것을 나눠 처리하는 구조인 셈이다.

구현은 라이브러리를 추가하는 데서 시작한다. 의존성 목록에 CrewAI 도구 패키지를 넣고 설치한 뒤, 별도의 tools 폴더에 날씨용 파이썬 파일을 만든다. 그 안에서 도구 데코레이터로 함수를 감싸 이름을 붙이고, 도시 이름을 인자로 받는 함수를 정의한다. 발표자는 여기서 독스트링을 반드시 넣으라고 강조한다. 그 설명이 있어야 모델이 이 함수가 무엇을 하는 도구인지 이해하기 때문이다.

함수 본문에서는 API 키를 환경 변수에서 읽어오고, 기본 URL과 질의 파라미터를 조립해 요청을 보낸다. 응답에 10초 제한을 걸어두는 점도 눈여겨볼 만하다. 돌아온 JSON에서 위치 정보와 현재 상태에 해당하는 두 덩어리만 골라내 지역, 기온, 습도, 풍속 같은 필요한 값만 추려 돌려준다. 응답 전체를 그대로 넘기지 않고 필요한 값만 골라 반환하는 방식이다.

마지막 단계는 에이전트와 과제 쪽 수정이다. 관광지 조사 담당 에이전트의 목표에 '현재 날씨를 고려해 추천하라'는 문장을 더하고, 배경 설명에도 날씨 도구를 쓸 수 있다는 맥락을 넣는다. 그다음 에이전트에 도구 목록으로 함수를 등록하고, 과제 정의와 기대 산출물에도 날씨를 반영한 추천이 포함되도록 고친다. 실행해 보면 관리자 에이전트가 담당 에이전트에게 날씨 확인을 위임하고, 도구가 파리를 인자로 호출돼 기온과 습도, 풍속이 출력되며, 최종 일정에는 따뜻하고 맑은 날씨를 근거로 한 야외 활동 추천이 담긴다.

주요 인사이트

• 도구를 코드에 등록하는 것만으로는 부족하다. 에이전트의 목표와 배경 설명, 과제의 기대 산출물이라는 자연어 지시가 함께 바뀌어야 모델이 그 도구를 실제로 호출한다.
• 독스트링이 사실상 도구의 인터페이스 문서 역할을 한다. 사람이 읽는 주석이 아니라 모델이 판단에 쓰는 입력이라는 점이 일반적인 파이썬 코드와 다른 지점이다.
• 외부 API 호출에는 타임아웃을 걸어두는 습관이 필요하다. 에이전트가 여러 단계를 거쳐 움직이는 구조에서는 한 곳이 멈추면 전체 실행이 함께 지연된다.
• 계층형 구조에서는 관리자 에이전트가 작업을 나눠주고, 도구를 가진 담당 에이전트가 실제 호출을 수행한다. 도구를 어느 에이전트에 붙일지가 곧 역할 분담이 된다.
• API 키는 코드가 아니라 환경 변수 파일에서 읽어온다. 저장소에 키가 함께 올라가는 사고를 막는 기본 조치다.

자주 묻는 질문

관련 AI 소식