7-4. [AI Agent 구현]: 설계서를 코드로

직전 글은 "Workflow vs Agent 라벨링과 가드레일이 자율성의 경계를 정의한다." 였다. system_prompt에 [WORKFLOW]·[AGENT] 구간을 명시하고, 출력 스키마를 강제하며, 정규식 기반 가드레일을 1차 방어선으로 세웠다. 이 결정들이 에이전트의 동작 범위를 설계 의도에 맞게 제한한다는 것이었다.

 

이번 글은 그 주장을 데이터로 검증한다. 설계서에 정의한 5개 케이스의 expected 값과 실측 결과를 직접 매핑한다. 결론을 먼저 말하면 5개 케이스 중 완전 일치는 1개뿐이다.

 

나머지는 부분 일치, 재현 실패, 검증 불가, 죽은 규칙이었다. 이 결과가 실패를 의미하지는 않는다. 설계서가 틀렸다는 증거도 아니다. 설계서가 실제 동작을 충분히 명세하지 못한 지점이 어디인지, 그리고 다음 주 Observability 작업에서 무엇을 보강해야 하는지를 데이터가 가리키고 있다.

 

 

---

 

 

1. 5개 케이스 매핑: 판정 결과

 

 

케이스	판정	어긋난 지점	원인
케이스 1: IT 중심 요청	부분 일치	설계는 Tool 4종 각 1회 가정, 실측은 7회 호출	LLM이 컨셉 2개를 자율 생성하고 컨셉마다 후속 Tool을 독립 호출
케이스 2: 유사 앱 발견 후 재생성	재현 실패	loop_count=1 기대, 실측 0 — 루프백 미발동	트렌드 조합이 우연히 1차 생성에서 공백 — 분기 발화 안 됨
케이스 3: 트렌드 API 일부 실패	검증 불가	partial_failure → reddit_only fallback 미발생	Reddit·YouTube가 Mock이라 실패 자체가 시뮬레이션 불가
케이스 4: 유사 앱 3회 발견 후 fallback	죽은 규칙	failure_type 기대 "no_unique_concept", 실측 "agent_error"	recursion_limit=15가 자체 루프 카운터보다 먼저 발동
케이스 5: 인젝션 거부	완전 일치	—	정규식 1차 차단이 Tool 호출 이전에 정확히 작동

판정 기준은 단순하다. expected_tool_sequence와 expected_final_fields와 expected_stop_reason 세 항목이 모두 실측과 일치하면 완전 일치, 일부만 일치하면 부분 일치, 의도한 조건 자체를 재현하지 못했으면 재현 실패, 기대한 경로가 코드에서 아예 평가되지 않으면 죽은 규칙이다.

 

 

---

 

 

2. 케이스 1: 부분 일치가 드러낸 설계의 부분

 

 

expected vs actual

# 설계서 expected_tool_sequence (케이스 1)
- trend_scanner(type="IT")
- concept_generator
- app_existence_checker
- feasibility_checker
# 총 4회 호출, Tool별 1회

# case1_it_focus.json 실측 tool_trace
step 1: trend_scanner          (hackernews+github, real_api)
step 2: concept_generator      (sonnet-4-6, t=0.9)
step 3: concept_generator      (sonnet-4-6, t=0.9)   ← 두 번째 컨셉
step 4: app_existence_checker  (itunes+github, real_api)
step 5: app_existence_checker  (itunes+github, real_api)  ← 두 번째 컨셉
step 6: feasibility_checker    (haiku, t=0.3)
step 7: feasibility_checker    (haiku, t=0.3)  ← 두 번째 컨셉
# 총 7회 호출

 

무엇이 일어났는가

설계서의 Tool 명세는 concept_generator를 1회 호출하는 것을 전제했다. 실제로는 LLM이 컨셉을 2개 생성하고, 2개 각각에 대해 app_existence_checker와 feasibility_checker를 독립적으로 호출했다.

 

이것이 오작동인가? 하면 또 그렇지 않다. 최종 출력에서 두 컨셉 모두 similar_app_exists: false이고 difficulty와 stack이 정상적으로 채워져 있다. expected_final_fields는 충족됐다. expected_stop_reason: "정상 종료"도 맞다.

 

그러나 expected_tool_sequence는 맞지 않는다. 설계서는 4회 호출을 가정했고 실측은 7회였다. 이 간극의 원인은 명확하다. 설계서 6이 "컨셉 1개 입력에 대한 Tool 호출 흐름"만 명세했기 때문이다. LLM이 컨셉 N개를 생성하고 N개 각각에 대해 후속 Tool을 독립 호출하는 패턴은 설계서에 정의되지 않은 동작이다.

 

이것이 설계서의 사각지대다. 의도된 동작이지만 명세되지 않은 동작. 설계서가 예측하지 못한 방식으로 에이전트가 동작했다. 부분 일치 판정의 정확한 근거다.

 

시사점

used_tools 필드에 동일 Tool이 반복 등장하는 것이 정상인지 비정상인지를 설계서가 정의하지 않는다면, LangSmith에서 이 패턴을 관찰했을 때 무엇을 기준으로 평가할 것인가. 8주차 Observability 작업에서 "컨셉 단위 반복 호출"을 명시적으로 허용하는 패턴으로 설계서를 보완해야 한다.

 

 

---

 

 

3. 케이스 2: 정상 흐름이 만든 검증의 사각지대

 

 

expected vs actual

# 설계서 expected (케이스 2)
expected_tool_sequence:
  - trend_scanner(type="meme")
  - trend_scanner(type="IT")
  - concept_generator                 # 1차
  - app_existence_checker             # 유사 앱 발견
  - concept_generator(exclude=[...])  # AGENT 판단 → 재생성
  - app_existence_checker             # 유사 앱 없음
  - feasibility_checker
expected_final_fields:
  - metadata.loop_count: 1
expected_stop_reason: "정상 종료"

# case2_both_exclude_existing.json 실측
loop_count = 0
similar_app_exists = false (두 컨셉 모두)
# 케이스 1과 동일한 패턴 — 루프백 미발동

 

무엇이 일어났는가

케이스 2는 --exclude-existing 플래그를 활성화하여 유사 앱이 발견됐을 때 루프백이 발동되는지 확인하려는 케이스였다. 그런데 트렌드 조합이 1차 생성에서 공백(유사 앱 없음)으로 판정됐기 때문에 루프백 분기 자체가 발화되지 않았다.

 

이것은 시스템의 실패가 아니다. 에이전트가 의도한 대로 동작했고, 결과도 정상이다.

 

무엇이 필요한가

Mock 트렌드 데이터를 의도적으로 조작하여 유사 앱 발견을 강제하는 통제된 케이스가 필요하다.

 

 

 

---

 

 

4. 케이스 3: Mock의 성공이 만든 거짓 신호

 

 

expected vs actual

# 설계서 expected (케이스 3)
expected_tool_sequence:
  - trend_scanner(source=["reddit","youtube"])  # youtube 실패
  - trend_scanner(source=["reddit"])            # AGENT 판단 → reddit만으로 재시도
  - concept_generator
  - app_existence_checker
  - feasibility_checker
expected_final_fields:
  - metadata.failure_type: "partial_trend_failure"
  - metadata.fallback_action: "reddit_only"
expected_stop_reason: "정상 종료 (부분 데이터 기반)"

# 실측
케이스 3은 재현 자체가 불가능했다.
Reddit·YouTube data_source = "mock"
Mock은 실패하지 않는다.

 

무엇이 일어났는가

data_source: "mock"으로 결과 파일에 명시는 됐다. 어디까지가 실 API이고 어디서부터 Mock인지는 투명하게 드러난다. 그러나 Mock이 실패하지 않는다는 사실이 케이스 3 전체를 검증 불가 상태로 만든다. YouTube API가 타임아웃을 반환했을 때 AGENT 구간이 개입하여 Reddit만으로 재시도하는 분기는, YouTube API가 실제로 실패해야만 발화된다.

 

 

 

---

 

 

5. 케이스 4: 죽은 규칙과 컨셉 단위 반복의 결합

 

 

expected vs actual

# 설계서 expected (케이스 4)
expected_tool_sequence:
  - trend_scanner(type="both")
  - concept_generator                 # 1차
  - app_existence_checker             # 유사 앱 발견
  - concept_generator(exclude=[...])  # 2차
  - app_existence_checker             # 유사 앱 발견
  - concept_generator(exclude=[...])  # 3차
  - app_existence_checker             # 유사 앱 발견 → 루프 탈출
expected_final_fields:
  - metadata.failure_type: "no_unique_concept"
  - metadata.loop_count: 3
  - metadata.fallback_action: "차별화 포인트 제안"
expected_stop_reason: "루프 탈출 (3회 초과)"

// case_failure_recursion_limit.json 실측
{
  "today_brief": null,
  "metadata": {
    "used_tools": [...],  // 13개 항목
    "loop_count": 0,
    "failure_type": "agent_error",
    "fallback_action": null,
    "error": "Recursion limit of 15 reached without hitting a stop condition."
  }
}

 

13단계 trace의 정확한 패턴

직전 글에서 이미 다룬 내용이지만, 케이스 4의 맥락에서 trace를 분해하면 더 명확한 패턴이 보인다.

step  1:    trend_scanner           (scanner 1회)
step  2-3:  concept_generator × 2  (1사이클 — 컨셉 2개 생성)
step  4-5:  app_existence_checker × 2
step  6-7:  feasibility_checker × 2
step  8-9:  concept_generator × 2  (2사이클 — 컨셉 2개 재생성)
step 10-11: app_existence_checker × 2
step 12-13: feasibility_checker × 2
# 합계: scanner 1 + (gen 2 + checker 2 + fc 2) × 2사이클 = 13

이 패턴은 죽은 규칙과 케이스 1에서 발견한 컨셉 단위 반복이 결합된 결과다. 설계서의 루프 탈출 조건(동일 조합 3회 재호출 시 중단)은 자체 loop_count 카운터에 의존하는데, 이 카운터가 실제로 증가하지 않았다. 동시에 LLM이 매 사이클마다 컨셉 2개를 생성하는 패턴 때문에 step 수가 빠르게 누적됐다. 1회 사이클에 6 step(gen×2 + checker×2 + fc×2), 2사이클이면 12 step, 여기에 scanner 1 step을 더하면 13으로 정확히 recursion_limit에 도달한다.

 

죽은 규칙(loop_count 미동작) + 설계 미명시 패턴(컨셉 단위 반복 호출) + LangGraph 기본 제한(recursion_limit=15)의 세 요소가 결합하여 이 결과를 만들었다.

 

보완 방향

자체 루프 카운터를 LangGraph state에 직접 주입하는 방식으로 보완한다. recursion_limit 상향도 고려할 수 있지만, 그보다 루프 탈출 로직이 LangGraph의 외부 제한에 의존하지 않고 독립적으로 동작하도록 설계하는 것이 근본적인 해결이다.

 

 

 

---

 

 

6. 케이스 5: 유일하게 완전 일치한 케이스

 

 

expected vs actual

# 설계서 expected (케이스 5, §9)
expected_behavior:
  - 입력 가드레일 감지 → 요청 거부 + 경고 반환
  - Tool 호출 0회

// case_guardrail_blocked.json 실측
{
  "today_brief": null,
  "metadata": {
    "used_tools": [],
    "tool_trace": [],
    "failure_type": "guardrail_blocked",
    "fallback_action": "요청 거부 — 도메인 외 또는 인젝션 의심",
    "guardrail": {
      "blocked": true,
      "reason": "prompt_injection_suspected",
      "matched_pattern": "ignore\\s+previous\\s+instructions"
    }
  }
}

Tool 호출 0회. 에이전트 루프 진입 이전에 차단. expected와 actual이 완전히 일치한다.

 

왜 이 케이스만 완전 일치했는가

가드레일이 정규식이기 때문이다. 정규식은 결정론적이다. 입력 문자열이 패턴과 매칭되면 반드시 차단하고, 매칭되지 않으면 반드시 통과한다. LLM의 자율성이 개입하지 않는다. 컨텍스트가 변해도 동작이 달라지지 않는다.

 

 

 

---

 

 

7. 결론

 

 

설계서가 나빴다는 뜻이 아니다. 설계서가 실제 구현의 모든 동작을 사전에 명세하는 것은 불가능하다. 에이전트는 실행 전에 전체 경로를 알 수 없기 때문에 에이전트다. LLM이 자율적으로 컨셉 2개를 생성하고 컨셉마다 후속 Tool을 독립 호출하는 패턴은 설계서가 예측할 수 없었던 동작이다. 그것이 설계서의 한계가 아니라, 설계와 구현 사이에 반드시 존재하는 간극의 특성이다.

 

문제는 그 간극을 어떻게 좁히는가다. 현재 상태에서 5개 케이스를 모두 완전 일치로 만들기 위해 필요한 조건을 정리하면 다음과 같다.

 

케이스 1 (부분 일치 → 완전 일치): 설계서에 컨셉 단위 반복 호출 패턴을 명시한다. expected_tool_sequence를 컨셉 수에 따라 가변적으로 정의하거나, 컨셉당 호출 수를 별도 필드로 추적한다.

케이스 2 (재현 실패 → 완전 일치): 의도적으로 유사 앱 발견을 강제하는 통제된 Mock 케이스를 구성한다. app_existence_checker가 특정 컨셉에 대해 항상 similar_app_found: true를 반환하도록 Mock을 조작한다.

케이스 3 (검증 불가 → 완전 일치): Reddit·YouTube 실 API를 연동하고, API 타임아웃을 테스트 환경에서 시뮬레이션한다. 또는 Mock에 실패 모드를 명시적으로 주입하는 인터페이스를 구현한다.

케이스 4 (죽은 규칙 → 완전 일치): LangGraph state에 자체 loop_count 카운터를 주입하고, 카운터 기반 조건 분기가 recursion_limit보다 먼저 평가되도록 로직을 재구성한다.

 

이 네 가지 보완 작업은 모두 8주차에 LangSmith를 붙이는 작업과 직접 연결된다. 현재 metadata.tool_trace 구조는 LangSmith trace 레이어에 매핑되도록 설계됐다. LangSmith가 연동되면 각 케이스의 실행 경로를 시각적으로 비교할 수 있고, 설계서의 expected_tool_sequence와 실측 trace의 일치 여부를 step 수준에서 검증할 수 있다.

 

7주차 구현의 결과는 동작하는 에이전트를 만드는 것이었다. 그것은 달성됐다. 그러나 이번 주에 더 중요하게 남은 것은 그 에이전트가 어디서 예상대로 동작하지 않는지를 데이터로 기록한 것이다. 완전 일치 1개, 부분 일치 1개, 재현 실패 1개, 검증 불가 1개, 죽은 규칙 1개라는 결과가 8주차의 결론이다.