도구 정의 및 구성
RubyLLM에서 도구를 정의하려면 RubyLLM::Tool 클래스를 상속받아 새로운 클래스를 생성합니다. 각 도구는 description 메서드를 통해 AI 모델이 이해할 수 있도록 명확한 목적을 설명해야 합니다. 입력 매개변수는 param 메서드를 사용하여 정의하며, 이름, 데이터 타입, 설명, 필수 여부 등을 지정할 수 있습니다. 실제 로직은 execute 인스턴스 메서드에 구현되며, 이 메서드는 param으로 정의된 매개변수들을 키워드 인자로 받습니다. 도구의 클래스 이름은 자동으로 스네이크 케이스로 변환되어 API 호출에 사용됩니다.
도구 활용 및 실행 흐름
도구는 RubyLLM::Chat 인스턴스에 with_tool 또는 with_tools 메서드를 사용하여 연결됩니다. RubyLLM v1.6.2 이상 버전부터는 모든 모델에서 도구 사용을 시도하며, 모델이 함수 호출을 지원하지 않는 경우 적절한 오류를 반환합니다. 도구의 실행 흐름은 사용자의 질의가 모델로 전송되면, 모델이 질의와 사용 가능한 도구를 분석하여 필요한 도구를 결정하고 도구 호출 요청을 생성하는 방식으로 진행됩니다. RubyLLM은 이 요청을 받아 등록된 도구의 execute 메서드를 실행하고, 그 결과를 다시 AI 모델에 전달하여 최종 자연어 응답을 생성하게 합니다. 이 모든 과정은 chat.ask 호출 내에서 자동으로 처리됩니다.
고급 기능 및 고려사항
개발자는 on_tool_call 및 on_tool_result 콜백을 사용하여 도구 호출 및 결과 반환을 모니터링할 수 있으며, 이는 로깅, UI 업데이트, 디버깅 및 감사에 유용합니다. 과도한 API 사용이나 무한 루프를 방지하기 위해 콜백을 통해 도구 호출 횟수를 제한할 수도 있습니다. halt 헬퍼는 도구 실행 후 LLM이 대화를 계속하는 것을 건너뛰고 도구 결과를 직접 반환해야 할 때 사용됩니다. 이는 토큰 절약, 서브 에이전트 위임, 정밀한 응답이 필요할 때 유용합니다. 디버깅을 위해서는 RUBYLLM_DEBUG=true 환경 변수를 설정하여 상세 로그를 확인할 수 있습니다.
오류 처리 및 보안
도구 내에서의 오류는 복구 가능한 경우 { error: "description" } 형태로 반환하고, 복구 불가능한 경우 예외를 발생시켜야 합니다. 가장 중요한 보안 고려사항은 execute 메서드로 전달되는 모든 인수를 잠재적으로 신뢰할 수 없는 사용자 입력으로 간주해야 한다는 점입니다. eval, system, send 또는 직접적인 SQL 삽입과 같은 메서드를 AI로부터 받은 원시 인수에 절대 사용해서는 안 됩니다. 항상 매개변수 유형, 범위, 형식 및 허용 값을 검증하고, 주입 공격을 방지하기 위해 문자열을 살균 처리하며, 최소 권한의 원칙을 준수해야 합니다.