반환 타입 힌트(화살표➡️)

한마디 요약

-> 는 “이 함수가 뱉어내는 값의 타입”을 선언하는 표지판. 사람에게는 문서, IDE에게는 자동완성 근거, mypy 같은 타입체커에게는 검사 대상, LangChain @tool 같은 데코레이터에게는 JSON Schema 생성 재료로 쓰인다.

---

-> 가 무엇인가

화살표(->, return type annotation, 반환 타입 주석) 는 함수 정의 헤더에서 )와 : 사이에 붙는 Python 문법이다. PEP 3107(함수 주석), PEP 484(타입 힌트)에서 공식 도입되었다.

def get_db() -> Database:
    #         ↑ 이 함수는 Database 타입을 반환합니다
    return MySQLDatabase()

비교

# 반환 타입 없음
def get_number():
    return 42
 
# 반환 타입 있음
def get_number() -> int:
    #              ↑ int를 반환한다고 명시
    return 42

포함 관계

함수 시그니처(signature, 함수 선언부)
├─ 파라미터 타입 힌트: def f(x: int, y: str)
└─ 반환 타입 힌트: -> ReturnType        ← 이 문서 주제

반환 타입 힌트는 “함수 타입 힌트”의 한 종류. 파라미터 힌트와 쌍을 이룬다.

---

기본 반환 타입 총정리

# 원시 타입
def get_name() -> str:
    return "홍길동"
 
def get_age() -> int:
    return 30
 
def is_admin() -> bool:
    return True
 
def get_ratio() -> float:
    return 0.75
 
# 컬렉션 (Python 3.9+)
def get_prices() -> list[int]:
    return [100, 200, 300]
 
def get_user() -> dict[str, int]:
    return {"age": 25, "score": 99}
 
def get_coords() -> tuple[float, float]:
    return (37.5, 127.0)
 
def get_unique_tags() -> set[str]:
    return {"ai", "agent"}
 
# 반환값이 없는 함수
def process() -> None:  # return 없거나 return 만 있는 경우
    print("처리 완료")

Python 3.8 이하에서는 from typing import List, Dict, Tuple, Set 후 List[int] 같은 대문자 제네릭을 써야 한다. 3.9+ 부터는 소문자 list[int] 가 표준.

---

AI Agent 개발에서 자주 쓰는 고급 반환 타입

AI Agent 코드는 LLM 응답, 도구 실행 결과, 그래프 상태 객체를 자주 다루므로 Optional, Union, Callable, Awaitable, TypedDict, Pydantic 모델을 반환 타입으로 쓰는 빈도가 높다.

from typing import Optional, Union, Callable, Awaitable, TypedDict, Literal
from langchain_core.messages import BaseMessage
from langchain_core.tools import BaseTool
from pydantic import BaseModel
 
# 1. None 가능 (실패 시 None 반환 패턴)
def find_tool_by_name(name: str) -> Optional[BaseTool]:
    # Optional[BaseTool] == Union[BaseTool, None]
    return registry.get(name)  # 없으면 None
 
# 2. 여러 타입 중 하나 (Python 3.10+ 에서는 | 연산자로도 표기)
def parse_llm_output(text: str) -> Union[dict, str]:
    # JSON 파싱 성공이면 dict, 실패면 원문 str
    ...
 
def parse_llm_output_new(text: str) -> dict | str:  # 3.10+
    ...
 
# 3. 함수 객체 반환 (데코레이터, 클로저 팩토리)
def make_retry_wrapper(n: int) -> Callable[[Callable], Callable]:
    def decorator(func): ...
    return decorator
 
# 4. 비동기 함수 반환값 (await 대상)
async def call_llm(prompt: str) -> Awaitable[str]:
    ...
 
# 5. 그래프 State를 명시적으로 (LangGraph 패턴)
class AgentState(TypedDict):
    messages: list[BaseMessage]
    step: int
    done: bool
 
def agent_node(state: AgentState) -> AgentState:
    # State 일부만 갱신해 반환해도 LangGraph 가 merge 해줌
    return {"messages": state["messages"] + [...], "step": state["step"] + 1}
 
# 6. Pydantic 모델 반환 (FastAPI + tool call 응답 스키마)
class SearchResult(BaseModel):
    title: str
    url: str
    score: float
 
def search(query: str) -> list[SearchResult]:
    ...
 
# 7. Literal (반환값이 정해진 문자열 중 하나)
def classify_intent(text: str) -> Literal["search", "answer", "clarify"]:
    ...

---

왜 이렇게 쓰는가 (설계 의도)

관점	힌트 없음	힌트 있음
IDE 자동완성	반환값에 점 찍어도 아무것도 안 뜸	반환 객체의 메서드/속성 제안됨
mypy/pyright 검사	모든 사용처를 런타임까지 가야 확인	정적 단계에서 타입 불일치 검출
문서화	docstring 없으면 호출자가 본문 읽어야 함	시그니처만 봐도 계약 파악
LangChain @tool 스키마	추출 불가, 에러	-> int 를 JSON Schema "type": "integer" 로 변환
Pydantic create_model	스키마 자동 생성 불가	반환 타입이 API 응답 스키마로 직결
런타임 동작	동일	동일 (Python 은 힌트를 강제하지 않음)

중요: Python 은 타입 힌트를 강제(runtime enforcement)하지 않는다. -> int 라고 써도 실제로 문자열을 반환해도 에러가 안 난다. 검사는 mypy/pyright 같은 외부 도구의 몫. 이 특성 때문에 “선언적 문서 + 도구 지원” 목적이지 진짜 안전장치가 아님을 기억.

---

LangChain @tool 이 반환 타입 힌트를 쓰는 방식 (직접 확인)

AI Agent 에서 반환 타입 힌트가 실제로 런타임에 의미 있게 쓰이는 대표 지점.

from langchain_core.tools import tool
 
@tool
def get_weather(city: str) -> dict:
    """도시의 현재 날씨를 반환합니다."""
    return {"city": city, "temp": 22}
 
# 내부적으로 LangChain 이 한 일:
# 1. 함수 시그니처에서 파라미터 힌트 읽음  → args_schema 에 "city: str"
# 2. 반환 타입 힌트 읽음                 → 문서화/검증용
# 3. docstring 읽음                      → tool description
# 4. Tool 객체로 포장해 LLM 이 호출 가능하게 만듦
 
print(get_weather.args_schema.schema())
# {'properties': {'city': {'type': 'string', ...}}, ...}

타입 힌트 없이 @tool 을 쓰면 ValueError: ... must have type hints 류 에러가 난다. Agent 도구 정의에서는 타입 힌트가 사실상 필수.

---

관련 문서

• 함수의 타입 힌트 (파라미터 쪽 힌트)
• @데코레이터 (@tool 이 타입 힌트를 읽어가는 메커니즘)
• 함수경로(=none 의 의미) (Optional[X] = None 패턴과 연결)
• 함수(별args, 별별kwargs) (*args/**kwargs 에 타입 힌트 붙이는 법)

---

한마디 재요약

-> 는 함수의 출구에 붙이는 라벨이다. 사람에게는 계약서, 도구에게는 메타데이터, Agent 프레임워크에게는 LLM 에 넘길 스키마다.