도구(Tools)

도구(Tools)

Smolagents는 언제든 바뀔 수 있는 실험적 API예요. 에이전트가 돌려주는 결과는 API나 기반 모델이 바뀌면 달라질 수 있답니다.

에이전트와 도구에 대한 더 기본적인 내용은 소개 가이드를 먼저 읽어보세요. 이 페이지는 내부 클래스들에 대한 API 문서를 담고 있어요.

도구 베이스 클래스

load_tool[[smolagents.load_tool]]

  • repo_id (str) — 허브에 올라와 있는 도구의 Space 레포 ID예요.
  • model_repo_id (str, 선택) — 선택한 도구에 기본 모델 대신 다른 모델을 쓰고 싶을 때 지정해요.
  • token (str, 선택) — hf.co에서 당신을 식별하기 위한 토큰이에요. 설정하지 않으면 huggingface-cli login을 실행하며 생성된 토큰(~/.huggingface에 저장)을 써요.
  • trust_remote_code (bool, 선택, 기본 False) — 허브에서 도구를 불러오려면 이 값을 받아들여야 해요.
  • kwargs (추가 키워드 인자, 선택) — 허브 관련 인자(cache_dir, revision, subfolder 등)는 도구 파일을 내려받을 때 쓰고, 나머지는 도구의 init에 전달돼요.

허브에서 도구를 빠르게 불러오는 메인 함수예요. 도구를 '불러온다'는 건 도구를 내려받아 로컬에서 실행한다는 뜻이에요. 항상 도구를 실행 환경에 불러오기 전에 그 도구를 먼저 검사하세요 — pip/npm/apt로 패키지를 설치할 때처럼요.

tool[[smolagents.tool]]

  • tool_function (Callable) — Tool 서브클래스로 변환할 함수예요. 각 입력과 출력에 타입 힌트가 있어야 하고, 함수 설명과 각 인자를 설명하는 'Args:' 부분을 포함한 docstring도 있어야 해요.

함수를 동적으로 생성된 Tool 서브클래스의 인스턴스로 변환해요.

Tool[[smolagents.Tool]]

에이전트가 쓰는 함수들의 베이스 클래스예요. 이걸 상속해 forward 메서드와 다음 클래스 속성들을 구현하면 돼요.

  • description (str) — 도구가 무엇을 하는지, 어떤 입력을 받고 어떤 출력을 돌려주는지에 대한 짧은 설명이에요. 예: 'url에서 파일을 내려받는 도구예요. url을 입력으로 받아 파일에 담긴 텍스트를 돌려줘요.'
  • name (str) — 에이전트 프롬프트에서 도구를 가리키는 이름이에요. 예: "text-classifier"나 "image_generator".
  • inputs (Dict[str, Dict[str, Union[str, type, bool]]]) — 기대하는 입력의 종류(모달리티)를 담은 dict예요. type 키와 description 키를 가져요. launch_gradio_demo에서 쓰이거나 도구로 멋진 Space를 만들 때 쓰이며, 도구의 생성 설명에도 사용돼요.
  • output_type (type) — 도구 출력의 타입이에요. launch_gradio_demo나 멋진 Space 생성에 쓰이고, 생성 설명에도 사용돼요.
  • output_schema (Dict[str, Any], 선택) — 도구 출력의 기대 구조를 정의하는 JSON 스키마예요. 시스템 프롬프트에 포함해 에이전트가 기대 출력 형식을 이해하게 도울 수 있어요. 참고: 지금은 정보 제공용일 뿐 실제 출력 검증을 수행하지는 않아요.

도구를 사용하기 전에 무거운 작업(모델 로딩 같은)이 필요하다면 setup() 메서드를 오버라이드할 수도 있어요. setup()은 도구를 처음 사용할 때 호출되지, 인스턴스화할 때 호출되지는 않아요.

  • tool_dict (dict[str, Any]) — 도구의 dict 표현이에요.
  • **kwargs — 도구 생성자에 전달할 추가 키워드 인자예요.

dict 표현으로부터 Tool 객체를 만들어요.

Gradio 도구로부터 Tool을 만들어요.

  • repo_id (str) — 도구가 정의된 허브의 Space 레포 이름이에요.
  • token (str, 선택) — hf.co에서 당신을 식별하는 토큰이에요. 설정하지 않으면 huggingface-cli login으로 생성된 토큰을 써요.
  • trust_remote_code (bool, 선택, 기본 False) — 원격 코드 실행의 위험을 이해하고 이 도구를 신뢰한다는 표시예요. True로 설정하지 않으면 허브에서 도구를 불러오는 게 실패해요.
  • kwargs (추가 키워드 인자, 선택) — 허브 관련 인자는 파일 다운로드에 쓰이고 나머지는 도구 init에 전달돼요.

허브에 정의된 도구를 불러와요. 허브에서 도구를 불러오는 건 도구를 내려받아 로컬에서 실행한다는 뜻이에요. 항상 런타임에 불러오기 전에 도구를 검사하세요.

LangChain 도구로부터 Tool을 만들어요.

  • space_id (str) — 허브에 있는 Space의 ID예요.
  • name (str) — 도구의 이름이에요.
  • description (str) — 도구의 설명이에요.
  • api_name (str, 선택) — Space에 탭이 여러 개일 때 쓸 특정 api_name이에요. 지정하지 않으면 첫 번째 api가 기본값이 돼요.
  • token (str, 선택) — 비공개 Space에 접근하거나 GPU 할당량을 늘리려면 토큰을 추가해요.

허브에서 id로 Space를 찾아 Tool로 만들어요.

예시:

>>> image_generator = Tool.from_space(
...     space_id="black-forest-labs/FLUX.1-schnell",
...     name="image-generator",
...     description="Generate an image from a prompt"
... )
>>> image = image_generator("Generate an image of a cool surfer in Tahiti")

>>> face_swapper = Tool.from_space(
...     "tuan2308/face-swap",
...     "face_swapper",
...     "Tool that puts the face shown on the first image on the second image. You can give it paths to images.",
... )
>>> image = face_swapper('./aymeric.jpeg', './ruth.jpg')
  • repo_id (str) — 도구를 올릴 저장소의 이름이에요. 특정 조직에 올릴 때는 조직 이름을 포함해야 해요.
  • commit_message (str, 선택, 기본 "Upload tool") — 푸시할 때 커밋할 메시지예요.
  • private (bool, 선택) — 레포를 비공개로 만들지 여부예요. None(기본)이면 조직 기본값이 비공개가 아닌 한 공개가 돼요. 레포가 이미 존재하면 이 값은 무시돼요.
  • token (bool 또는 str, 선택) — 원격 파일용 HTTP bearer 인증 토큰이에요. 설정하지 않으면 huggingface-cli login으로 생성된 토큰을 써요.
  • create_pr (bool, 선택, 기본 False) — 업로드한 파일로 PR을 만들지, 바로 커밋할지 결정해요.

도구를 허브에 업로드해요.

  • output_dir (str 또는 Path) — 도구를 저장할 폴더예요.
  • tool_file_name (str, 선택) — 도구를 저장할 파일 이름이에요.
  • make_gradio_app (bool, 선택, 기본 True) — requirements.txt 파일과 Gradio UI도 함께 내보낼지 여부예요.

도구를 허브에 푸시할 수 있게 관련 코드 파일을 저장해요. 도구의 코드를 output_dir에 복사하고 자동으로 다음을 생성해요.

  • 도구 로직을 담은 {tool_file_name}.py 파일
  • make_gradio_app=True로 넘기면, tool.push_to_hub()로 Space에 내보낼 때 도구용 UI를 제공하는 app.py 파일도 작성돼요.
  • 도구가 사용하는 모듈 이름(코드 검사로 감지)을 담은 requirements.txt

도구를 사용하기 전에 수행해야 하는 무거운 작업(큰 모델 로딩 같은)이 있으면 이 메서드를 오버라이드해요.

도구를 나타내는 dict를 반환해요.

launch_gradio_demo[[smolagents.launch_gradio_demo]]

  • tool (Tool) — 데모를 실행할 도구예요.

도구용 Gradio 데모를 실행해요. 해당 도구 클래스는 클래스 속성 inputs와 output_type을 제대로 구현해야 해요.

ToolCollection[[smolagents.ToolCollection]]

도구 컬렉션은 에이전트의 도구 상자에 도구 모음을 불러오게 해 줘요. 컬렉션은 허브의 컬렉션이나 MCP 서버에서 불러올 수 있어요.

예시와 사용법은 ToolCollection.from_hub()와 ToolCollection.from_mcp()를 참고해요.

  • collection_slug (str) — 컬렉션을 가리키는 컬렉션 슬러그예요.
  • token (str, 선택) — 컬렉션이 비공개일 때의 인증 토큰이에요.
  • trust_remote_code (bool, 선택, 기본 False) — 원격 코드를 신뢰할지 여부예요.

허브에서 도구 컬렉션을 불러와요. 컬렉션에 있는 모든 Space의 도구 모음을 에이전트의 도구 상자에 추가해요.

[!NOTE] Space만 가져와지므로, 이 컬렉션에서 다른 것을 보여주고 싶다면 모델과 데이터셋을 컬렉션에 자유롭게 추가해도 괜찮아요.

예시:

>>> from smolagents import ToolCollection, CodeAgent

>>> image_tool_collection = ToolCollection.from_hub("huggingface-tools/diffusion-tools-6630bb19a942c2306a2cdb6f")
>>> agent = CodeAgent(tools=[*image_tool_collection.tools], add_base_tools=True)

>>> agent.run("Please draw me a picture of rivers and lakes.")

  • server_parameters (mcp.StdioServerParameters 또는 dict) — MCP 서버에 연결하기 위한 설정 파라미터예요.

    • mcp.StdioServerParameters 인스턴스: 서브프로세스로 표준 입출력을 통해 Stdio MCP 서버에 연결할 때 써요.
    • 최소한 다음을 담은 dict:
      • "url": 서버의 URL
      • "transport": 사용할 전송 프로토콜. 다음 중 하나:
        • "streamable-http": Streamable HTTP 전송(기본값).
        • "sse": 레거시 HTTP+SSE 전송(비권장).

  • trust_remote_code (bool, 선택, 기본 False) — MCP 서버에 정의된 도구의 코드 실행을 신뢰할지 여부예요. MCP 서버를 신뢰하고 로컬 머신에서 원격 코드 실행의 위험을 이해할 때만 True로 설정해야 해요. False로 설정하면 MCP에서 도구를 불러오는 게 실패해요.

  • structured_output (bool, 선택, 기본 False) — MCP 도구에 구조화 출력 기능을 켤지 여부예요. True면:

    • MCP 도구의 outputSchema 지원
    • 구조화 콘텐츠 처리(MCP 응답의 structuredContent)
    • 구조화 데이터용 JSON 파싱 폴백 False면 하위 호환성을 위해 기존의 단순 텍스트 전용 동작을 써요.

MCP 서버에서 도구 컬렉션을 자동으로 불러와요. Stdio, Streamable HTTP, 레거시 HTTP+SSE MCP 서버를 지원해요. 각 MCP 서버에 연결하는 방법은 server_parameters 인자를 참고하세요.

참고: MCP 서버를 처리하는 asyncio 이벤트 루프를 돌리기 위해 별도 스레드가 생성돼요.

Stdio MCP 서버 예시:

>>> import os
>>> from smolagents import ToolCollection, CodeAgent, InferenceClientModel
>>> from mcp import StdioServerParameters

>>> model = InferenceClientModel()

>>> server_parameters = StdioServerParameters(
>>>     command="uvx",
>>>     args=["--quiet", "[email protected]"],
>>>     env={"UV_PYTHON": "3.12", **os.environ},
>>> )

>>> with ToolCollection.from_mcp(server_parameters, trust_remote_code=True) as tool_collection:
>>>     agent = CodeAgent(tools=[*tool_collection.tools], add_base_tools=True, model=model)
>>>     agent.run("Please find a remedy for hangover.")

구조화 출력을 켠 예시:

>>> with ToolCollection.from_mcp(server_parameters, trust_remote_code=True, structured_output=True) as tool_collection:
>>>     agent = CodeAgent(tools=[*tool_collection.tools], add_base_tools=True, model=model)
>>>     agent.run("Please find a remedy for hangover.")

Streamable HTTP MCP 서버 예시:

>>> with ToolCollection.from_mcp({"url": "http://127.0.0.1:8000/mcp", "transport": "streamable-http"}, trust_remote_code=True) as tool_collection:
>>>     agent = CodeAgent(tools=[*tool_collection.tools], add_base_tools=True, model=model)
>>>     agent.run("Please find a remedy for hangover.")

MCP 클라이언트[[smolagents.MCPClient]]

  • server_parameters (StdioServerParameters | dict[str, Any] | list[StdioServerParameters | dict[str, Any]]) — MCP 서버에 연결하기 위한 설정 파라미터예요. 여러 MCP를 한 번에 연결하려면 리스트로 쓸 수 있어요.
    • mcp.StdioServerParameters 인스턴스: 서브프로세스로 표준 입출력을 통해 Stdio MCP 서버에 연결할 때.
    • 최소한 다음을 담은 dict:
      • "url": 서버의 URL
      • "transport": 사용할 전송 프로토콜(위와 동일).
  • adapter_kwargs (dict[str, Any], 선택) — MCPAdapt에 직접 전달할 추가 키워드 인자예요.
  • structured_output (bool, 선택, 기본 False) — MCP 도구에 구조화 출력 기능을 켤지 여부(위와 동일).

MCP 서버 연결을 관리하고 그 도구들을 SmolAgents에 제공해요. 참고: 도구는 init 중에 connect() 메서드로 연결을 시작한 후에만 접근할 수 있어요. 컨텍스트 매니저를 쓰지 않는다면 연결이 정리되도록 try ... finally를 쓰길 강력히 권장해요.

예시:

# 완전 관리형 컨텍스트 매니저 + stdio
with MCPClient(...) as tools:
    # 이제 도구 사용 가능

# 컨텍스트 매니저 + Streamable HTTP 전송:
with MCPClient({"url": "http://localhost:8000/mcp", "transport": "streamable-http"}) as tools:
    # 이제 도구 사용 가능

# 고급 MCP 도구에 구조화 출력 켜기:
with MCPClient(server_parameters, structured_output=True) as tools:
    # 구조화 출력을 지원하는 도구 사용 가능

# mcp_client 객체로 연결을 직접 관리:
try:
    mcp_client = MCPClient(...)
    tools = mcp_client.get_tools()

    # 여기서 도구 사용
finally:
    mcp_client.disconnect()

MCP 서버에 연결하고 도구를 초기화해요.

MCP 서버에서 연결을 끊어요.

MCP 서버에서 사용 가능한 SmolAgents 도구 목록이에요. - ValueError — MCP 서버 도구가 None일 때(보통 서버가 시작되지 않았다고 가정).

참고: 지금은 항상 세션 생성 시점에 사용 가능한 도구를 돌려주지만, 향후 릴리스에서는 호출 시점에 MCP 서버에서 새로 사용 가능해진 도구도 돌려줄 거예요.

에이전트 타입

에이전트는 도구 사이에서 어떤 타입의 객체도 다룰 수 있어요. 도구는 완전히 멀티모달이라 텍스트, 이미지, 오디오, 비디오 등을 받고 돌려줄 수 있죠. 도구 간 호환성을 높이고 이런 반환값을 ipython(jupyter, colab 등)에서 올바르게 렌더링하기 위해, 이런 타입들을 감싸는 래퍼 클래스를 제공해요.

래핑된 객체는 원래처럼 동작해야 해요. 텍스트 객체는 여전히 문자열처럼, 이미지 객체는 여전히 PIL.Image처럼 동작해야 하죠. 이 타입들은 세 가지 목적이 있어요.

  • 타입에 to_raw를 호출하면 내부 객체를 반환
  • to_string을 호출하면 객체를 문자열로 반환 (AgentText의 경우 그 문자열이지만, 다른 경우엔 객체의 직렬화 버전의 경로)
  • ipython 커널에서 표시하면 객체를 올바르게 표시

AgentText[[smolagents.AgentText]]

에이전트가 돌려주는 텍스트 타입이에요. 문자열처럼 동작해요.

AgentImage[[smolagents.AgentImage]]

에이전트가 돌려주는 이미지 타입이에요. PIL.Image.Image처럼 동작해요.

  • output_bytes (bytes) — 이미지를 저장할 출력 바이트예요.
  • format (str) — 출력 이미지에 쓸 형식이에요. PIL.Image.save와 같은 형식이에요.
  • **params — PIL.Image.save에 전달할 추가 파라미터예요.

이미지를 파일로 저장해요.

그 객체의 "raw" 버전을 반환해요. AgentImage의 경우 PIL.Image.Image예요.

그 객체의 문자열화 버전을 반환해요. AgentImage의 경우 직렬화된 이미지 버전의 경로예요.

AgentAudio[[smolagents.AgentAudio]]

에이전트가 돌려주는 오디오 타입이에요. 그 객체의 "raw" 버전을 반환해요. torch.Tensor 객체예요. 그 객체의 문자열화 버전을 반환해요. AgentAudio의 경우 직렬화된 오디오 버전의 경로예요.

출처: 공식문서