에이전트 그래프
에이전트 그래프 (Agent Graphs)
Langfuse의 에이전트 그래프는 복잡한 AI 에이전트 워크플로를 시각적으로 표현해, 다단계 추론 과정과 에이전트 상호작용을 이해하고 디버깅하는 데 도움을 줘요.
출처: 문서
본문
Langfuse의 에이전트 그래프는 복잡한 AI 에이전트 워크플로를 시각적으로 표현해, 다단계 추론 과정과 에이전트 상호작용을 이해하고 디버깅하는 데 도움을 줘요.
에이전트 그래프 뷰가 있는 예시 trace (공개 링크)
시작하기 (Get Started)
trace에 그래프가 나타나는 방법은 두 가지가 있어요:
- observation에서 추론(Inferred). trace에 span·event·generation을 제외한 어떤 observation 유형의 observation이 있어요. 그러면 Langfuse는 trace를 에이전틱(agentic)으로 해석하고, observation의 타이밍과 중첩에서 자동으로 추론한 그래프를 보여줘요.
- LangGraph 통합에서. LangGraph 통합을 사용하면 그래프가 자동으로 나타나요.
Observation Types: 모든 사용 가능한 Observation Types를 보고 설정하는 법을 확인하세요. LangGraph: LLM 에이전트 트레이싱을 위해 LangGraph를 Langfuse와 네이티브로 통합하는 end-to-end 예시는 LangGraph integration 가이드를 참고하세요.
뷰 모드: 집계(Aggregated)와 확장(Expanded)
같은 trace를 두 가지 방식으로 그릴 수 있어요. 그래프 왼쪽 위의 Aggregated / Expanded 토글 사이를 전환하세요. 선택은 trace 간에도 기억돼요.
차이는 반복되는 단계를 어떻게 다루는가에 있어요 — 단계 이름당 한 노드 vs 호출당 한 노드:
| Aggregated (기본값) | Expanded ("실행된 그대로") | |
|---|---|---|
| 노드가 의미하는 것 | 하나의 고유 단계 이름 | 하나의 개별 호출 |
| 반복 호출 | 카운터가 있는 단일 노드로 접힘 | 별도 노드로 나타남 |
| 루프 / 사이클 | 사이클로 그려짐 (에지가 루프백) | 비순환 그래프(DAG)로 풀림 |
| 읽히는 방식 | 에이전트의 전체적 형태 | 정확한 실행, 단계별 |
| 가장 적합한 곳 | 구조와 복잡성을 한눈에 파악 | 특정 실행 추적 또는 디버깅 |
집계 뷰 (Aggregated)
Aggregated 뷰는 컴팩트한 개요예요. 이름을 공유하는 단계는 카운터와 함께 단일 노드로 병합돼요 —
retrieve_docs (3/3)는 그 단계가 세 번 실행됐다는 뜻이에요 — 그리고 같은 도구를 반복 호출하는 루프는 긴 체인 대신 사이클로 그려져요. 이렇게 하면 바쁜 에이전트도 읽기 쉽게 유지돼요: 화면에 모든 개별 호출 없이 몇 개의 뚜렷한 단계가 있고 어떻게 연결되는지 볼 수 있어요. "이 에이전트는 무엇을 하고 얼마나 복잡한가요?"라는 질문에 답하는 가장 빠른 방법이에요.
확장 뷰 (Expanded)
Expanded 뷰는 실행된 그대로의 전체 프로세스를 보여줘요. 모든 호출이 자체 노드라서, 세 번의
litellm_request호출은 세 개의 뚜렷한 노드이고, 루프는 실행 순서의 방향성 비순환 그래프로 풀려요. 더 문자 그대로이고 trace 트리에 더 가까워요 — 특정 run을 처음부터 끝까지 따라가거나 정확히 어디에서 무언가가 발생했는지 짚고 싶을 때 적합한 뷰예요. 큰 trace는 자연스럽게 집계 뷰보다 여기서 더 많은 노드를 만들어요.
둘 중 어느 것이 "올바른" 건 아니에요 — 서로 다른 질문에 답해요. 에이전트의 구조를 이해하려면 Aggregated를, 단일 run을 따라가려면 Expanded를 사용하세요.
GitHub Discussions
더 알아보기 (Learn more)
- 출처 문서: 에이전트 그래프 (Agent Graphs)