도구 하나로는 부족한 순간

2편에서 에이전트에 도구 하나(체중조회)를 줬습니다. "A개체 교배 체중 돼?"에 42g을 조회해 답했죠.
근데 현실 질문은 보통 하나로 안 끝나요. "교배 가능한지 보고, 주의사항도 알려주고, 사육장 온도도 괜찮은지 봐줘" — 이건 도구 여러 개를 순서대로 써야 답이 나옵니다.

3편 주제가 그거예요. 도구를 여러 개 쥐여주면, LLM이 스스로 골라 연쇄로 호출합니다. 사람이 "체중 먼저, 그다음 검색, 그다음 환경"이라고 안 짜줘도, 관찰을 보며 다음 도구를 정하죠. 이게 진짜 멀티스텝 에이전트입니다.

3편에서 하는 것: 멀티스텝 루프(도구 선택→실행→관찰→반복) → 도구 3개(체중조회·KB검색·환경체크) → 그중 KB검색은 지난 KG-RAG 시리즈의 Neo4j(Docker로 띄움)에 붙입니다 → 무한루프·실패·종료 안전장치. 도구 연쇄·Docker·Neo4j Browser를 전부 실제로 돌려 캡처했습니다. 예시 개체는 익명 A/B/C.

한 계단씩 올라가듯, 멀티스텝 에이전트는 도구를 단계별로 연쇄 호출한다. (사진: Wikimedia Commons, Public Domain)

멀티스텝 에이전트가 뭔가요?

멀티스텝은 도구 선택 → 실행 → 관찰을, 목표를 달성할 때까지 LLM이 스스로 반복하는 것입니다. 한 도구의 결과(관찰)를 보고 "아직 부족하네, 다음은 이 도구"를 LLM이 판단합니다. 사람이 순서를 정해주지 않아도, 관찰을 근거로 다음 행동을 고르는 게 핵심입니다.

말보다 실제 실행을 보는 게 빠릅니다. "A개체 교배 가능한지 확인하고, 교배 전 주의사항도 알려줘"를 던졌더니, 에이전트가 도구를 네 번 연쇄로 호출하더라고요.

체중조회(42g) → KB에서 교배 기준 검색 → 다시 온도·습도 주의사항 검색 → 사육장 warm 구역 환경 확인 → 그제서야 종합 판단. 제가 순서를 안 짰는데 알아서 이렇게 엮더라고요. ㅎㅎ 관찰을 보며 "아직 부족, 다음은 이거"를 스스로 정한 겁니다.

도구를 여러 개 주면 어떻게 고르나요?

도구 3개를 줬습니다. 체중조회(get_gecko_weight), 사육지식 검색(search_care_kb), 환경체크(check_environment). LLM은 각 도구의 설명을 보고 질문에 맞는 걸 고릅니다. 질문이 "체중이랑 환경 둘 다 봐줘"면 체중조회와 환경체크를, "주의사항 알려줘"면 KB검색을 부르는 식입니다.

"체중이랑 사육장 온도 둘 다 괜찮은지 봐줘"라고 물으니, 체중조회와 환경체크를 골라 쓰고 중간에 기준 확인용으로 KB까지 곁들이더군요.

# 도구를 dict로 모아두면, LLM이 설명을 보고 고른다
TOOLS = {
  "get_gecko_weight": {"fn": get_gecko_weight,
    "desc": "개체(A/B/C)의 체중·성별·상태 조회"},
  "search_care_kb": {"fn": search_care_kb,
    "desc": "사육 지식을 Neo4j에서 검색"},
  "check_environment": {"fn": check_environment,
    "desc": "사육장 구역(warm/cool) 온·습도 조회"},
}

# 루프: LLM이 Action으로 도구 이름+입력을 내면, 우리가 실행해 Observation으로 되먹임
for step in range(max_steps):
    out = claude(transcript)              # 추론 1턴
    kind, data = parse(out)
    if kind == "final": break
    obs = TOOLS[data["action"]]["fn"](**json.loads(data["input"]))  # 실제 실행
    transcript += f"{out}\nObservation: {obs}\n"   # 결과 되먹임 → 다음 턴

그런데 Neo4j는 왜 Docker로 띄우나요?

KB검색 도구는 지난 KG-RAG 시리즈에서 만든 Neo4j에 붙습니다. 그 Neo4j는 Docker 컨테이너로 띄웠습니다. Docker는 프로그램을 '격리된 한 칸'에 담아 한 줄로 켜고, 끄면 흔적 없이 정리하는 도구입니다. 내 PC 환경과 분리돼 버전 충돌이 없고, 같은 이미지면 어디서든 똑같이 재현됩니다.

복잡한 DB를 직접 설치하면 의존성 꼬이기 십상인데, Docker는 docker run 한 줄로 끝납니다. 지금 우리 Neo4j 컨테이너가 떠 있는지 확인해봤어요. 우리 RAG 검색에 쓰는 컨테이너 하나만 나오게 필터링했습니다(다른 컨테이너는 이 글과 무관해서 가렸어요).

# 비밀번호는 환경변수로 — 코드/캡처에 직접 노출하지 않는다
docker run -d --name neo4j-kgrag \
  -p 7474:7474 -p 7687:7687 \
  -e NEO4J_AUTH=neo4j/$NEO4J_PASS \
  neo4j:5.26

# 확인 (우리 컨테이너만 필터)
docker ps --filter name=neo4j
# → 7474(브라우저), 7687(bolt) 포트로 접속

지난 RAG 검색이 에이전트의 도구가 됐다고요?

search_care_kb 도구는 질문과 관련된 사육 지식을 Neo4j 그래프에서 가져옵니다. 1편에서 "RAG의 검색은 에이전트의 도구 하나가 된다"고 했는데, 그게 3편에서 실제로 일어난 겁니다. 에이전트가 KB검색을 부르면, 그 도구가 Neo4j에 쿼리를 던져 관련 문서를 돌려줍니다.

에이전트가 던진 그 검색을, 실제 Neo4j Browser에서도 그대로 돌려봤습니다. 질문에 닿은 주제(온도·습도·번식)의 문서들이 그래프와 표로 나옵니다 — 에이전트가 도구로 가져온 게 바로 이 데이터예요.

도구가 검색하는 전체 지식은 이렇게 생겼습니다. 문서(Doc)들이 의미 유사도(SIMILAR_TO)로 촘촘히 엮인 망 — 22개 문서에 189개의 유사 관계예요. KB검색은 이 위에서 질문에 맞는 부분을 떠오는 거죠.

실제 Neo4j Browser 화면 그대로입니다. 왼쪽 도구 막대, 그래프/표/RAW 탭, 우측 결과 요약(노드 22 · 관계 189)까지 — 우리가 쓰는 그 웹 UI에서 직접 돌린 거예요.

지난 5부작 내내 만든 그 Neo4j가, 이제 에이전트가 필요할 때 부르는 도구로 자리 잡은 거죠. 검색이 끝이 아니라 더 큰 흐름의 한 부품이 된 셈입니다.

스스로 반복하게 두면 위험하지 않나요?

맞습니다. 도구를 스스로 반복하게 두면 무한 루프, 도구 실패, 끝나지 않는 호출 같은 문제가 따라옵니다. 그래서 안전장치가 필요합니다. 같은 호출이 연속되면 중단하고, 단계 수에 상한을 두고, 도구 오류는 크래시 대신 관찰로 넘겨 복구하게 하고, 등록 안 된 도구를 부르면 막습니다.

사실 처음 돌렸을 땐 에이전트가 같은 검색을 두 번 세 번 반복하기도 했어요. 그래서 "같은 (도구, 입력) 2연속이면 중단"과 최대 단계 상한을 넣었더니 깔끔해지더라고요. 자유롭게 반복하게 하려면, 그만큼 멈추는 규칙도 같이 줘야 합니다.

정리

3편 핵심만 정리합니다.

1. 멀티스텝 = 도구 선택→실행→관찰을 목표 달성까지 LLM이 스스로 반복합니다.
2. 도구 3개를 주면 LLM이 설명을 보고 질문에 맞는 걸 골라 연쇄 호출합니다.
3. KB검색 도구는 지난 KG-RAG 시리즈의 Neo4j(Docker 컨테이너)에 그대로 붙습니다.
4. Docker는 격리된 한 칸 — 한 줄로 켜고 끄면 깨끗, 어디서든 재현됩니다.
5. 스스로 반복하는 자유에는 안전장치(루프 상한·예외 처리·종료 조건)가 필수입니다.

도구를 여러 개 골라 쓰는 에이전트까지 왔습니다. 근데 지금은 도구가 전부 우리 코드 안에 박혀 있어요.
4편에서는 이 도구들을 MCP(Model Context Protocol)라는 표준으로 외부에 연결합니다. 코드에 박는 대신, 표준 커넥터로 도구를 줄줄이 꽂는 거죠. 실제로 claude mcp list로 연결된 도구들을 직접 확인해봅니다. ㅎㅎ