3부 12장. 검색, 파일, 브라우저, 코드 실행 도구 연결하기
도구를 붙이는 순간 에이전트는 갑자기 현실감이 생긴다. 어제까지는 그럴듯한 설명만 하던 시스템이, 오늘부터는 웹을 찾아보고, 문서를 뒤지고, 브라우저를 열고, 코드를 실행한다. 독자 입장에서는 여기서 기대가 커진다. 이제 진짜 일을 하겠구나.
하지만 설계자 입장에서는 반대로 긴장이 시작된다. 바로 이 지점부터 에이전트는 말이 아니라 행동으로 평가되기 때문이다. 검색 도구는 최신 정보를 가져와야 하고, 파일 도구는 필요한 문맥만 정확히 꺼내야 하며, 브라우저 도구는 페이지 변화에 흔들리지 않아야 하고, 코드 실행 도구는 강력한 만큼 반드시 격리되어야 한다. OpenAI 계열 도구 문서도 이런 차이를 전제로 웹 검색, 파일 검색, 코드 실행, 셸, 컴퓨터 사용 같은 도구를 호스티드 도구와 로컬 런타임 도구로 나누어 설명한다.1
지난 장에서 우리는 Tool Calling이 계약이라는 사실을 배웠다. 이번 장에서는 그 계약을 실제 공구에 연결해 본다. 핵심 질문은 하나다. 검색, 파일, 브라우저, 코드 실행이라는 서로 다른 도구를 어떤 입력과 출력으로 감싸고, 어디에서 실패를 막아야 하는가.
도구는 모두 함수처럼 보이지만, 성격은 전혀 다르다
겉으로만 보면 네 종류의 도구는 비슷하다. 이름이 있고, 입력이 있고, 결과가 돌아온다. 그래서 처음에는 같은 방식으로 연결해도 될 것처럼 느껴진다. 하지만 실무에서는 이 단순화가 곧바로 문제를 만든다.
검색 도구는 모르는 사실을 찾는 데 강하지만, 결과가 본질적으로 불완전하다. 웹은 넓고, 검색엔진은 요약만 준다. 파일 도구는 우리 문서에 강하지만, 색인 상태와 권한, 인용 방식이 중요하다. 브라우저 도구는 동적인 웹사이트를 다룰 수 있지만 느리고 깨지기 쉽다. 코드 실행 도구는 계산과 변환에 매우 강력하지만, 잘못 연결하면 작은 실수가 바로 큰 사고가 된다.
이 차이를 무시하고 모든 도구를 한 바구니에 넣으면 모델은 비슷한 것들 사이에서 자꾸 헤맨다. 반대로 도구의 성격을 먼저 구분하면 설계가 쉬워진다.
검색은 찾는 도구다. 파일은 읽고 근거를 붙이는 도구다. 브라우저는 상호작용하는 도구다. 코드 실행은 계산하고 변환하고 생성하는 도구다. 이 한 줄 구분만 분명해도 도구 설명, 권한, 재시도 정책이 훨씬 또렷해진다.
연결 전에 먼저 정해야 할 세 가지
도구를 붙이기 전에, 프레임워크보다 먼저 정해야 할 것이 있다.
이 도구는 무엇을 잘하고, 무엇은 하지 못하는가
입력은 어떤 칸으로 쪼개고, 결과는 어떤 구조로 돌려줄 것인가
실패했을 때 자동 복구할 것인가, 다시 물을 것인가, 사람에게 넘길 것인가
이 세 가지를 정하지 않으면 연결은 되더라도 운영은 되지 않는다. 많은 팀이 도구를 붙이는 데는 성공하지만, 왜 같은 질문에 호출이 들쑥날쑥한지, 왜 쓸데없는 재시도가 생기는지, 왜 실패 로그를 읽어도 원인을 찾기 어려운지에서 막힌다. 이유는 대부분 여기 있다. 도구 자체보다 계약과 운영 규칙이 먼저여야 한다.
검색 도구 연결하기
검색 도구는 에이전트에게 바깥세상의 창문을 달아 준다. 다만 창문이라고 해서 세상이 자동으로 정리돼 들어오지는 않는다. 바람도 들어오고, 소음도 들어오고, 광고지도 날아들 수 있다. 그래서 검색 도구는 연결 자체보다 검색 결과를 어떻게 압축해 모델에게 먹일지가 더 중요하다.
검색에는 크게 두 갈래가 있다. 모델이 기본 제공하는 웹 검색을 쓰는 방식과, 외부 검색 API를 도구로 붙이는 방식이다. 전자는 빠르고 통합이 간단한 대신 세부 제어가 적다. 후자는 한 번 더 왕복해야 하지만 검색어, 도메인 제한, 결과 수, 추출 방식을 더 섬세하게 통제할 수 있다.2
실무에서는 보통 검색을 한 덩어리 도구로 만들지 않는 편이 낫다. web_search와 fetch_page 또는 extract_page를 분리하는 식이 좋다. 먼저 넓게 찾고, 그다음 필요한 페이지를 좁게 읽게 하는 것이다. 공항에서 사람을 찾을 때도 방송부터 하는 사람은 없다. 먼저 도착층을 보고, 게이트를 보고, 마지막에 이름표를 확인한다. 검색도 비슷하다.
검색 도구의 입력 스키마는 단순할수록 좋다. 보통은 query, max_results, allowed_domains, freshness_days 정도면 충분하다. 여기서 중요한 것은 필드 이름이 애매하지 않아야 한다는 점이다. date보다 published_after_iso8601이 낫고, site보다 allowed_domains가 낫다. 검색은 작은 애매함이 바로 엉뚱한 결과로 이어진다.
출력 스키마도 마찬가지다. 검색 결과를 그대로 긴 텍스트로 돌려주면 모델은 중요한 것을 찾느라 또 힘을 쓴다. 차라리 항목별로 title, url, snippet, published_at, source_type 정도로 정리해 주는 편이 낫다. 검색 결과는 길수록 좋은 것이 아니라, 다음 판단에 필요한 최소 단위로 잘려 있을수록 좋다.
검색 도구에서 자주 터지는 실패는 세 가지다. 첫째는 빈 결과다. 이때는 실패라고 바로 단정하지 말고, 질의를 재작성할 여지를 남겨야 한다. 둘째는 낡은 결과다. 뉴스나 가격처럼 시점이 중요한 정보는 최신성 검사를 붙여야 한다. 셋째는 중복 검색이다. 같은 세션에서 거의 같은 검색을 여러 번 날리면 비용만 늘고 답은 별로 나아지지 않는다. 따라서 검색 전에는 캐시를 확인하고, 검색 후에는 결과를 짧게 요약해 작업 상태에 남겨 두는 편이 좋다.8
검색 도구는 사용성이 좋아 보이는 만큼 남용되기 쉽다. 그래서 가장 먼저 가르쳐야 하는 습관은 이것이다. 모르면 검색해라가 아니라, 최신성이 필요할 때만 검색해라. 그러면 속도와 비용, 정확도 균형이 한결 좋아진다.
파일 도구 연결하기
파일 도구는 에이전트가 사내 문서나 사용자 업로드 자료를 다룰 때 핵심이 된다. 여기서 중요한 것은 파일을 읽는다는 말이 실제로는 두 가지를 뜻한다는 점이다. 하나는 특정 파일을 직접 여는 것이고, 다른 하나는 여러 파일 가운데 관련 부분을 찾아오는 것이다.
후자가 바로 파일 검색이다. 최근 에이전트 플랫폼들이 파일 검색을 벡터 저장소나 자체 색인과 연결하는 이유도 여기에 있다. 파일 전체를 통째로 모델에게 밀어 넣는 대신, 관련된 조각만 찾아 넣어야 정확도와 비용이 모두 좋아진다. Microsoft Foundry 계열 문서도 파일 업로드, 벡터 저장소 생성, 파일 검색 도구 연결을 한 흐름으로 설명하며, 문서 소유권과 저장소 통제를 유지하는 점을 강조한다.3
실무에서 파일 도구는 최소한 세 종류로 나누는 편이 안전하다. search_documents, read_file_segment, write_file 또는 save_artifact처럼 역할을 나누는 것이다. 특히 읽기와 쓰기를 한 도구에 섞어 넣으면 설명도 흐려지고 권한 경계도 약해진다.
파일 검색 도구의 입력에는 보통 query, source_ids, filters, top_k가 들어간다. 여기서 filters는 생각보다 중요하다. 문서 종류, 작성 부서, 날짜 범위, 보안 등급 같은 메타데이터를 넣을 수 있어야 같은 질문이라도 맥락에 맞는 자료만 찾을 수 있다. 예를 들어 정책 문서를 찾는데 회의록까지 같이 나오면 검색 품질은 급격히 떨어진다.
출력은 chunks 배열로 두고, 각 조각에 document_id, filename, page, text, score, citation_label을 붙이는 방식이 좋다. 이유는 간단하다. 파일 도구의 핵심 가치는 답 자체보다 근거에 있기 때문이다. 사용자가 신뢰하는 것은 에이전트의 문장이 아니라, 어느 문서 몇 페이지에서 가져왔는지까지 이어지는 추적 가능성이다.
파일 도구에서 자주 생기는 실패도 검색과는 조금 다르다. 업로드는 끝났지만 색인이 아직 안 된 경우가 있고, 최신 버전 파일이 올라왔는데 오래된 색인이 남아 있는 경우가 있다. 권한은 있는데 페이지 정보가 누락된 결과가 나오기도 한다. PDF나 스캔본처럼 텍스트 추출 품질이 낮은 경우도 흔하다. 따라서 파일 검색 결과에는 항상 신뢰도와 출처를 함께 실어야 하며, 낮은 신뢰도의 결과를 바탕으로 단정적인 답을 하지 않도록 프롬프트와 후처리를 맞춰야 한다.
여기서 기억할 실무 감각이 하나 있다. 사용자는 파일을 읽어 달라고 말하지만, 실제로 원하는 것은 대부분 파일 전체가 아니라 답에 필요한 단락이다. 좋은 파일 도구는 책장을 다 들이밀지 않고, 필요한 쪽수를 펴서 손가락으로 짚어 준다.
브라우저 도구 연결하기
브라우저 도구는 도구 상자 안의 모험가다. 검색으로는 안 보이고, 단순 HTTP 요청으로는 잘 안 열리고, 자바스크립트가 페이지를 늦게 그리거나 버튼을 눌러야 내용이 나오는 곳에서 진가를 발휘한다. 하지만 그만큼 변덕도 심하다.
브라우저 도구를 붙일 때는 먼저 질문해야 한다. 정말 브라우저가 필요한가. 많은 경우 검색과 페이지 추출만으로 충분하다. 브라우저는 API가 없고, 정적 추출로는 안 되고, 실제 상호작용이 필요한 사이트에서만 꺼내는 편이 좋다.
브라우저 연결 방식은 크게 두 방향이 있다. 하나는 open, snapshot, click, fill처럼 낮은 수준의 액션을 여러 개 노출하는 방식이다. 다른 하나는 시작 URL과 목표를 주면 브라우저가 알아서 여러 단계를 수행하고 구조화된 결과를 돌려주는 높은 수준의 작업형 도구다. Vercel의 agent-browser는 전자에 가깝고, 접근성 트리를 기반으로 한 스냅샷과 ref 선택자를 써서 DOM 전체보다 훨씬 적은 토큰으로 페이지를 다루게 해 준다.4 반면 Oxylabs의 Browser Agent는 목표, 시작 URL, 출력 형식, JSON 스키마를 받아 다단계 탐색과 추출을 한 번에 수행하는 후자에 가깝다.5
어느 쪽이 낫냐고 묻는다면, 정답은 없다. 대신 원칙은 있다. 페이지가 자주 바뀌고 디버깅이 중요하면 낮은 수준 도구가 낫다. 특정 비즈니스 작업을 반복 자동화하고 싶다면 높은 수준 도구가 낫다. 쉽게 말해 직접 운전할지, 택시를 부를지의 차이다.
브라우저 도구의 입력 스키마에는 보통 start_url, goal, allowed_domains, step_budget, output_format, extraction_schema가 들어간다. 여기서 step_budget은 특히 중요하다. 브라우저는 잘못하면 끝없이 돌아다닌다. 쿠키 팝업을 닫고, 로그인 버튼을 찾고, 새 탭을 열고, 다시 뒤로 가는 사이에 토큰과 시간이 순식간에 사라진다. 행동 예산이 있어야 한다.
출력은 단순한 텍스트보다 actions, final_url, observations, extracted_data, screenshots 같은 구조가 좋다. 그래야 실패했을 때 어디서 막혔는지 알 수 있다. 브라우저 도구는 결과만 보면 멀쩡해 보여도 중간 과정에서 잘못된 버튼을 눌렀을 수 있다. 흔히 실패가 조용하다. 그래서 브라우저는 특히 추적 가능한 출력이 중요하다.
브라우저에서 자주 생기는 실패는 꽤 인간적이다. 쿠키 배너를 못 닫고 얼어붙는다. 로그인 세션이 만료됐는데도 계속 다음 버튼을 찾는다. 페이지가 갱신되어 이전에 본 요소 참조가 무효가 된다. 봇 탐지에 걸려 이상한 확인 페이지로 튄다. 이런 문제를 줄이려면 브라우저 도구를 한 번의 거대한 액션으로 만들기보다 관찰과 행동을 교차하는 짧은 루프로 설계하는 편이 낫다. 먼저 스냅샷을 보고, 그다음 클릭하고, 다시 스냅샷을 보는 식이다. 사람도 낯선 사이트에서는 한 번에 열 걸음 뛰지 않는다.
코드 실행 도구 연결하기
코드 실행 도구는 에이전트를 갑자기 유능하게 만드는 비밀병기처럼 보인다. 계산도 하고, CSV도 읽고, 그래프도 그리고, 변환도 한다. 실제로 그렇다. 하지만 동시에 가장 조심해서 다뤄야 하는 도구이기도 하다.
중요한 원칙은 하나다. 모델은 코드를 제안하고, 별도의 실행 환경이 그것을 돌린다. 추론 계층과 실행 계층을 분리하는 구조가 기본이다. 코드가 실행되는 곳은 시간 제한, 메모리 제한, 네트워크 정책, 파일 접근 범위 같은 규칙으로 감싸져 있어야 한다. 최근 코드 실행 아키텍처를 다루는 자료들이 샌드박스, 컨테이너, 마이크로VM 같은 격리 환경을 반복해서 강조하는 이유도 바로 여기에 있다.6 Hugging Face의 smolagents 문서 역시 기본적으로 샌드박스 실행과 제한된 import 허용 방식을 강조한다.7
코드 실행 도구의 입력 스키마는 최소한 language, code, input_files, timeout_sec, network_mode, expected_artifacts 정도는 분리해 두는 편이 좋다. code 하나에 모든 것을 우겨 넣으면 실행 정책을 제어하기 어렵다. 예를 들어 같은 Python 코드라도 네트워크가 필요한 작업인지, 단순 계산인지에 따라 위험도가 다르다.
출력은 exit_code, stdout_tail, stderr_tail, artifacts, duration_ms, resource_usage 정도가 유용하다. 여기서 핵심은 전체 표준출력을 다 돌려주지 않는 것이다. 코드 실행은 출력이 쉽게 길어진다. 로그 수천 줄을 모델에 다시 넣는 순간, 코드보다 로그 읽기에 더 많은 비용을 쓰게 된다. 따라서 긴 출력은 파일로 저장하고, 모델에게는 마지막 일부와 요약만 보여 주는 편이 좋다.8
코드 실행에서 자주 생기는 실패는 네 부류다. 문법 오류와 런타임 오류처럼 즉시 보이는 실패가 있다. 무한 루프나 대용량 처리처럼 느리게 드러나는 실패가 있다. 네트워크나 권한 때문에 필요한 자원에 접근하지 못하는 실패도 있다. 그리고 가장 위험한 것은 성공한 것처럼 보이지만 잘못된 계산을 한 경우다. 그래서 코드 실행 도구는 단순히 실행 성공 여부만 보면 안 된다. 가능하면 기대하는 산출물 형태까지 검증해야 한다. 예를 들어 CSV 요약 작업이라면 결과 파일이 실제로 생성됐는지, 그래프라면 PNG가 나왔는지까지 확인해야 한다.
또 하나의 실무 원칙은 기본값을 보수적으로 잡는 것이다. 네트워크는 기본 차단, 쓰기 권한은 특정 경로만 허용, 장시간 실행은 백그라운드 작업으로 넘기기. 좋은 코드 실행 도구는 똑똑하게 풀어 주는 도구가 아니라, 함부로 못 하게 막아 주는 도구다.
입력과 출력 스키마는 어떻게 나누는 것이 좋은가
도구를 연결할 때 가장 많이 하는 실수는 스키마를 개발자 편의대로 만드는 것이다. 하지만 스키마는 런타임을 위한 구조이면서 동시에 모델을 위한 설명서다. 사람이 보기 편한 것과 모델이 실수하지 않는 것은 종종 다르다.
좋은 스키마에는 몇 가지 공통점이 있다. 첫째, 필드 이름이 구체적이다. amount보다 amount_cents가 낫고, date보다 start_date_iso8601이 낫다. 둘째, 한 도구에 너무 많은 모드를 몰아넣지 않는다. update_record 하나에 mode=create|update|delete를 넣는 것보다 create_record, update_record, delete_record를 나누는 편이 대개 낫다. 셋째, 자유 텍스트를 최소화한다. 자유 텍스트는 결국 모델이 의도를 몰래 끼워 넣는 통로가 되기 쉽다.9
특히 브라우저와 코드 실행 도구에서 이 문제가 심하다. 브라우저 도구에 instruction 하나만 두고 모든 행동을 맡기면 편해 보이지만, 나중에 실패 원인을 파악하기 어렵다. 코드 실행 도구도 run_anything처럼 설계하면 강력해 보이지만, 실제로는 정책과 검증 포인트를 잃어버린다.
반대로 출력 스키마는 가능한 한 다음 단계가 바로 읽을 수 있어야 한다. 검색 결과는 URL과 요약이 있어야 하고, 파일 결과는 인용 단위가 있어야 하며, 브라우저 결과는 최종 URL과 액션 로그가 있어야 하고, 코드 결과는 오류 요약과 산출물 목록이 있어야 한다. 도구 출력은 사람에게 보여 주는 보고서가 아니라, 다음 추론 단계로 건네는 부품이다.
실패 처리는 도구마다 다르게 설계해야 한다
에이전트 실패는 전통적인 소프트웨어 실패와 모양이 조금 다르다. HTTP 200이 떴는데도 결과가 틀릴 수 있고, 도구는 성공했는데 작업 전체는 실패할 수도 있다. 그래서 도구 실패를 한 종류로 묶어 다루면 안 된다.
실무에서는 실패를 네 가지 정도로 나눠 생각하면 편하다. 입력이 잘못된 경우, 일시적으로 외부 서비스가 불안정한 경우, 권한이나 정책 때문에 실행하면 안 되는 경우, 그리고 실행은 끝났지만 품질이 기준을 못 넘는 경우다. 이 분류에 따라 대응도 달라져야 한다.10
입력 오류는 무작정 재시도하면 안 된다. 대신 모델에게 오류 메시지를 돌려주고 한 번 정도 자기 수정을 시도하게 하는 편이 낫다. 반대로 타임아웃이나 일시적 5xx 오류는 짧은 지수 백오프로 재시도할 가치가 있다. 429는 보통 대기 시간을 존중해야 한다. 401이나 403은 재시도보다 운영 경보에 가깝다. 인증이 잘못된 상태에서 같은 요청을 세 번 반복하는 것은 끈기가 아니라 소음이다.10
도구 실행 래퍼에는 최소한 네 가지가 있어야 한다. 호출 전 입력 검증, 실행 시간 제한, 재시도 정책, 그리고 결과 크기 제한이다. 여기에 더해 품질 실패를 잡는 회로 차단기나 예산 제한이 있으면 좋다. 예를 들어 브라우저 도구가 다섯 번 연속 쿠키 팝업에서 막혔다면, 더 돌리는 것이 해결책일 가능성은 낮다. 그때는 멈추고 다른 경로를 찾거나 사람에게 넘겨야 한다.8
쓰기 동작이 섞인 도구라면 한 가지를 더 붙여야 한다. 바로 멱등성이다. 같은 요청이 재시도될 때 중복 발송, 중복 저장, 중복 결제가 일어나지 않도록 요청 키나 상태 체크를 둬야 한다. 에이전트는 사람이 아니라서, 실패하면 같은 버튼을 아무 생각 없이 다시 누를 수 있다.9
네 도구를 함께 쓰는 흐름은 이렇게 생긴다
실전에서는 도구가 하나만 쓰이는 경우보다 여러 도구가 이어지는 경우가 훨씬 많다. 예를 들어 경쟁사 가격 동향 보고서를 만드는 에이전트를 생각해 보자.
먼저 검색 도구가 경쟁사 이름과 공식 가격 페이지 후보를 찾는다. 이 단계의 출력은 company, candidate_url, snippet 정도면 된다. 다음으로 브라우저 도구가 그중 실제 가격 페이지를 열어 자바스크립트 렌더링 결과를 확인하고, 필요한 표를 JSON 형태로 추출한다. 여기서 출력은 final_url, pricing_rows, captured_at 같은 구조가 된다.
이후 코드 실행 도구가 여러 통화와 단위를 정규화하고, 가격 변동 그래프를 만들고, 이상치를 계산한다. 출력은 normalized_csv, chart_png, summary_stats가 된다. 마지막으로 파일 도구가 이 산출물을 보고서 저장소에 저장하고, 나중에 다시 검색할 수 있도록 메타데이터와 함께 등록한다.
중요한 것은 네 도구를 다 연결했다는 사실이 아니다. 한 도구의 출력이 다음 도구의 입력에 자연스럽게 이어지도록 스키마를 맞췄다는 점이다. 에이전트 설계는 결국 번역 작업이다. 검색 결과를 브라우저가 읽을 수 있는 형태로, 브라우저 결과를 코드 실행이 다룰 수 있는 형태로, 계산 결과를 파일 저장이 기록할 수 있는 형태로 계속 바꿔 주는 일이다.
무엇을 자동화하고, 어디서 멈출 것인가
도구를 많이 붙일수록 자율성이 높아진다. 그러나 좋은 시스템은 자율성을 높이는 데만 관심이 있지 않다. 어디서 멈출지도 같이 정한다.
검색과 파일 읽기는 대체로 자동화에 잘 맞는다. 브라우저도 읽기 중심 작업이면 꽤 자동화할 수 있다. 하지만 로그인, 제출, 구매, 삭제, 발송 같은 행동은 이야기가 달라진다. 코드 실행도 내부 분석은 자동화하기 좋지만, 외부 시스템에 쓰기를 동반하는 순간 승인 체계가 필요해진다.
이 장의 네 도구 가운데 특히 브라우저와 코드 실행은 쉽게 과신을 부른다. 눈앞에서 실제 행동이 일어나기 때문이다. 하지만 제품 수준의 에이전트는 화려한 데모보다 멈춤의 품질이 더 중요하다. 자신 있게 클릭하는 능력보다, 이 클릭은 내가 하면 안 된다고 판단하는 능력이 더 비싸다.
결국 좋은 연결은 도구가 아니라 경계에서 나온다
도구 연결을 잘한다는 말은 라이브러리를 많이 안다는 뜻이 아니다. 어떤 순간에 검색을 쓰고, 어떤 순간에 파일 검색으로 충분하며, 어떤 순간에 브라우저가 정말 필요한지, 코드 실행을 어디까지 허용할지 경계를 분명히 세우는 뜻에 가깝다.
검색 도구는 질의와 결과를 짧고 선명하게 설계해야 한다. 파일 도구는 근거와 인용을 중심으로 설계해야 한다. 브라우저 도구는 관찰과 행동을 나눠 흔들림을 줄여야 한다. 코드 실행 도구는 격리와 검증을 기본값으로 가져가야 한다.
이 네 가지를 이해하면 에이전트가 현실 세계와 만나는 장면이 더 이상 막연하지 않다. 어떤 도구가 왜 필요한지, 입력과 출력은 왜 그렇게 생겨야 하는지, 실패는 왜 도구마다 다르게 다뤄야 하는지가 손에 잡히기 시작한다.
지난 장에서 우리는 도구 호출이 계약이라는 사실을 배웠다. 이번 장에서는 그 계약이 실제 세계와 만나면 어떤 설계가 필요한지 보았다. 다음 장에서는 이 흐름을 더 넓혀, 도구를 하나씩 붙이는 수준을 넘어 MCP라는 공통 연결 규약이 왜 중요한지 살펴보겠다.
참고
3Microsoft Foundry File Search 도구 문서
6How do AI agents execute code
7Hugging Face smolagents 코드 에이전트 가이드
8Reliable tool calling patterns for AI agents
이 노트는 보도·비평·교육·연구 목적으로 작성되었습니다. 저작권 문의가 있으시면 에서 알려주세요.