빠른 시작

SpoonOS 프레임워크를 사용하면 5분 안에 AI 에이전트를 만들고 실행할 수 있습니다. 이 가이드를 따라가면 첫 번째 에이전트를 빠르게 구축할 수 있습니다.

사전 요구사항

시작하기 전에 몇 가지 준비가 필요합니다. 먼저 설치가 완료되어 있어야 하며, 최소 하나의 프로바이더 API 키(예: OPENAI_API_KEY)로 설정이 되어 있어야 합니다. 이 API 키는 에이전트가 LLM(Large Language Model)과 통신하는 데 사용됩니다.

첫 번째 에이전트 만들기

이제 실제로 동작하는 에이전트를 만들어보겠습니다. 처음에는 간단한 인사 기능을 가진 에이전트부터 시작하여 점진적으로 기능을 확장해 나가겠습니다.

1. 간단한 에이전트 생성

가장 먼저 할 일은 커스텀 도구를 정의하고 이를 사용하는 에이전트를 만드는 것입니다. 새로운 Python 파일 my_first_agent.py를 생성하고 다음 코드를 작성해보세요:

import asyncio
from spoon_ai.agents.toolcall import ToolCallAgent
from spoon_ai.chat import ChatBot
from spoon_ai.tools import ToolManager
from spoon_ai.tools.base import BaseTool

# 커스텀 도구 정의
class GreetingTool(BaseTool):
    name: str = "greeting"
    description: str = "Generate personalized greetings"
    parameters: dict = {
        "type": "object",
        "properties": {
            "name": {"type": "string", "description": "Person's name"}
        },
        "required": ["name"]
    }

    async def execute(self, name: str) -> str:
        return f"Hello {name}! Welcome to SpoonOS! 🚀"

# 에이전트 생성
class MyFirstAgent(ToolCallAgent):
    name: str = "my_first_agent"
    description: str = "A friendly assistant with greeting capabilities"

    system_prompt: str = """
    You are a helpful AI assistant built with SpoonOS framework.
    You can greet users and help with various tasks.
    """

    available_tools: ToolManager = ToolManager([GreetingTool()])

async def main():
    # LLM으로 에이전트 초기화
    agent = MyFirstAgent(
        llm=ChatBot(
            llm_provider="openai",         # 또는 "anthropic", "gemini", "deepseek", "openrouter"
            model_name="gpt-5.1"   # OpenAI용 프레임워크 기본값
        )
    )

    # 에이전트 실행 - 프레임워크가 모든 오류 케이스를 자동으로 처리
    response = await agent.run("Please greet me, my name is Alice")
    return response

if __name__ == "__main__":
    result = asyncio.run(main())
    # 에이전트 응답이 직접 반환됩니다

이 코드에서는 GreetingTool이라는 커스텀 도구를 정의하고, 이를 사용하는 MyFirstAgent 클래스를 만들었습니다. ToolCallAgent를 상속받아 에이전트의 기본 구조를 정의하고, available_tools에 우리가 만든 도구를 등록했습니다. LLM 프로바이더로는 OpenAI를 사용했지만, Anthropic, Gemini, DeepSeek, OpenRouter 등 다른 프로바이더도 선택할 수 있습니다.

2. 에이전트 실행

코드를 작성했다면 이제 실행해볼 차례입니다. 터미널에서 다음 명령어를 실행하세요:

python my_first_agent.py

에이전트가 실행되면 사용자의 이름을 받아 개인화된 인사말로 응답하고, 다양한 작업을 도와줄 준비가 되어 있습니다. 프레임워크가 내부적으로 모든 오류 케이스를 자동으로 처리하기 때문에, 복잡한 예외 처리 코드를 작성할 필요가 없습니다.

3. Web3 기능 추가

기본적인 에이전트가 동작하는 것을 확인했다면, 이제 블록체인과 암호화폐 관련 기능을 추가해보겠습니다. SpoonOS는 Web3 도구를 쉽게 통합할 수 있도록 설계되어 있어, 몇 줄의 코드만으로 암호화폐 가격 조회, DeFi 작업, 블록체인 분석 등의 기능을 추가할 수 있습니다.

다음과 같이 에이전트를 확장할 수 있습니다:

from spoon_ai.tools.crypto_tools import get_crypto_tools

class Web3Agent(ToolCallAgent):
    name: str = "web3_agent"
    description: str = "AI agent with Web3 and crypto capabilities"

    system_prompt: str = """
    You are a Web3-native AI assistant with access to blockchain data.
    You can help with crypto prices, DeFi operations, and blockchain analysis.
    """

    available_tools: ToolManager = ToolManager([
        GreetingTool(),
        # spoon-toolkits에서 모든 암호화폐/Web3 도구 로드 (requires `pip install -e spoon-toolkits`)
        *get_crypto_tools()
    ])

# 사용법
async def web3_demo():
    agent = Web3Agent(
        llm=ChatBot(
            llm_provider="anthropic",
            model_name="claude-sonnet-4-20250514"  # 프레임워크 기본값
        )
    )

    # 프레임워크가 암호화폐 데이터 가져오기와 오류 케이스를 자동으로 처리
    response = await agent.run("What's the current price of Bitcoin?")
    return response

get_crypto_tools() 함수를 사용하면 spoon-toolkits에서 제공하는 모든 암호화폐 및 Web3 관련 도구를 한 번에 로드할 수 있습니다. 이렇게 하면 에이전트가 실시간 암호화폐 가격을 조회하거나, 블록체인 데이터를 분석하는 등의 작업을 수행할 수 있게 됩니다. 프레임워크가 암호화폐 데이터를 가져오는 과정과 발생할 수 있는 오류들을 자동으로 처리해주기 때문에, 개발자는 비즈니스 로직에만 집중할 수 있습니다.

4. 프레임워크 기능 개요

지금까지 간단한 예제를 통해 SpoonOS의 기본 사용법을 살펴봤습니다. 이제 프레임워크가 제공하는 주요 기능들을 정리해보겠습니다.

SpoonOS 프레임워크는 다양한 LLM 프로바이더를 지원합니다. OpenAI (openai), Anthropic (anthropic), Google Gemini (gemini), DeepSeek (deepseek), OpenRouter (openrouter) 등 여러 프로바이더 중에서 선택할 수 있어, 프로젝트의 요구사항에 맞는 최적의 모델을 사용할 수 있습니다.

또한 프레임워크에는 암호화폐, DeFi, 소셜 미디어, 데이터 분석 등 다양한 분야의 내장 도구들이 포함되어 있습니다. 이러한 도구들을 조합하여 복잡한 작업을 수행하는 에이전트를 만들 수 있습니다.

에이전트 유형도 다양하게 제공됩니다. ReAct 패턴을 사용하는 에이전트, ToolCall 기반 에이전트, 그리고 여러 에이전트를 그래프 형태로 연결하여 복잡한 워크플로우를 구성할 수 있는 그래프 기반 에이전트 등이 있습니다.

마지막으로 MCP(Model Context Protocol) 통합을 통해 동적으로 도구를 발견하고 실행할 수 있습니다. 이를 통해 런타임에 새로운 도구를 추가하거나 기존 도구를 확장하는 것이 가능합니다.

프레임워크 단순성

SpoonOS의 가장 큰 장점 중 하나는 개발 복잡성을 크게 줄여준다는 점입니다. 일반적으로 AI 에이전트를 개발할 때는 오류 처리, 재시도 로직, API 호출 관리 등 많은 보일러플레이트 코드를 작성해야 합니다. 하지만 SpoonOS를 사용하면 이러한 부분들을 프레임워크가 자동으로 처리해줍니다.

예를 들어, 다음과 같이 간단하게 에이전트를 생성하고 실행할 수 있습니다:

# 간단한 에이전트 생성 - 오류 처리 불필요
agent = ToolCallAgent(
    llm=ChatBot(llm_provider="openai", model_name="gpt-4.1"),
    available_tools=ToolManager([CryptoTool(), Web3Tool()])
)


response = await agent.run("Analyze Bitcoin trends and suggest trades")

이 코드만으로도 에이전트가 비트코인 트렌드를 분석하고 거래 제안을 생성할 수 있습니다. 프레임워크가 내부적으로 API 호출, 오류 처리, 재시도 로직 등을 모두 관리하기 때문에, 개발자는 핵심 비즈니스 로직에만 집중할 수 있습니다.

프레임워크 개발 패턴

이제 기본적인 사용법을 넘어서, 더 복잡한 시나리오를 위한 개발 패턴들을 살펴보겠습니다. 이러한 패턴들을 활용하면 실제 프로덕션 환경에서 사용할 수 있는 강력한 에이전트 시스템을 구축할 수 있습니다.

에이전트 구성

복잡한 작업을 수행해야 할 때는 단일 에이전트보다 여러 에이전트를 조합하는 것이 효과적입니다. 예를 들어, 연구 에이전트가 데이터를 수집하고, 분석 에이전트가 이를 분석한 다음, 거래 에이전트가 최종 결정을 내리는 식으로 워크플로우를 구성할 수 있습니다.

SpoonOS의 GraphAgent를 사용하면 이러한 멀티 에이전트 시스템을 쉽게 구축할 수 있습니다:

# 복잡한 워크플로우를 위해 여러 에이전트 결합
from spoon_ai.agents.graph import GraphAgent

class MultiAgentSystem(GraphAgent):
    def __init__(self):
        super().__init__()
        self.add_agent("researcher", ResearchAgent())
        self.add_agent("analyst", AnalysisAgent())
        self.add_agent("trader", TradingAgent())

각 에이전트는 자신의 전문 분야에 집중할 수 있고, 그래프 구조를 통해 에이전트 간의 데이터 흐름과 작업 순서를 명확하게 정의할 수 있습니다. 이렇게 하면 시스템의 모듈성과 유지보수성이 크게 향상됩니다.

커스텀 도구 개발

프레임워크에서 제공하는 내장 도구만으로는 부족한 경우, 자신만의 도메인별 도구를 만들 수 있습니다. BaseTool을 상속받아 커스텀 도구를 정의하면, 에이전트가 이를 자동으로 인식하고 사용할 수 있게 됩니다.

예를 들어, 블록체인 분석 도구를 만들어보겠습니다:

# 도메인별 도구 생성
class BlockchainAnalysisTool(BaseTool):
    name: str = "blockchain_analysis"
    description: str = "Analyze blockchain transactions and patterns"

    async def execute(self, address: str, chain: str = "ethereum") -> str:
        # 커스텀 블록체인 분석 로직
        return f"Analysis results for {address} on {chain}"

이 도구는 특정 블록체인 주소와 체인을 받아서 분석 결과를 반환합니다. execute 메서드 내부에 실제 분석 로직을 구현하면, 에이전트가 이 도구를 사용하여 블록체인 데이터를 분석할 수 있게 됩니다. 이렇게 만든 도구는 다른 에이전트에서도 재사용할 수 있어, 코드 재사용성도 높아집니다.

MCP 통합

MCP(Model Context Protocol)는 동적으로 도구를 발견하고 실행할 수 있게 해주는 프로토콜입니다. SpoonOS는 MCP를 완전히 지원하여, 런타임에 새로운 도구를 추가하거나 외부 시스템과 통합하는 것을 쉽게 만들어줍니다.

MCP를 사용하면 다음과 같이 에이전트를 구성할 수 있습니다:

# 동적 도구를 위한 Model Context Protocol 사용
from spoon_ai.tools.mcp_tools_collection import MCPToolsCollection

agent = ToolCallAgent(
    llm=ChatBot(llm_provider="anthropic", model_name="claude-sonnet-4-20250514"),
    available_tools=ToolManager([
        MCPToolsCollection()  # MCP 도구를 자동으로 발견
    ])
)

MCPToolsCollection을 사용하면 연결된 MCP 서버에서 제공하는 모든 도구를 자동으로 발견하고 사용할 수 있습니다. 이를 통해 에이전트의 기능을 런타임에 확장하거나, 외부 시스템과의 통합을 간단하게 구현할 수 있습니다.

다음 단계

이제 SpoonOS 프레임워크의 기본 사항을 이해하셨을 것입니다. 간단한 에이전트부터 시작하여 Web3 기능을 추가하고, 멀티 에이전트 시스템을 구축하는 방법까지 살펴봤습니다.

더 깊이 있는 학습을 원하신다면 다음 자료들을 참고하시기 바랍니다:

• 핵심 개념 - 에이전트 아키텍처에 대한 심화 학습 자료입니다. 에이전트의 내부 동작 원리와 설계 패턴을 자세히 알아볼 수 있습니다.
• 내장 도구 - Web3 및 암호화폐 도구를 포함한 모든 내장 도구들을 탐색할 수 있습니다. 각 도구의 사용법과 활용 사례를 확인해보세요.
• 방법 가이드 - 고급 에이전트 패턴과 실제 프로덕션 환경에서의 활용 방법을 다룹니다. 복잡한 시나리오를 해결하기 위한 실전 가이드입니다.

이러한 자료들을 통해 SpoonOS 프레임워크를 더욱 효과적으로 활용할 수 있을 것입니다. 행운을 빕니다!