2. LangGraph 기본기
중간 결과 보여 주기, 형식 고정해 받기
이 차시를 마치면
중간 결과를 보여 주는 방법과 형식을 고정해 받는 방법을 씁니다.
답이 다 나올 때까지 화면이 멈춰 있으면 사람은 기다리지 않습니다. 그리고 모델이 준 글을 코드가 받아 쓰려면 형식이 일정해야 합니다. 두 가지를 함께 다룹니다.
Streaming
개념. 최종 답변만 보여 주는 대신 token, message, State 갱신값을 중간에 전달합니다.
어디에 쓰는가.
- 긴 research Agent — 진행 중임을 보여 줍니다
- Tool 사용 진행 표시
- long-running 작업 흐름의 사용자 경험
- State 변화 관찰
비유
택배 배송에서 "배송 완료" 한 번만 알려 주는 것과 "집화 → 간선상차 → 배송출발"을 단계마다 알려 주는 것의 차이입니다. 걸리는 시간은 같지만, 후자는 기다리는 사람이 지금 어디쯤인지 압니다. 멈춰 있는지 진행 중인지도 구분됩니다.
Structured Output
개념. schema 를 만족하는 객체를 반환하게 만듭니다.
장점. 파싱 안정성, 값 검사, UI 연결, DB 저장, 다음 Node 로 안정적 전달.
from pydantic import BaseModel, Field
class RelevanceDecision(BaseModel):
relevant: bool
score: float = Field(ge=0, le=1)
reason: str
1.x 실무 기준은 이렇습니다.
- Agent 에는
response_format=Schema를 지정합니다 - provider 가 native Structured Output 을 지원하면 provider 전략을 씁니다
- 지원하지 않으면 Tool calling 기반 전략을 씁니다
흔한 실수 세 가지
| 실수 | 왜 문제인가 분석 |
|---|---|
| JSON 처럼 "보이게" 프롬프트로만 요구 | 모델이 설명을 덧붙이거나 형식을 바꾸면 파싱이 깨집니다 |
| schema 검사 실패 처리를 안 함 | 실패가 조용히 지나가고 다음 Node 에서 엉뚱한 곳이 터집니다 |
| Tool 과 Structured Output 동시 지원 여부를 모델별로 확인하지 않음 | 모델을 바꾼 뒤에야 동작하지 않음을 알게 됩니다 |
보안 관점에서
Structured 출력은 모델이 돌려주는 값의 범위를 좁힙니다. 자유 문장을 받아 코드가 해석하면 예상 못 한 값이 흘러 들어옵니다. schema 로 받으면 허용된 형태만 통과합니다. 분석
다만 schema 를 지킨다고 내용이 참이 되는 것은 아닙니다. 형식 검사와 사실 검사는 다른 일입니다.
반대로 Streaming 은 주의가 필요합니다. 중간 상태를 그대로 화면에 흘리면 아직 승인되지 않은 초안이나 내부 판단 근거가 노출될 수 있습니다. 무엇을 흘릴지 고르는 일이 필요합니다. 분석
이 차시의 파이썬 코드는 개념을 보이려고 떼어 놓은 예시 조각입니다. 문법 검사는 통과하지만 그대로 돌려서 결과를 확인한 코드는 아닙니다. 실행까지 검증한 코드는 4번과 6번 트랙에 있으며, 그 차시에는 무엇을 어떻게 확인했는지 따로 적어 두었습니다.