ReAct 반복 상한 vs Flow 재귀 한계

LLaMON Agent SDK는 LangGraph recursion_limit을 두 가지 경로에서 다르게 해석합니다. 운영자가 이름만 보고 오해하지 않도록 이 문서에서 의미를 고정합니다.

핵심 요약

항목	값	비고
Env 변수	`REACT_MAX_ITERATIONS`	ReAct 모드에서만 유효
Python API	`ExtensionConfig(max_retry=N)`	필드명은 v0.3.0까지 유지
내부 변환	`recursion_limit = max_retry * 2 + 1`	`core.recursion.react_recursion_limit()`
Flow 모드 재귀 한계	LangGraph 기본 `25`	`MAX_RETRY` 영향 없음

왜 `×2+1` 인가

한 번의 ReAct 사이클은 두 개의 LangGraph 노드 전이로 구성됩니다.

LLM 노드 (think): 다음 action을 결정
Tool 노드 (act): tool 실행 후 결과를 메시지에 합성

여기에 마지막 사이클 이후 tool 호출 없이 최종 응답을 반환할 LLM 노드 1회가 추가로 필요합니다. 따라서:

recursion_limit = iterations * 2 + 1

예:

REACT_MAX_ITERATIONS=3 → recursion_limit=7 (기본값)
REACT_MAX_ITERATIONS=5 → recursion_limit=11 (validate 도구를 여러 번 호출하는 워크플로 권장)

템플릿별 적용 규칙

템플릿 카테고리	ReAct 사용	Env 노출
`simple` (ollama / agent-openai / agent-anthropic)	사용	`REACT_MAX_ITERATIONS=3`
`registry-general`	사용	`REACT_MAX_ITERATIONS=3`
`registry-structured`	거의 미사용 (JSON 한 번 생성)	주석 처리 (기본값 3 권장)
`graph-*` (Flow 4종)	미사용	노출 없음 (기본 recursion_limit=25 사용)

Flow 템플릿(graph_sequential, graph_parallel, graph_conditional, graph_http_pipeline)은 사용자가 직접 작성한 LangGraph를 compiled_flow로 실행합니다. 런타임은 Flow 경로에서 recursion_limit을 설정하지 않으므로 LangGraph 기본값 25가 그대로 적용됩니다.

Agent Card 노출 (`urn:llamon:agent-config`)

.well-known/agent-card.json의 extension params에 maxRetry 키로 노출됩니다.

{
  "uri": "urn:llamon:agent-config",
  "params": {
    "llm": { },
    "maxRetry": 3
  }
}

JSON 키 maxRetry는 외부 계약이므로 변경하지 않습니다. Studio 및 다른 A2A consumer가 이 키를 파싱합니다.
Studio UI와 docs preview는 라벨만 “ReAct Max Iter.”로 표시하여 의미를 명확히 합니다.
Flow 템플릿이어도 이 필드는 노출되지만 실제 런타임에 영향을 주지 않습니다. (consumer 호환을 위해 유지)

ReAct 반복 상한 vs Flow 재귀 한계

핵심 요약

왜 ×2+1 인가

템플릿별 적용 규칙

Agent Card 노출 (urn:llamon:agent-config)

관련 문서

왜 `×2+1` 인가

Agent Card 노출 (`urn:llamon:agent-config`)