[SpoonOS] 에이전트(Agents)

네오 블록체인·2025년 12월 5일

SpoonOS

목록 보기

8/27

에이전트는 SpoonOS의 핵심 지능 계층입니다. 추론하고, 계획하고, 행동하는 자율 AI 시스템으로 복잡한 작업을 수행합니다. 에이전트는 LLM의 추론 능력을 도구, 메모리, 구조화된 실행 패턴과 결합하여 단순한 질문-답변을 넘어서는 기능을 제공합니다.

왜 에이전트가 필요한가?

일반적인 LLM은 질문에 답할 수 있지만, 다음은 할 수 없습니다:

행동 수행 — API 호출, 데이터베이스 쿼리, 트랜잭션 실행
컨텍스트 기억 — 대화와 세션 간 상태 유지
반복적 추론 — 복잡한 작업을 단계로 분해하고, 결과를 관찰하며, 적응
실패 처리 — 재시도, 대체 방안, 또는 문제 발생 시 도움 요청

SpoonOS 에이전트는 두 가지 실행 모델로 이러한 문제를 해결합니다:

모델	최적 용도	작동 방식
ReAct	간단한 작업, 단일 단계 도구 호출, Q&A	Think → Act → Observe 루프를 완료될 때까지 반복
Graph	복잡한 워크플로우, 병렬 작업, 조건부 로직	노드, 엣지, 라우팅을 가진 상태 그래프

무엇을 만들 수 있을까?

사용 사례	에이전트 타입	예시
도구가 있는 챗봇	ReAct	웹 검색이나 API 쿼리를 통해 질문에 답변
트레이딩 봇	Graph	시장 분석 → 행동 결정 → 거래 실행 → 모니터링
연구 어시스턴트	Graph	소스 수집 → 요약 → 종합 → 보고서 형식화
고객 지원	ReAct	지식 베이스 쿼리 및 에스컬레이션으로 티켓 처리
포트폴리오 추적기	Graph	가격 가져오기 → 지표 계산 → 알림 생성

SpoonOS vs 다른 프레임워크

기능	SpoonOS	LangChain	AutoGPT
실행	ReAct + Graph 워크플로우	ReAct 변형	자율 루프
도구	`BaseTool` + MCP 프로토콜	`Tool` 클래스	플러그인
메모리	내장 단기 메모리 + Mem0	외부 모듈	파일 기반
프로바이더	폴백이 있는 통합 다중 프로바이더	모델별 어댑터	단일 프로바이더
Web3/Crypto	네이티브 CEX, DEX, 온체인 툴킷	서드파티만	제한적

빠른 시작

pip install spoon-ai
export OPENAI_API_KEY="your-key"

import asyncio
from spoon_ai.agents import SpoonReactAI
from spoon_ai.chat import ChatBot

agent = SpoonReactAI(llm=ChatBot(model_name="gpt-4.1", llm_provider="openai"))

async def main():
    response = await agent.run("What is the capital of France?")
    print(response)

asyncio.run(main())

에이전트 타입

ReAct 에이전트

ReAct(Reasoning + Acting) 에이전트는 생각 → 행동 → 관찰 루프를 따릅니다. 에이전트는 무엇을 할지 생각하고, 도구를 실행하거나 응답을 생성하며, 결과를 관찰하고, 작업이 완료될 때까지 반복합니다.

import os
from spoon_ai.agents import SpoonReactAI
from spoon_ai.chat import ChatBot
from spoon_ai.tools import ToolManager
from spoon_ai.tools.base import BaseTool
from spoon_ai.tools.mcp_tool import MCPTool

class PercentageTool(BaseTool):
    name: str = "calculate_percentage"
    description: str = "Calculate a percentage of a numeric value"
    parameters: dict = {
        "type": "object",
        "properties": {
            "value": {"type": "number", "description": "Base value"},
            "percent": {"type": "number", "description": "Percentage to apply (e.g., 10 for 10%)"},
        },
        "required": ["value", "percent"],
    }

    async def execute(self, value: float, percent: float) -> str:
        return str(value * percent / 100)

# MCP 웹 검색 도구 (TAVILY_API_KEY 필요)
tavily_search = MCPTool(
    name="tavily-search",
    description="Search the web for current information",
    mcp_config={
        "command": "npx",
        "args": ["-y", "tavily-mcp"],
        "env": {"TAVILY_API_KEY": os.getenv("TAVILY_API_KEY")},
    },
)

# 실제 도구가 있는 에이전트
agent = SpoonReactAI(
    llm=ChatBot(model_name="gpt-4.1", llm_provider="openai"),
    tools=ToolManager([tavily_search, PercentageTool()]),
    max_iterations=10  # 추론 루프 제한
)

response = await agent.run("Search Bitcoin price and calculate 10% of it")

최적 용도: 단일 단계 작업, API 호출, Q&A, 간단한 자동화

Graph 에이전트

Graph 에이전트는 상태 그래프로 정의된 구조화된 워크플로우를 실행하며, 조건부 분기, 병렬 실행, 복잡한 다단계 파이프라인을 지원합니다.

from spoon_ai.agents import GraphAgent
from spoon_ai.graph import StateGraph

# 워크플로우 구축 (StateGraph 세부사항은 Graph System 문서 참조)
graph = StateGraph(MyState)
graph.add_node("analyze", analyze_fn)
graph.add_node("execute", execute_fn)
graph.add_edge("__start__", "analyze")
graph.add_conditional_edge("analyze", router_fn)

# 메모리 지속성이 있는 에이전트
agent = GraphAgent(
    graph=graph.compile(),
    memory_path="./agent_memory",
    session_id="user_123"
)

result = await agent.run("Analyze market and execute trades")

최적 용도: 다단계 워크플로우, 조건부 로직, 병렬 작업, 인간 개입 루프

에이전트 아키텍처

핵심 구성 요소

LLM 프로바이더 - 에이전트를 구동하는 언어 모델
도구 관리자 - 사용 가능한 도구 및 실행 관리
메모리 시스템 - 대화 기록 및 컨텍스트 저장
프롬프트 시스템 - 시스템 프롬프트 및 지시사항 처리

에이전트 생명주기

커스텀 에이전트 만들기

기본 에이전트 설정

from spoon_ai.agents.base import BaseAgent
from spoon_ai.tools import ToolManager

class CustomAgent(BaseAgent):
    def __init__(self, llm, tools=None):
        super().__init__(llm)
        self.tool_manager = ToolManager(tools or [])

    async def run(self, message: str) -> str:
        # 커스텀 에이전트 로직 작성
        return await self.process_message(message)

에이전트 구성

import os
from spoon_ai.agents.spoon_react_mcp import SpoonReactMCP
from spoon_ai.tools import ToolManager
from spoon_ai.tools.mcp_tool import MCPTool
from spoon_ai.chat import ChatBot
from spoon_toolkits.crypto.crypto_powerdata.tools import CryptoPowerDataCEXTool

# 추가 의존성 설치: pip install spoon-toolkits

class SpoonMacroAnalysisAgent(SpoonReactMCP):
    name: str = "SpoonMacroAnalysisAgent"
    system_prompt: str = (
        "You are a crypto market analyst. Use tavily-search for news and "
        "crypto_power_data_cex for market data, then deliver a concise macro view."
    )

    def __init__(self, **kwargs):
        super().__init__(**kwargs)
        self.available_tools = ToolManager([])

    async def initialize(self):
        tavily_key = os.getenv("TAVILY_API_KEY")
        if not tavily_key:
            raise ValueError("Set TAVILY_API_KEY before running the agent.")

        tavily_tool = MCPTool(
            name="tavily-search",
            description="Web search via Tavily",
            mcp_config={
                "command": "npx",
                "args": ["--yes", "tavily-mcp"],
                "env": {"TAVILY_API_KEY": tavily_key},
            },
        )

        crypto_tool = CryptoPowerDataCEXTool()
        self.available_tools = ToolManager([tavily_tool, crypto_tool])

agent = SpoonMacroAnalysisAgent(llm=ChatBot(llm_provider="openai"))

모범 사례

도구 선택

사용 사례에 맞는 도구 선택
도구 과부하 방지 - 너무 많은 도구는 에이전트를 혼란스럽게 만들 수 있음
도구 조합을 철저히 테스트

프롬프트 엔지니어링

명확하고 구체적인 지시사항 제공
원하는 동작의 예시 포함
적절한 제약 조건 및 가이드라인 설정

에러 처리

프레임워크의 자동 재시도 메커니즘 활용
내장 폴백 전략 사용
프레임워크의 구조화된 에러 처리에 의존

프레임워크 에러 처리

SpoonOS 에이전트는 내장된 에러 복원력의 이점을 제공합니다:

# 프레임워크가 자동으로 에러 처리
# 필요: pip install spoon-toolkits
from spoon_ai.tools import ToolManager
from spoon_toolkits.crypto.crypto_powerdata.tools import CryptoPowerDataCEXTool

agent = SpoonReactAI(
    llm=ChatBot(model_name="gpt-4.1", llm_provider="openai"),
    tools=ToolManager([CryptoPowerDataCEXTool()])  # 재시도/실패 처리가 있는 실제 도구
)

# 자동 처리 항목:
# - 폴백이 있는 LLM 프로바이더 실패
# - 재시도가 있는 도구 실행 에러
# - 우아한 성능 저하가 있는 네트워크 문제
response = await agent.run("Get Bitcoin price and analyze trends")

성능 고려사항

메모리 사용량

ReAct 에이전트: 낮은 메모리 사용량
Graph 에이전트: 복잡한 워크플로우를 위한 높은 메모리

실행 속도

간단한 작업: ReAct 에이전트가 더 빠름
복잡한 워크플로우: Graph 에이전트가 더 효율적

확장성

ReAct: 고빈도, 간단한 작업에 더 적합
Graph: 복잡하고 장기 실행 프로세스에 더 적합

다음 단계

📚 에이전트 구현 예제

🎯 Intent Graph Demo

GitHub: 소스 보기

데모 내용:

지능형 라우팅을 포함한 완전한 Graph 에이전트 구현
지속적인 메모리를 가진 장기 실행 에이전트 아키텍처
고급 상태 관리 및 컨텍스트 보존
프로덕션 준비된 에러 처리 및 복구

주요 기능:

사용자 의도 기반 동적 쿼리 라우팅 (general_qa → short_term_trend → macro_trend → deep_research)
여러 데이터 소스 간 진정한 병렬 실행
메모리 지속성 및 대화 컨텍스트
실시간 성능 모니터링 및 메트릭

학습에 최적:

Graph 에이전트 아키텍처 패턴
장기 실행 프로세스 관리
고급 메모리 및 상태 처리
프로덕션 배포 고려사항

🔍 MCP Spoon Search Agent

GitHub: 소스 보기

데모 내용:

동적 도구 발견을 가진 MCP 활성화 에이전트
암호화폐 분석과 통합된 웹 검색
다중 도구 오케스트레이션 및 데이터 종합
실제 에이전트 배포 패턴

주요 기능:

웹 검색을 위한 Tavily MCP 서버 통합
시장 분석을 위한 Crypto PowerData 도구
여러 데이터 소스를 결합한 통합 분석
동적 도구 로딩 및 검증

학습에 최적:

MCP 프로토콜 구현
다중 도구 에이전트 아키텍처
실시간 데이터 통합 패턴
분산 시스템의 에러 처리

📊 Graph Crypto Analysis

GitHub: 소스 보기

데모 내용:

전문 암호화폐 분석 에이전트
워크플로우 전반에 걸친 LLM 기반 의사결정
실시간 시장 데이터 처리 및 분석
투자 추천 생성

주요 기능:

실제 Binance API 통합 (시뮬레이션 데이터 없음)
기술 지표 계산 (RSI, MACD, EMA, 볼린저 밴드)
다중 시간대 분석 및 상관관계
위험 평가 및 시장 심리 분석

학습에 최적:

도메인 특화 에이전트 개발
금융 데이터 처리 패턴
LLM 기반 워크플로우 자동화
에이전트의 실제 API 통합

🛠️ 개발 가이드

Tools System - 사용 가능한 도구 및 통합에 대한 완전한 가이드
LLM Providers - 언어 모델 구성 및 최적화
Build Your First Agent - 단계별 에이전트 개발 튜토리얼

📖 고급 주제

Graph System - 고급 워크플로우 오케스트레이션
MCP Protocol - 동적 도구 발견 및 실행
API Reference - 완전한 에이전트 API 문서

네오 블록체인

스마트 이코노미를 위한 퍼블릭 블록체인, 네오에 대한 모든것

[SpoonOS] 에이전트(Agents)

SpoonOS

왜 에이전트가 필요한가?

무엇을 만들 수 있을까?

SpoonOS vs 다른 프레임워크

빠른 시작

에이전트 타입

ReAct 에이전트

Graph 에이전트

에이전트 아키텍처

핵심 구성 요소

에이전트 생명주기

커스텀 에이전트 만들기

기본 에이전트 설정

에이전트 구성

모범 사례

도구 선택

프롬프트 엔지니어링

에러 처리

프레임워크 에러 처리

성능 고려사항

메모리 사용량

실행 속도

확장성

다음 단계

📚 에이전트 구현 예제

🎯 Intent Graph Demo

🔍 MCP Spoon Search Agent

📊 Graph Crypto Analysis

🛠️ 개발 가이드

📖 고급 주제

SpoonOS 설치 가이드: Python AI 에이전트 프레임워크 시작하기

[SpoonOS] Graph System

0개의 댓글