LLM(Large Language Model)은 텍스트를 생성하는 데 뛰어나지만, 오늘의 비트코인 가격을 알거나 이메일을 보내거나 데이터베이스를 조회할 수는 없습니다. Tools는 바로 이 격차를 메워주는 핵심 기능입니다.
Tools란 무엇인가?
Tools는 호출 가능한 기능(callable capabilities)으로, 에이전트가 외부 세계와 상호작용할 수 있게 해줍니다. API, 데이터베이스, 블록체인, 파일 시스템, 그리고 기타 모든 외부 서비스와 소통할 수 있게 만들어주죠. Tools 없이는 LLM이 단순히 텍스트만 생성할 수 있지만, Tools가 있으면 실제로 행동을 취할 수 있습니다.
왜 Tools가 필요한가?
다음과 같은 상황을 상상해보세요:
에이전트가 사용자에게 비트코인 가격을 알려주려면, 실제로 거래소 API를 호출해야 합니다. Tools가 없다면 이는 불가능하죠. Tools는 LLM과 현실 세계를 연결하는 다리 역할을 합니다.
SpoonOS Tools의 특징
SpoonOS의 Tools 시스템은 다음과 같은 강력한 특징들을 제공합니다:
- 타입 안전성(Typed) — JSON-schema 파라미터를 통해 LLM이 잘못된 입력을 생성하는 것을 방지합니다
- 검증(Validated) — 실행 전 런타임 검사를 통해 데이터 무결성을 보장합니다
- 비동기(Async) — 논블로킹 I/O로 고성능 에이전트 루프를 구현합니다
- 조합 가능(Composable) — Tools를 툴킷으로 묶고, MCP 프로토콜을 통해 공유할 수 있습니다
Tool의 구조
모든 SpoonOS Tool은 세 가지 핵심 요소로 구성됩니다:
| 구성 요소 | 목적 | 예시 |
|---|---|---|
| name | LLM이 Tool을 호출할 때 사용하는 고유 식별자 | "get_crypto_price" |
| description | Tool이 무엇을 하는지 자연어로 설명 | "Get real-time price for a cryptocurrency" |
| parameters | 예상되는 입력을 정의하는 JSON-schema | {"symbol": {"type": "string"}} |
LLM은 description을 읽어서 언제 Tool을 사용할지 결정하고, parameters를 통해 어떻게 호출할지 알게 됩니다.
무엇을 만들 수 있을까?
Tools를 활용하면 다양한 종류의 기능을 구현할 수 있습니다:
| Tool 유형 | 예시 |
|---|---|
| 데이터 조회 | 웹 검색, 데이터베이스 쿼리, API 호출 |
| 암호화폐/Web3 | 중앙화 거래소(CEX) 거래, 탈중앙화 거래소(DEX) 스왑, 온체인 읽기, 지갑 작업 |
| 파일 작업 | 파일 읽기/쓰기, 문서 파싱, 보고서 생성 |
| 커뮤니케이션 | 이메일 전송, Slack 포스팅, 티켓 생성 |
| 계산 | 코드 실행, SQL 실행, 계산 수행 |
SpoonOS vs 다른 Tool 시스템
다른 Tool 시스템과 비교했을 때 SpoonOS의 장점은 무엇일까요?
| 기능 | SpoonOS | LangChain | OpenAI Functions |
|---|---|---|---|
| 정의 | BaseTool 클래스 | @tool 데코레이터 | API 호출의 JSON |
| 검증 | JSON-schema + 런타임 | 선택적 Pydantic | 서버 측만 |
| 원격 Tools | MCP 프로토콜 (stdio/SSE/WS) | API 래퍼 | N/A |
| 발견 | ToolManager + 시맨틱 검색 | load_tools() | 수동 |
| 암호화폐 네이티브 | 내장 CEX/DEX/온체인 | 서드파티 | N/A |
빠른 시작
이제 실제로 Tools를 사용해보겠습니다. 먼저 필요한 패키지를 설치합니다:
pip install spoon-ai-sdk간단한 예제부터 시작해볼까요?
import asyncio
from spoon_ai.tools.base import BaseTool
from spoon_ai.tools import ToolManager
# JSON-schema 파라미터를 가진 Tool 정의
class GreetTool(BaseTool):
name: str = "greet"
description: str = "Greet someone by name"
parameters: dict = {
"type": "object",
"properties": {"name": {"type": "string"}},
"required": ["name"]
}
async def execute(self, name: str) -> str:
return f"Hello, {name}!"
# 등록 및 실행
manager = ToolManager([GreetTool()])
async def main():
result = await manager.execute(name="greet", tool_input={"name": "World"})
print(result) # Hello, World!
asyncio.run(main())이 간단한 예제에서 GreetTool은 이름을 받아서 인사말을 반환합니다. ToolManager를 통해 Tool을 등록하고 실행할 수 있습니다.
Tool 유형 상세 설명
로컬 Tools (BaseTool)
모든 Tool은 BaseTool을 상속받으며, 세 가지 필수 속성과 하나의 메서드를 가집니다:
from spoon_ai.tools.base import BaseTool
class MyTool(BaseTool):
name: str = "my_tool" # 고유 식별자
description: str = "What this tool does" # LLM이 언제 사용할지 결정하기 위해 읽는 설명
parameters: dict = { # 입력 검증을 위한 JSON-schema
"type": "object",
"properties": {
"arg1": {"type": "string", "description": "First argument"},
"arg2": {"type": "integer", "default": 10}
},
"required": ["arg1"]
}
async def execute(self, arg1: str, arg2: int = 10) -> str:
return f"Result: {arg1}, {arg2}"__call__ 메서드가 execute()로 전달되므로, await tool(arg1="value")와 같이 직접 호출할 수도 있습니다.
ToolManager
ToolManager는 Tool 등록, 조회, 실행을 조율합니다:
from spoon_ai.tools import ToolManager
manager = ToolManager([MyTool(), AnotherTool()])
# 이름으로 실행
result = await manager.execute(name="my_tool", tool_input={"arg1": "hello"})
# LLM 함수 호출을 위한 Tool 스펙 가져오기
specs = manager.to_params() # OpenAI 호환 Tool 정의 목록주요 메서드:
add_tool(tool)/add_tools([...])— Tool 등록remove_tool(name)— 이름으로 등록 해제get_tool(name)— Tool 인스턴스 조회to_params()— OpenAI 호환 Tool 정의 내보내기index_tools()/query_tools(query)— 시맨틱 검색 (Pinecone + OpenAI 필요)
암호화폐 툴킷 (선택 사항)
spoon-toolkits를 설치하면 필요한 구체적인 Tools를 가져올 수 있습니다:
from spoon_toolkits import CryptoPowerDataPriceTool, CryptoPowerDataCEXTool
from spoon_ai.tools import ToolManager
crypto_tools = [
CryptoPowerDataPriceTool(),
CryptoPowerDataCEXTool(),
]
manager = ToolManager(crypto_tools)이러한 Tools의 환경 변수는 특정 제공업체에 따라 다릅니다 (예: OKX_API_KEY, BITQUERY_API_KEY, RPC_URL 등).
MCP 클라이언트 Tools (MCPTool)
MCPTool을 사용하면 에이전트가 MCP 서버에서 호스팅되는 Tools를 호출할 수 있습니다:
from spoon_ai.tools.mcp_tool import MCPTool
mcp_tool = MCPTool(
mcp_config={
"url": "http://localhost:8765", # 또는 ws://..., 또는 stdio용 command/args
"transport": "sse", # 선택 사항: "sse" (기본값) | "http"
"timeout": 30,
"max_retries": 3,
}
)
# Tool의 스키마/설명은 MCP 서버에서 동적으로 가져옵니다.MCPTool.execute(...)는 서버의 Tool 목록을 가져오고, 이름/파라미터를 정렬하며, 재시도 및 헬스 체크를 수행합니다.
MCP 클라이언트 사용 예제
SpoonOS 에이전트는 주로 MCPTool (MCP 클라이언트)을 사용하여 원격 MCP 서버와 통신합니다:
from spoon_ai.tools.mcp_tool import MCPTool
# 예제: DeepWiki SSE MCP 서버에 연결
deepwiki = MCPTool(
name="read_wiki_structure", # 서버의 실제 Tool 이름 사용
description="DeepWiki MCP tool for repository analysis",
mcp_config={
"url": "https://mcp.deepwiki.com/sse",
"transport": "sse",
"timeout": 30,
},
)
async def main():
# 올바른 스키마를 얻기 위해 파라미터를 미리 로드
print("Loading MCP tool parameters...")
await deepwiki.ensure_parameters_loaded()
# 올바른 파라미터 이름 사용: repoName (repo 아님)
result = await deepwiki.execute(repoName="XSpoonAi/spoon-core")
print(f"\nResult:\n{result}")
asyncio.run(main())MCP 서버를 자체 호스팅해야 하는 경우, 해당 서버의 자체 문서를 따르세요. 이 가이드는 FastMCP 서버 설정보다는 spoon_ai MCP 클라이언트(MCPTool)에 중점을 둡니다.
설정
- 핵심: 기본 Tools에는 설정이 필요 없습니다.
- 임베딩 인덱스 (선택 사항):
OPENAI_API_KEY,PINECONE_API_KEY. - 암호화폐/툴킷 Tools: 제공업체별 키 (예:
OKX_API_KEY,BITQUERY_API_KEY,RPC_URL,GOPLUSLABS_API_KEY). - MCP:
mcp_config를 통해 전송 대상을 설정 (url또는command+args/env).
모범 사례
Tools를 효과적으로 사용하기 위한 몇 가지 모범 사례를 소개합니다:
- 단일 목적 유지: 명확한
parametersJSON 스키마를 가진 단일 목적 Tool을 만드세요. - 입력 검증:
execute내부에서 입력을 검증하고, 더 나은 에이전트 피드백을 위해 풍부한 오류를 발생시키세요. - 비동기 I/O 선호: 이벤트 루프를 차단하지 않도록
execute에서 비동기 I/O를 사용하세요. - ToolManager 재사용: 이름 기반 디스패치 및 Tool 메타데이터 생성을 위해
ToolManager를 재사용하세요. - 우아한 실패 처리: 툴킷 또는 MCP Tools를 사용할 때, 선택적 종속성이나 서버가 없는 경우 우아하게 실패하도록 처리하세요.
마무리
SpoonOS Tools는 LLM 에이전트가 외부 세계와 상호작용할 수 있게 해주는 강력한 시스템입니다. 타입 안전성, 검증, 비동기 처리, 그리고 조합 가능성까지 제공하여 현대적인 AI 에이전트를 구축하는 데 필요한 모든 기능을 갖추고 있습니다.
이제 여러분도 Tools를 활용하여 더 강력하고 실용적인 AI 에이전트를 만들어보세요!
참고 자료
