LLM Tools: 에이전트용 Python 도구 설치·등록·실행 관리

이 요약은 AI가 원문을 분석해 생성했습니다. 정확한 내용은 원문 기준으로 확인하세요.

TL;DR

이 프로젝트는 에이전트가 호출 가능한 도구들을 일반 pip 패키지로 배포하고 LLM-tools.txt라는 레지스트리 파일에 정확한 버전을 고정해 설치와 호출을 일관되게 만드는 도구 관리자이다. 설치는 가상환경에서 pip로 llm-tools를 설치한 뒤 llm-tools install로 패키지를 추가하고 llm-tools describe로 입력·출력 스키마를 조회한 다음 llm-tools execute로 JSON 또는 XML 페이로드를 전달해 실행 결과와 진단 정보를 받는 방식으로 동작한다. 도구는 작은 CLI 패키지와 FastAPI 같은 서버측 구현으로 분리되며 describe와 execute 계약을 통해 도구 탐색과 자동 설치가 재현 가능하게 유지된다. 실행 실패는 표준화된 필드(ok, stdout, stderr, exit_code, error_type 등)로 반환되어 에이전트의 오류 처리와 결정 근거로 활용될 수 있다.

실용적 조언

가상환경을 생성하고 프로젝트 폴더에서 llm-tools를 설치한 뒤 LLM-tools.txt를 사용해 도구 의존성을 관리하면 도구 충돌과 버전 불일치 문제를 줄일 수 있다. 작성된 도구 패키지는 describe와 execute 계약을 준수해야 하며 이를 통해 에이전트가 자동으로 스키마를 조회하고 JSON 또는 XML 페이로드로 실행할 수 있다. 도구의 API URL과 자격증명은 환경변수로 관리하고 레지스트리에는 포함하지 않음으로써 보안 사고를 예방할 수 있다.

섹션별 상세

여러 에이전트 프로젝트에서 도구가 복제되거나 서로 다른 버전과 스키마가 흩어지는 문제로 인해 재현성과 유지보수가 어려움이 발생한다. 이 프로젝트는 LLM-tools.txt라는 레지스트리 파일에 각 도구의 패키지 이름과 정확한 버전을 기록하여 어떤 도구가 설치되어야 하는지 명확히 한다. 설치는 pip로 처리되고 레지스트리에 설치된 정확한 버전이 자동으로 기록되어 수동으로 경로를 찾거나 Git 체크아웃을 복사할 필요가 사라진다. 결과적으로 동일한 에이전트 구성을 다른 환경에서 반복적으로 재현할 수 있다.

클라이언트 측 도구 설치와 호출 방식은 에이전트가 도구를 직접 복제하는 대신 로컬에 작은 클라이언트 패키지를 설치하고 실제 작업 로직은 FastAPI나 외부 API에 남기는 아키텍처를 따른다. llm-tools CLI와 LLMTool 클래스는 패키지를 pip로 설치하고 설치된 명령의 존재를 확인한 다음 describe 명령으로 입력·출력 스키마를 조회하고 execute로 JSON 또는 XML 페이로드를 전달해 실행 결과를 받는다. 예시로 llm-tools describe example-tool --format json과 llm-tools execute example-tool --payload '{"text":"hello LLM"}' 명령이 제시되어 있으며 실행 결과에는 출력과 표준출력·표준오류·종료코드가 포함된다. 이 흐름은 에이전트가 도구의 인자와 반환값을 표준화된 방식으로 학습하고 호출하도록 만든다.

bash

python -m venv .venv
source .venv/bin/activate
python -m pip install "git+https://github.com/John-Codes/LLM-Tools.git"
llm-tools --help

프로젝트 내에서 가상환경을 만들고 GitHub에서 llm-tools를 설치한 뒤 도움말로 설치 완료를 확인하는 셸 명령 흐름이다.

python

from llm_tools import LLMTool

# Creates LLM-tools.txt automatically if it does not exist.
tools = LLMTool("LLM-tools.txt")

# Install from PyPI and pin the installed version in LLM-tools.txt.
# tools.install("weather-tool")

# See which tools the agent can use.
for tool in tools.get_tools():
    print(tool.package, tool.version)

# Ask the package how the LLM should call it.
schema = tools.describe("example-tool", format="json")
print(schema["description"])
print(schema["input_schema"])

# Call the tool using ordinary Python data.
result = tools.execute(
    "example-tool", payload={"text": "hello from Python"}, format="json",
)
if result.ok:
    print(result.output) # {'result': 'HELLO FROM PYTHON'}
else:
    print(result.to_dict())

LLMTool 클래스를 통해 LLM-tools.txt를 생성하고 도구 목록 열람, 설명(schema) 조회, JSON 포맷으로 도구 실행까지 하는 클라이언트 측 예시 코드이다.

도구 패키지 자체는 표준 pip 패키지 형식을 따르며 pyproject.toml에서 콘솔스크립트로 명령을 등록하고 CLI는 describe와 execute 명령을 표준화된 계약으로 제공해야 한다. 예제의 weather-tool CLI는 환경변수로 API URL을 받아 /description와 /execute 엔드포인트에 HTTP 요청을 보내며 실패 시 stderr와 비영리 종료코드로 실패 원인을 전달한다. README에는 describe가 이름, 버전, 목적, 입력·출력 스키마를 stdout으로 출력해야 하고 execute는 stdin에서 페이로드를 읽어 결과를 반환해야 한다고 명시되어 있다. 이 계약은 도구 탐색과 자동화된 설치·실행을 가능하게 하여 서로 다른 에이전트 프레임워크 간 이식성을 높인다.

python

import argparse
import os
import sys
from urllib.error import HTTPError, URLError
from urllib.request import Request, urlopen

API_URL = os.getenv("WEATHER_TOOL_URL", "http://127.0.0.1:8000")

def call_api(request: str | Request) -> None:
    try:
        with urlopen(request, timeout=30) as response:
            print(response.read().decode())
    except HTTPError as error:
        print(error.read().decode(), file=sys.stderr)
        raise SystemExit(1) from error
    except URLError as error:
        print(f"API connection failed: {error.reason}", file=sys.stderr)
        raise SystemExit(1) from error

def main() -> None:
    parser = argparse.ArgumentParser(prog="weather-tool")
    commands = parser.add_subparsers(dest="action", required=True)
    for name in ("describe", "execute"):
        command = commands.add_parser(name)
        command.add_argument("--format", choices=["json", "xml"], default="json")
    args = parser.parse_args()
    if args.action == "describe":
        call_api(f"{API_URL}/description?format={args.format}")
        return
    payload = sys.stdin.buffer.read()
    request = Request(
        f"{API_URL}/execute?format={args.format}", data=payload, headers={"Content-Type": f"application/{args.format}"}, method="POST",
    )
    call_api(request)

if __name__ == "__main__":
    main()

예제 weather-tool의 CLI 구현으로 describe와 execute 동작을 FastAPI 서버의 /description와 /execute 엔드포인트로 전달하는 주요 로직을 포함한다.

실행 실패와 진단 정보는 숨겨지지 않고 구조화된 형태로 반환되어 에이전트가 판단 근거로 활용할 수 있다. execute 호출의 예시 결과는 ok, output, stdout, stderr, exit_code, error_type, error_message, timed_out 필드를 포함하며 타임아웃과 에러 타입을 명확히 전달한다. 설치·제거 과정에서 예외가 발생하면 ToolCommandError 같은 예외 타입이 발생하고 에러 결과의 to_dict() 형태로 자세한 진단을 얻을 수 있다. 이 투명성은 에이전트가 실패 상황에서 재시도·대체 도구 선택·오류 보고 등의 결정을 할 때 필요한 정보를 제공한다.

용어 해설

LLM-tools.txt 레지스트리(LLM-tools.txt): — LLM-tools.txt는 Python 프로젝트의 requirements.txt와 유사하게 에이전트가 호출할 수 있는 도구 패키지 이름과 정확한 버전을 기록하는 파일이다. 이 파일은 pip로 설치된 도구의 정확한 버전을 고정하고 다른 개발자가 동일한 도구 세트를 재현할 수 있게 한다. 에이전트가 어떤 도구를 사용할 수 있는지와 그 버전을 명시적으로 전달하는 목적이 있다.
FastAPI: — FastAPI는 경량 Python 웹 프레임워크로서 도구의 서버측 구현이 HTTP 엔드포인트로 동작하도록 만들기 적합하다. 이 리포지토리의 예제 도구는 FastAPI로 /description와 /execute 엔드포인트를 노출하여 CLI가 해당 엔드포인트와 통신하게 한다. 도구 로직을 서버에 두고 클라이언트는 간단한 패키지로 남기는 아키텍처를 가능하게 한다.
pip: — pip은 Python 패키지를 설치하고 버전을 고정하는 표준 도구로서 이 프로젝트에서는 에이전트 도구를 일반 Python 패키지로 배포하고 설치하는 수단으로 사용된다. llm-tools는 pip 호출을 안전하게 수행하고 설치된 명령의 존재와 버전을 검사하여 LLM-tools.txt에 기록한다. pip 기반 배포는 도구 재현성과 버전 관리를 단순화한다.

언급된 도구

llm-tools추천링크

에이전트에서 LLM 도구를 설치·등록·설명·실행하는 CLI와 LLMTool Python 클래스

언급된 리소스

GitHubLLM-Tools GitHub 저장소