24장. 서비스 통합과 실행

돌아보기 — 아키텍처의 네 칸은 어디서 채워졌나

한 줄 요약

1장에서 코드 한 줄 없이 그렸던 아키텍처 그림에는 도구 · 지식 · 기억 · 오케스트레이션 네 칸이 있었습니다. 스물네 장을 지나며 그 칸이 전부 실제 파일로 채워졌습니다. 마지막으로 그림으로 돌아가 어느 칸이 어느 장에서, 어느 파일로 채워졌는지 짚어 봅니다.

---

1. 1장의 그림

1장에서 이 그림을 두고 이렇게 말했습니다. "이후의 모든 장은 이 그림의 빈칸 하나씩을 실제 코드로 채우는 일입니다." 이제 빈칸이 없습니다.

---

2. 네 칸과 채운 장

그리고 네 칸을 고객과 상담원이 쓸 수 있게 한 서버로 묶은 것이 이번 장의 app/main.py입니다. 그림 맨 아래의 "서빙" 칸입니다.

도구 — 5~8장, 21장

도구는 두 묶음입니다. 그림의 "조회 도구"가 haru_tools.py, "처리 도구"가 haru_actions.py입니다.

Q8에서 기간이 지난 반품을 접수하지 않은 것, 티켓의 고객 이름이 "김*윤"으로 저장된 것도 이 칸의 결과입니다.

지식 — 12~15장

Q3과 Q4의 답 끝에 붙은 "(근거: … 제N조)"가 이 칸의 결과입니다. Q5에서 VIP 등급의 반품 배송비 면제를 멤버십 정책 제2조에서 찾아 답한 것, Q7에서 환불 기간을 정책 제5조를 근거로 답한 것도 같은 칸이 한 일입니다.

기억 — 16~17장

"그중 이어폰은 언제 발송된 거예요?"가 주문번호로 풀려 넘어간 것이 이 칸의 결과입니다. 서버의 histories 딕셔너리는 16장의 이력을 session_id별로 늘어놓은 것입니다.

서버에 붙일 수 있는 부품도 하나 남아 있습니다. 17장에서 만든 요약과 장기 기억은 아직 app/main.py에 연결하지 않았습니다. 지금 서버는 16장의 이력만 씁니다. 부품은 만들어 두었으니, 긴 대화와 재방문 고객을 다루게 될 때 붙이면 됩니다.

오케스트레이션 — 18~23장

Q6에서 주문조회, 정책안내, 요청처리가 차례로 불리고 세 보고가 답 하나로 묶인 것, Q9에서 주문조회 뒤에 요청처리가 이어져 배송지가 바뀐 것이 이 칸의 결과입니다.

사람도 이 지휘 체계 안에 있습니다. 그림의 처리 도구 칸에 적힌 "환불·취소 승인 요청 → 사람의 승인"이 그 자리입니다.

23장에서 interrupt로 만든 승인 게이트와 이번 장의 상담원 화면은 같은 설계의 두 모습입니다. 요청을 승인대기로 등록하는 request_refund, 사람의 결정을 기록하는 decide가 양쪽에서 똑같이 쓰입니다. 23장은 그 사이의 기다림을 그래프의 멈춤으로, 이번 장은 상담원 화면의 승인 대기 목록으로 보여 주었습니다.

---

3. 문의 하나가 지나간 길

Q6 "지난주에 산 운동화가 불량이에요. 검정 270으로 교환 접수해 주세요."가 지나간 길을 따라가며 네 칸을 한 번에 봅니다.

같은 시각 상담원 화면의 처리 내역에는 A00001 교환접수 · 완료가 올라옵니다. 이 요청이 교환이 아니라 환불이었다면 8번에서 승인대기로 등록되고, 그 뒤에 사람의 승인이라는 한 단계가 더 있었을 것입니다.

10초 남짓한 시간 동안 스물네 장의 거의 모든 부품이 한 번씩 일했습니다.

---

4. 과정 내내 반복된 것

네 칸을 채우는 동안 같은 판단이 여러 번 되풀이되었습니다. 기술 이름보다 이 판단이 남아야 합니다.

모델은 바뀝니다. 프레임워크도 바뀝니다. 위의 일곱 줄은 모델이나 프레임워크가 바뀌어도 그대로 쓸 수 있습니다.

---

5. 범위를 넓히려면 어느 칸에 무엇을 더하나

1장에서 이 시스템의 범위를 고객지원으로 정했습니다. 범위를 넓히는 일도 같은 네 칸으로 적을 수 있습니다.

네 번째 에이전트를 붙이는 방법은 이미 압니다. 21장처럼 도구와 프롬프트를 묶어 에이전트를 만들고, 22장처럼 함수로 감싸 Supervisor의 도구 목록에 넣고, 운영 원칙에 한 줄을 더한 뒤, 표준 질문 열두 개에 새 질문을 더해 다시 돌립니다. 새 기능을 "어느 칸에 무엇을 더하는 일"로 말할 수 있다는 것이 이 과정을 마치고 남는 것입니다.

---

핵심 정리

• 네 칸은 도구(5~8장, 21장) · 지식(12~15장) · 기억(16~17장) · 오케스트레이션(18~23장) 에서 채워졌고, 24장이 이를 한 서버로 묶었습니다.
• 도구는 조회 도구(haru_tools.py)와 처리 도구(haru_actions.py) 두 묶음이고, 오케스트레이션에는 요청처리 에이전트와 사람의 승인이 들어 있습니다.
• 남은 파일은 haru_tools.py, haru_actions.py, chroma_db/, haru_agents.py, haru_supervisor.py, app/main.py입니다.
• 문의 하나가 처리되는 동안 네 구성요소가 모두 한 번씩 일합니다.
• 17장의 요약·장기 기억은 만들어 둔 부품이고, 서버에 붙이는 일이 다음 확장입니다.
• 남는 것은 기술 이름이 아니라 되풀이된 판단입니다. 고르는 것은 모델, 실행과 보증은 코드, 바꿀 때마다 같은 질문으로 다시 확인.
• 범위를 넓히는 일을 어느 칸에 무엇을 더하는지로 말할 수 있습니다.