4장 · 에이전트 ② 웹검색 — 절 목차01. LLM이 모르는 것 학습이 끝난 시점 이후의 세상 02. 검색 도구 붙이기 키가 필요 없는 DuckDuckGo 03. 따라하기 검색어를 LLM이 직접 만들게 하기 04. 도구가 여러 개일 때 모델은 무엇을 보고 고르나 05. ReAct 생각 행동 관찰의 반복 06. 따라하기 두 도구를 함께 쥐여 주기 07. 따라하기 for 루프로 에이전트 직접 만들기 08. 종료 조건 무한 반복과 비용 폭탄 막기 09. 검색은 실패한다 끊겨도 멈추지 않게 10. 정리 체크리스트

도구가 여러 개일 때 모델은 무엇을 보고 고르나

한 줄 요약

모델이 보는 것은 도구 명세와 시스템 지시 뿐입니다. 그래서 도구가 늘어날수록 독스트링에 경계선을 긋는 일이 중요해집니다. 8장에서 도구를 여러 에이전트에 나눠 주는 이유도 여기서 나옵니다.

1. 모델이 받는 것

도구 두 개를 넘기면 모델에게는 이런 목록이 전달됩니다.

[
  {
    "name": "get_product_info",
    "description": "승승장구몰이 파는 상품의 가격·평점·카테고리를 조회한다.
                    상품명 일부만 넣어도 된다. 예: '스마트워치'",
    "parameters": { "properties": { "product_name": {"type": "STRING"} } }
  },
  {
    "name": "search_web",
    "description": "인터넷에서 최신 정보를 검색한다.
                    시장 동향·경쟁 제품처럼 사내 데이터에 없는 내용에 쓴다.",
    "parameters": { "properties": { "query": {"type": "STRING"} } }
  }
]

모델은 이 목록과 사용자 질문만 보고 고릅니다. 함수 본문은 여전히 못 봅니다.

2. 고르는 기준은 '설명이 얼마나 맞는가'

질문에 따라 어떤 도구 설명이 더 적합한지가 달라진다

"승승장구몰이 파는" 과 "사내 데이터에 없는" 이 경계선을 그었습니다.

3. 경계선을 지우면 어떻게 되나

독스트링을 이렇게 바꿔 보세요.

직접 고쳐 보기 — agentic_ai/code/ch04_web_agent.py 를 열어 아래처럼 바꾸거나 덧붙인 뒤 다시 실행하세요. 확인이 끝나면 원래 독스트링으로 되돌리세요.

def get_product_info(product_name: str) -> str:
    """상품 정보를 조회한다."""           # ← 경계선 없음

def search_web(query: str) -> str:
    """검색한다."""                       # ← 경계선 없음

그리고 "승승 스마트워치 Fit 5는 얼마인가요?" 를 물어 보세요. 모델이 웹에서 찾으려 할 수 있습니다. 승승장구몰은 가상의 쇼핑몰이라 당연히 안 나오고, 엉뚱한 답이 나옵니다.

직접 해 보세요. 독스트링을 지웠다 넣었다 하며 모델의 선택이 바뀌는 걸 확인하는 것이, 이 개념을 몸에 익히는 가장 빠른 길입니다.

4. 시스템 지시로 한 번 더 못 박기

독스트링만으로 부족할 때, 시스템 지시에서 다시 정리해 줍니다.

아래는 code/ch04_web_agent.py 의 일부입니다 — 위에서 이미 붙여 넣었으니 다시 넣지 마세요.

SYSTEM = (
    "너는 승승장구몰의 상품기획 담당자다. "
    "자사 상품 정보는 get_product_info 로, 시장 동향처럼 바깥 정보는 search_web 으로 확인한다. "
    "확인한 내용만 근거로, 한국어로 간결하게 정리해 답한다."
)

도구 이름을 직접 언급하며 역할을 나눴습니다. 독스트링과 시스템 지시가 같은 이야기를 두 번 하는 셈인데, 일부러 그렇게 합니다.

어디에 적나	성격
독스트링	그 도구 자체의 설명. 도구를 재사용해도 따라간다
시스템 지시	이 에이전트의 업무 규칙. 에이전트마다 다르다

8장에서 이 구분이 실제로 쓰입니다. 같은 search_web 도구를 여러 에이전트가 쓰는데, 시스템 지시는 각자 다릅니다. 독스트링은 도구에, 업무 규칙은 에이전트에 붙는 것이죠.

5. 도구가 많아지면 정확도가 떨어집니다

도구를 2개, 5개, 10개로 늘리면 어떻게 될까요?

도구 2개  →  대체로 잘 고른다
도구 5개  →  가끔 헷갈린다
도구 10개 →  자주 헷갈린다. 비슷한 도구끼리 섞인다
도구 20개 →  명세만으로 토큰을 크게 먹는다

이유는 단순합니다.

설명이 비슷하면 도구를 혼동합니다. get_product_info 와 get_item_detail 이 함께 있으면 모델도 헷갈립니다.
명세 자체도 토큰을 사용합니다. 도구 20개면 호출할 때마다 20개 명세를 다 보냅니다.
판단할 것이 많아집니다. 사람도 선택지가 많으면 결정이 느려지고 실수하기 쉽습니다.

6. 그래서 8장이 있습니다

이 문제의 해결책이 멀티에이전트입니다.

도구를 나눠 맡기면 각자가 고를 것이 하나로 줄어든다 — 8장 멀티에이전트의 이유

여기 세 명은 8장 팀원 넷 중 셋입니다 — 8장에서는 여기에 주문담당(3장에서 만든 get_order_status)까지 붙어 넷이 됩니다. 이름은 1장 3절 조립도에서 고정한 그대로입니다.

나누면 각자의 판단이 쉬워집니다. 도구가 하나뿐인 담당자는 고를 것이 없으니까요.

그리고 어디서 틀렸는지 찾기도 쉬워집니다. "규정담당이 잘못 보고했다"고 짚을 수 있으니까요.

이 과정을 통틀어 8장이 "역할 분리"를 다루는 이유가 여기서 나옵니다. 멀티에이전트는 멋있어서 쓰는 게 아니라, 도구를 한 명에게 몰면 판단이 부정확해지기 때문에 쓰는 것입니다.

7. 도구를 설계할 때의 원칙

지금 정리해 두면 8장까지 계속 씁니다.

원칙	뜻
겹치지 않게	두 도구가 같은 일을 하면 반드시 헷갈린다
경계선을 적어라	"이건 이럴 때 안 쓴다"까지
하나에 하나	도구 하나가 여러 일을 하면 인자가 복잡해진다
개수를 줄여라	5~7개를 넘으면 나눌 때가 된 것
이름에 기능을 드러내라	`search_web` ✓ / `tool2` ✗

예측해 보기

다음 절로 넘어가기 전에 적어 보세요.

도구 두 개를 쥐여 준 상태에서 "승승 스마트워치 Fit 5는 얼마인가요? 요즘 시장 가격대와 비교하면 어느 수준인가요?" 를 물으면, 모델은 두 도구를 어떤 순서로 쓸까요? 그리고 왜 그 순서일까요?

순서: ______
이유: ______

핵심 정리

모델은 도구 명세와 시스템 지시만 보고 고릅니다. 함수 본문은 못 봅니다.
독스트링의 경계선이 선택을 좌우합니다 — "승승장구몰이 파는", "사내 데이터에 없는".
독스트링은 도구에, 업무 규칙은 시스템 지시에 적습니다. 같은 도구를 여러 에이전트가 쓸 수 있기 때문입니다.
도구가 많아지면 정확도가 떨어집니다 — 설명이 비슷하면 헷갈리고, 명세 자체도 토큰을 사용하고, 판단할 것이 늘어납니다.
해결책이 8장 멀티에이전트입니다. 도구를 나눠 주면 각자의 판단이 쉬워집니다.
도구 설계 원칙: 겹치지 않게 · 경계선을 적어라 · 하나에 하나 · 개수를 줄여라 · 이름에 기능을 드러내라.