LangGraph 핵심
중급 35분#langgraph#functional-api#entrypoint#task

Functional API: @entrypoint와 @task

그래프를 명시적으로 그리지 않고 평범한 Python 제어 흐름으로 LangGraph 워크플로를 작성하는 Functional API를 배웁니다. 병렬 task, 체크포인트 기반 재개, previous와 entrypoint.final, 그리고 Graph API와의 선택 기준을 다룹니다.

학습 목표
  • •@entrypoint와 @task로 워크플로를 작성하고 invoke/stream 할 수 있다
  • •task가 퓨처(future)를 반환한다는 점을 이용해 병렬 실행을 구현할 수 있다
  • •체크포인터와 함께 쓸 때 task 결과가 저장되어 실패 후 재개 시 재실행되지 않는 원리를 설명할 수 있다
  • •previous와 entrypoint.final로 스레드 단위의 상태를 이어 갈 수 있다
  • •Graph API와 Functional API 중 상황에 맞는 것을 고를 수 있다

Functional API: @entrypoint와 @task

지금까지 우리는 상태 스키마를 선언하고, 노드를 등록하고, 엣지를 그어 그래프를 만들었습니다. 이 방식(Graph API)은 흐름이 눈에 보이고 구조가 명시적이라는 큰 장점이 있습니다. 하지만 솔직히 말해 간단한 일에는 손이 많이 갑니다. "A를 하고, 결과가 이러면 B를, 아니면 C를 세 번 반복" 같은 흐름은 Python의 if와 for로 쓰면 다섯 줄인데, 그래프로 옮기면 상태 클래스, 노드 함수, 조건부 엣지, 라우팅 함수가 필요합니다.

Functional API는 이 간극을 메웁니다. 평범한 Python 함수와 제어 흐름을 그대로 쓰면서도, LangGraph 런타임의 핵심 기능인 체크포인트(영속성), 중단/재개, 스트리밍, 병렬 실행을 그대로 누릴 수 있게 해 줍니다. 두 API는 같은 런타임 위에서 동작하는 두 가지 작성 방식입니다.

1. 두 개의 데코레이터

데코레이터역할Graph API에 비유하면
@entrypoint워크플로의 시작점. 전체 흐름을 Python 코드로 기술그래프 전체 (compile() 결과)
@task독립된 작업 단위. 결과가 체크포인트에 저장됨노드
python
from langgraph.func import entrypoint, task

@task
def fetch_profile(user_id: str) -> dict:
    return DB[user_id]

@task
def write_greeting(profile: dict) -> str:
    return f"{profile['name']}님, 안녕하세요!"

@entrypoint()
def greet_workflow(user_id: str) -> str:
    profile = fetch_profile(user_id).result()     # task 호출 → 퓨처 → .result()로 값 받기
    return write_greeting(profile).result()

greet_workflow.invoke("u1")

몇 가지 규칙이 눈에 띕니다.

  • @entrypoint 함수는 인자를 하나만 받습니다. 여러 값이 필요하면 dict로 묶어 넘깁니다.
  • @entrypoint로 장식된 함수는 더 이상 평범한 함수가 아니라 Pregel 객체(컴파일된 그래프와 같은 종류)입니다. 그래서 invoke, stream, get_state 등을 그대로 씁니다.
  • @task 함수를 호출하면 즉시 값이 아니라 퓨처(future) 가 돌아옵니다. .result()를 호출해야 값을 받습니다. 이것이 병렬 실행의 열쇠입니다.

2. 퓨처와 병렬 실행

task 호출이 퓨처를 돌려준다는 것은, 여러 task를 먼저 출발시키고 나중에 결과를 모을 수 있다는 뜻입니다.

python
@entrypoint()
def research(topics: list[str]) -> list[str]:
    futures = [summarize(t) for t in topics]     # 모두 '출발' (병렬 실행)
    return [f.result() for f in futures]          # 모두 '도착'을 기다림

Graph API에서 Send로 구현했던 map-reduce(→ 4.4)가 리스트 컴프리헨션 두 줄이 됐습니다. 리듀서도 필요 없습니다. 결과는 그냥 Python 리스트이기 때문입니다.

주의

[summarize(t).result() for t in topics]처럼 호출하자마자 .result()를 붙이면 하나가 끝나야 다음이 출발하므로 순차 실행이 됩니다. 병렬로 돌리고 싶다면 퓨처를 먼저 모두 만든 뒤에 결과를 기다리세요.

▶ 오른쪽 IDE의 examples/01_basics.py를 실행해 보세요. 순차 실행과 병렬 실행의 소요 시간 차이를 직접 측정합니다.

3. 영속성: task 결과는 저장된다

Functional API의 진짜 힘은 체크포인터와 함께 쓸 때 드러납니다.

python
from langgraph.checkpoint.memory import InMemorySaver

@entrypoint(checkpointer=InMemorySaver())
def pipeline(order_id: int) -> str:
    order = load_order(order_id).result()          # task 1: 성공 → 결과 저장
    receipt = charge_payment(order).result()       # task 2: 일시 장애로 실패!
    return send_email(receipt).result()

charge_payment가 실패하면 실행은 예외로 끝나지만, 이미 성공한 load_order의 결과는 체크포인트에 남아 있습니다. 같은 thread_id로 pipeline.invoke(None, config)를 호출하면 워크플로가 재개되는데, 이때 load_order는 다시 실행되지 않고 저장된 결과를 재사용합니다.

이것이 내구성 있는 실행(durable execution) 입니다(→ 5.5). 비싼 LLM 호출이나 외부 API 호출을 task로 감싸 두면, 뒤 단계가 실패해도 앞 단계를 다시 돈 내고 호출하지 않습니다. interrupt()로 사람 승인을 기다렸다가 재개할 때도 같은 원리로 앞 단계가 재실행되지 않습니다(→ 5.3).

중요

재개할 때 entrypoint 함수 본문은 처음부터 다시 실행됩니다. 다만 task 호출은 저장된 결과로 즉시 대체될 뿐입니다. 그래서 다음 두 규칙이 중요합니다.

  1. 부수 효과(side effect)는 반드시 task 안에서. entrypoint 본문에서 직접 이메일을 보내거나 DB에 쓰면 재개할 때마다 또 실행됩니다.
  2. 비결정적 코드도 task 안에서. random, 현재 시각, LLM 호출을 entrypoint 본문에서 직접 하면 재개 때 다른 값이 나와 흐름이 달라질 수 있습니다. task로 감싸면 첫 실행의 결과가 저장되어 재개 시에도 같은 값이 쓰입니다.

4. previous와 entrypoint.final: 스레드 단위 상태

Graph API에서는 상태 객체가 실행 사이에 이어졌습니다. Functional API에서는 그 역할을 previous 가 합니다. entrypoint 함수가 previous라는 이름의 키워드 인자를 받으면, 같은 스레드에서 지난번 실행의 반환값이 주입됩니다(체크포인터 필요).

python
@entrypoint(checkpointer=InMemorySaver())
def counter(event: str, *, previous: dict | None = None) -> dict:
    stats = previous or {"count": 0, "events": []}
    return {"count": stats["count"] + 1, "events": [*stats["events"], event]}

반환값과 저장할 값을 다르게 하고 싶을 때는 entrypoint.final을 씁니다.

python
return entrypoint.final(value=reply, save=new_history)
#                       ↑ 호출자에게 반환     ↑ 다음 실행의 previous로 저장

예를 들어 챗봇이라면 호출자에게는 이번 답변 한 줄(value)만 돌려주고, 다음 턴을 위해서는 전체 대화 기록(save)을 저장하는 식입니다.

entrypoint는 previous 외에도 config(RunnableConfig), runtime(컨텍스트, 스토어, 스트림 writer 등을 담은 Runtime 객체)을 키워드 인자로 요청할 수 있습니다.

▶ examples/02_durable_and_memory.py에서 실패 후 재개(앞 task가 다시 실행되지 않는 것)와 previous/entrypoint.final을 이용한 LLM 챗봇의 대화 기억을 확인해 보세요.

5. task에도 정책을 붙일 수 있다

@task는 Graph API의 add_node와 비슷한 옵션을 받습니다.

python
from langgraph.types import RetryPolicy

@task(retry_policy=RetryPolicy(max_attempts=3))
def call_flaky_api(query: str) -> dict:
    ...

재시도 정책, 캐시 정책, 타임아웃을 task 단위로 지정할 수 있습니다. 세부 설정과 멱등성 설계는 신뢰성 강의(→ 5.5)에서 다룹니다.

6. Graph API vs Functional API

같은 문제를 두 방식으로 풀어 보면 차이가 선명해집니다. ▶ examples/03_graph_vs_functional.py는 "초안 작성 → 평가 → 기준 미달이면 재작성(최대 3회)" 루프를 두 API로 각각 구현해 결과를 비교합니다.

관점Graph APIFunctional API
흐름 표현노드·엣지로 명시if/for/while 그대로
상태공유 상태 스키마 + 리듀서함수 지역 변수 + previous
시각화draw_mermaid()로 전체 구조entrypoint 하나로만 보임
병렬엣지 팬아웃, Send퓨처 여러 개 출발
체크포인트 단위슈퍼스텝마다 상태 저장task 결과 + entrypoint 반환값
타임 트래블·상태 편집세밀하게 가능 (→ 5.2)제한적
잘 맞는 곳복잡한 분기, 멀티 에이전트, 팀 협업, 구조를 보여 줘야 할 때기존 코드에 영속성/HITL 추가, 선형·단순 흐름, 빠른 프로토타입

선택 기준은 이렇습니다.

  • 흐름 자체가 제품의 핵심이고 여러 사람이 함께 보고 고쳐야 한다면 Graph API. 그림이 문서 역할을 하고, 상태 단위로 디버깅과 타임 트래블이 쉽습니다.
  • 이미 있는 Python 코드(배치 스크립트, 서비스 로직)에 체크포인트·재개·사람 승인을 얹고 싶다면 Functional API. 코드를 거의 그대로 두고 함수에 데코레이터만 붙이면 됩니다.
  • 둘은 섞을 수 있습니다. entrypoint 안에서 컴파일된 그래프를 호출해도 되고, 그래프 노드 안에서 entrypoint를 호출해도 됩니다.

7. 현업에서는

  • "task 경계 = 비용 경계". 비싼 LLM 호출과 외부 API 호출은 각각 별도 task로 감싸세요. 실패 후 재개, 사람 승인 후 재개 시 이미 돈을 낸 호출이 반복되지 않습니다.
  • 직렬화 가능한 값만. task의 입력과 반환값은 체크포인트에 저장되므로 직렬화 가능해야 합니다. DB 커넥션, 파일 핸들, 거대한 객체를 반환하지 마세요.
  • 관측성. LangSmith 트레이스에서 각 task가 별도 실행으로 기록됩니다. task 이름을 의미 있게 지으면(@task(name="charge_payment") 또는 함수 이름) 트레이스 가독성이 좋아집니다.
  • 테스트. entrypoint는 일반 함수처럼 입력과 출력이 명확해 테스트하기 쉽습니다. 실패 주입(첫 호출에 예외) 테스트로 재개 동작을 검증해 두면 장애 시 안심할 수 있습니다.
  • 시각화의 한계 인지. Functional API 워크플로는 그림으로 내부 흐름이 보이지 않습니다. 운영 중 "지금 어디까지 진행됐나?"를 보여 줘야 한다면 runtime.stream_writer 등으로 진행 이벤트를 직접 내보내거나(→ 8.1), Graph API를 고려하세요.
경고

안티패턴: entrypoint 본문에서 LLM을 직접 호출하고, 그 뒤 task에서 실패가 나는 코드. 재개할 때 본문이 다시 실행되므로 LLM이 또 호출되고(비용), 다른 답이 나와 이후 흐름이 바뀔 수 있습니다(비결정성). LLM 호출은 task 안에서.

8. 정리

  • @entrypoint는 워크플로의 시작점(Pregel 객체), @task는 결과가 저장되는 작업 단위입니다.
  • task 호출은 퓨처를 반환합니다. 여러 퓨처를 먼저 만들고 나중에 .result()로 모으면 병렬 실행됩니다.
  • 체크포인터와 함께 쓰면 성공한 task 결과가 저장되어, invoke(None, config)로 재개할 때 재실행되지 않습니다.
  • 부수 효과와 비결정적 코드는 반드시 task 안에 둡니다.
  • previous로 지난 반환값을 받고, entrypoint.final(value=..., save=...)로 반환값과 저장값을 분리합니다.
  • 구조가 핵심이면 Graph API, 기존 코드에 영속성을 얹을 땐 Functional API. 둘은 섞어 쓸 수 있습니다.

이것으로 LangGraph 핵심 모듈을 마칩니다. 다음 모듈에서는 체크포인터와 스레드, 타임 트래블, 사람 승인(Human-in-the-loop), 장기 메모리 등 영속성을 본격적으로 다룹니다.

이해도 체크

0/5 · 정답 0
  1. Q1.@task로 장식한 함수를 호출하면 무엇이 반환되나요?

  2. Q2.다음 중 task 3개를 병렬로 실행하는 코드는?

  3. Q3.체크포인터가 있는 entrypoint에서 두 번째 task가 실패한 뒤 invoke(None, 같은 thread_id)로 재개하면?

  4. Q4.entrypoint.final(value=a, save=b)의 의미는?

  5. Q5.Functional API보다 Graph API가 더 적합한 경우는?

01_basics.py
02_durable_and_memory.py
03_graph_vs_functional.py
실습 과제
에디터 로딩 중…
출력
▶ 실행(⌘/Ctrl + Enter)하면 결과가 여기에 표시됩니다.