AI 에이전트에 Tools를 직접 달아야 할 때: 설계부터 구현까지 (ruxu.dev)

한줄 요약

AI 에이전트가 실제 작업을 수행하려면 LLM에 Tools를 연결해야 하며, 설계 방식이 신뢰성과 안전성을 결정한다.

어떤 상황에서 Tools가 필요한가?

AI 에이전트의 기본 루프는 단순하다. 사용자 입력을 받고, 모델이 응답하고, 대화 컨텍스트를 유지하는 것. 하지만 이 상태로는 모델이 이미 알고 있는 것만 답할 수 있다. 외부 파일을 읽거나, 코드를 실행하거나, 웹에서 정보를 가져오는 일은 할 수 없다.

이 한계를 넘으려면 Tools가 필요하다. Tool은 LLM이 자율적으로 호출할 수 있도록 노출된 함수 또는 프로그램이다. 단순한 Python 함수일 수도 있고, HTTP 요청을 날리는 외부 서버일 수도 있다.

실무에서 이 필요성이 두드러지는 상황은 분명하다. 코드베이스를 분석하는 코딩 에이전트, 파일 시스템을 탐색해 리포트를 생성하는 자동화 에이전트, 웹에서 최신 정보를 수집해 요약하는 리서치 에이전트 모두 Tools 없이는 동작하지 않는다. 앱 개발 외주나 내부 자동화 도구를 만들 때 에이전트를 도입하려는 팀이라면 Tools 설계를 초반부터 고려해야 한다.

Tools는 어떻게 구현하는가?

초기 구현 방식은 모델 출력 텍스트를 파싱해서 함수를 호출하는 방식이었다. 예를 들어 Action: web_fetch 같은 패턴을 감지해 실행하는 식이다. 하지만 모델이 정해진 포맷을 정확히 따르지 않는 경우가 많아 신뢰성이 낮았다.

현대 LLM은 네이티브 Tool Calling을 지원한다. 모델이 JSON 구조의 Tool 요청을 직접 생성하고, 내장 유효성 검사를 통해 환각을 줄인다. 에이전트 루프 안에서 모델 응답에 tool_calls가 있으면 해당 함수를 실행하고, 결과를 role: tool 메시지로 다시 컨텍스트에 추가하는 방식이다.

기본적으로 갖춰야 할 Tools 목록은 다음과 같다.

• bash 실행: 가장 강력한 도구. 에이전트가 컴퓨터에서 사실상 무엇이든 할 수 있게 된다.
• 파일 읽기: 줄 번호와 함께 파일 내용을 반환. offset과 limit으로 범위를 제한한다.
• glob 탐색: 디렉토리에서 패턴에 맞는 파일 목록을 찾는다.
• grep 검색: 정규식으로 파일 내용을 검색하고 파일 경로와 줄 번호를 함께 반환한다.
• 파일 쓰기: 파일 생성 및 전체 내용 기록. 상위 디렉토리가 없으면 자동 생성한다.
• 파일 편집: 파일 전체를 덮어쓰지 않고 특정 문자열만 교체한다. 코딩 에이전트에서 안전한 패치 작업에 적합하다.
• 웹 fetch: HTTP/HTTPS URL의 내용을 가져와 HTML을 제거하고 텍스트만 반환. 2MB 제한으로 컨텍스트 오염을 방지한다.

각 Tool은 함수 구현 외에 스키마 정의가 필요하다. 모델에게 Tool의 이름, 설명, 파라미터 타입과 필수 여부를 JSON 형태로 알려줘야 한다. 설명이 모호하면 모델이 잘못된 Tool을 선택하거나 파라미터를 틀리게 넘긴다. 스키마 작성이 곧 프롬프트 엔지니어링이다.

실전에서 주의할 점

bash Tool은 가장 강력하고 가장 위험하다. 에이전트가 rm -rf 같은 명령을 실행할 수 있다는 뜻이기도 하다. 지금 단계에서는 로컬 개발 환경이나 샌드박스에서만 사용해야 하고, 프로덕션 환경에 연결하는 순간 반드시 권한 제한과 명령어 필터링이 필요하다.

edit_file은 write_file보다 안전하다. 파일 전체를 덮어쓰는 대신 특정 문자열만 교체하기 때문에, 에이전트가 읽지 않은 내용을 실수로 지우는 사고를 방지한다. 파일 수정이 필요한 상황에서는 기본적으로 edit_file을 쓰도록 프롬프트를 설계하는 게 낫다.

Tool 결과는 컨텍스트를 빠르게 소모한다. grep이나 read_file이 수백 줄을 반환하면 컨텍스트 윈도우가 금세 찬다. 출력 길이를 제한하는 로직(limit, 2MB 캡 등)은 선택이 아니라 필수다. 에이전트가 루프를 돌면서 Tool을 반복 호출할수록 이 문제는 누적된다.

Tool 이름과 설명의 일관성이 신뢰성을 결정한다. 비슷한 기능의 Tool이 여러 개 있을 때 모델이 잘못된 것을 선택하는 경우가 생긴다. 각 Tool의 역할 경계를 명확히 하고, 스키마 설명에서 "언제 이 Tool을 써야 하는가"를 구체적으로 기술하면 이런 혼선을 줄일 수 있다.