에이전트 Tool 설계 — docstring은 문서가 아니라 라우팅 신호다

from crewai_tools import SerperDevTool, WebsiteSearchTool, ScrapeWebsiteTool

search_tool  = SerperDevTool()      # Google 검색 (SERPER_API_KEY 필요)
web_rag_tool = WebsiteSearchTool()  # 특정 사이트 내부를 RAG로 검색
scrap_tool   = ScrapeWebsiteTool()  # 페이지 본문 스크래핑

researcher = Agent(
    role='테크 트렌드 연구원',
    goal="인공지능 분야의 최신 기술 트렌드를 한국어로 제공합니다. 지금은 2024년 8월입니다.",
    backstory='기술 트렌드에 예리한 안목을 지닌 전문 분석가이자 AI 개발자입니다.',
    tools=[search_tool, web_rag_tool],
    max_iter=5,          # 툴 호출 루프 상한 — 기본 25는 너무 관대하다
    llm=llm, verbose=True
)
write = Task(
    description="연구원의 요약을 바탕으로 테크 뉴스레터를 작성하세요.",
    expected_output='최신 기술 소식을 재밌는 말투로 소개하는 4문단짜리 마크다운 뉴스레터',
    agent=writer,
    output_file='output/new_post.md'   # 결과를 파일로 바로 저장
)

from crewai_tools import tool
import yfinance as yf

# 형태 1) 함수명이 곧 툴 이름
@tool
def latest_stock_price(ticker):
    """
    주어진 주식 티커에 대한 최근 종가를 가져오는 툴
    """                                    # ← docstring이 LLM에게 보이는 사용설명서
    historical = yf.Ticker(ticker).history(period='5d', interval='1d')
    return historical['Close']

# 형태 2) 툴 이름을 명시 + 타입 힌트로 인자 스키마 확정
@tool("Updated Comprehensive Stock Analysis")
def comprehensive_stock_analysis(ticker: str) -> str:
    """
    주어진 주식 티커에 대한 종합적인 재무 분석을 수행합니다.
    최신 주가 정보, 재무 지표, 성장률, 밸류에이션 및 주요 비율을 제공합니다.

    :param ticker: 분석할 주식의 티커 심볼
    :return: 재무 분석 결과를 포함한 문자열
    """
    # 본문은 아래 "반환값을 압축한다" 절에서 이어서 다룬다.
    # yfinance 원본 → LLM이 읽기 좋은 dict로 정제하는 부분이 전부다.
    ...

latest_stock_price.run("AAPL")   # 단독 테스트 — 툴은 크루 없이도 검증 가능

# 툴 내부: 원본 DataFrame → LLM이 읽기 좋은 압축 dict (핵심부만 발췌)
def format_number(n):
    return "N/A" if (n is None or pd.isna(n)) else f"{n:,.0f}"

def calculate_growth_rate(current, previous):
    if previous and current and previous != 0:
        return (current - previous) / abs(previous) * 100
    return None

t = yf.Ticker(ticker)
annual    = t.get_financials()                    # 연간 손익
quarterly = t.get_financials(freq="quarterly")    # 분기 손익
balance   = t.get_balance_sheet()                 # 재무상태표

revenue = annual.loc['TotalRevenue', annual.columns[0]]
net_income = annual.loc['NetIncome', annual.columns[0]]
total_assets = balance.loc['TotalAssets', balance.columns[0]]
total_liab = balance.loc['TotalLiabilitiesNetMinorityInterest', balance.columns[0]]

return {
    "현재 주가": {"현재 주가": latest_price, "기준 시간": latest_time},
    "연간 데이터": {
        "매출": format_number(revenue),
        "순이익": format_number(net_income),
        "순이익률": f"{net_income / revenue * 100:.2f}%",
        "매출 성장률": f"{calculate_growth_rate(revenue, annual.iloc[:,1]['TotalRevenue']):.2f}%",
        "부채비율": f"{total_liab / total_assets * 100:.2f}%",
    },
    # 분기 데이터도 같은 방식으로 QoQ 성장률까지 계산해 담는다.
    # (연간 블록과 구조가 동일해 생략)
    "분기 데이터": {},
}

llm        = LLM(model="openai/gpt-4o-mini")                       # 조사·분석용 (저렴)
invest_llm = LLM(model="anthropic/claude-3-5-sonnet-20240620")     # 최종 종합용 (고품질)
current_time = datetime.now()

financial_analyst = Agent(
    role="Financial Analyst",
    goal="회사의 재무 상태 및 성과 분석",
    backstory=f"재무제표와 비율 해석에 전문성을 갖춘 분석가입니다. 날짜: {current_time:%Y년 %m월 %d일}",
    tools=[comprehensive_stock_analysis],
    llm=llm, max_iter=3, allow_delegation=False, verbose=True   # 위임 차단 = 비용 통제
)
# market_analyst / risk_analyst / investment_advisor도 같은 형태로 정의한다.
# 차이는 role·goal·tools·llm 네 필드뿐이다.

def create_dynamic_tasks(ticker):        # 티커를 런타임 입력으로 받아 Task를 동적 생성
    financial_analysis = Task(
        description=f"{ticker}에 대한 철저한 재무 분석을 수행합니다. 날짜: {current_time:%Y년 %m월 %d일}",
        agent=financial_analyst,
        expected_output=f"{ticker}의 재무 상태 종합 보고서. 주요 지표·수익성·부채비율 포함"
    )
    # market_analysis / risk_assessment / investment_recommendation도 같은 형태로 만든다.
    # 마지막 Task의 expected_output에는 리포트 9절 목차를 통째로 넣는다.
    return [financial_analysis, market_analysis, risk_assessment, investment_recommendation]

crew = Crew(
    agents=[financial_analyst, market_analyst, risk_analyst, investment_advisor],
    tasks=create_dynamic_tasks(ticker),
    process=Process.sequential,
    verbose=True,
)
result = crew.kickoff()