에이전트 도구 호출 모범 사례: 에이전트가 잘못된 도구를 선택하는 이유
에이전트 도구 호출 모범 사례는 작동하는 데모와 프로덕션에서 조용히 잘못된 도구를 호출하는 에이전트 사이의 차이를 만듭니다. Anthropic의 엔지니어링 팀은 단일 재작성된 설명이 하나의 도구 결과를 206 토큰에서 72 토큰으로 줄이는 것을 측정했으며, Claude Code는 이제 모든 도구 응답을 25,000 토큰으로 제한합니다. 왜냐하면 이 문제는 실제이기 때문입니다. 에이전트는 네 가지 방식으로 실패합니다: 잘못된 도구, 잘못된 인자, 무한 루프, 토큰 누출. 각 문제마다 이번 주에 적용할 수 있는 해결책이 있습니다.
주요 내용:
- 에이전트 도구 호출은 정확히 네 가지 방식으로 실패합니다: 잘못된 도구 선택, 잘못된 인자 전달, 무한 루프, 토큰 누출.
- 도구 설명은 모델이 도구 선택 시점에 보는 유일한 지시사항이므로, 대부분의 도구 선택 오류를 수정합니다.
- 평탄한 구조의 작업 지향 스키마와 검증된 입력은 대부분의 인자 전달 오류를 제거합니다.
- 간결한 도구 응답과 모든 변경에 대한 평가 루프는 토큰 비용과 회귀를 측정 가능하게 유지합니다.
왜 에이전트 도구 호출은 프로덕션에서 실패하나요?
에이전트 도구 호출은 네 가지 방식으로 실패합니다: 모델이 잘못된 도구를 선택하거나, 잘못된 인자를 작성하거나, 무한 루프에 빠지거나, 비대한 응답을 통해 토큰을 누출합니다. 각 실패는 호출 루프의 다른 단계에서 발생하므로, 수정 순서가 중요합니다. 잘못된 도구 선택이 이후의 모든 단계를 망치기 때문에 선택 단계부터 시작하세요.
한눈에 보는 완전한 처방:
이 순서대로 진행하세요. 실천 방법 1과 2는 오후 정도면 완료되며, 현재 보이는 대부분의 도구 선택 오류와 인자 전달 오류를 제거합니다. 도구 설명은 문서가 아닙니다. 이는 모델이 도구 선택 시점에 받는 유일한 지시사항입니다.
1단계: 모델이 실제로 사용할 수 있도록 도구를 설계하기
에이전트 도구 호출에서 가장 저렴한 신뢰성 향상은 프롬프트나 모델 선택이 아니라 도구 정의에 있습니다. 모델은 API 문서나 README를 읽지 않습니다. 도구의 이름, 설명 문자열, JSON 스키마만 보고 이 세 가지만으로 결정합니다. 이 세 가지를 올바르게 설정하면 다른 것을 건드리기 전에 선택 정확도가 향상됩니다.
실천 방법 1: 모델이 실행할 수 있도록 설명 작성하기
도구 설명을 API 문서가 아닌 모델을 위한 지시사항으로 작성하세요. 인간 개발자를 만족시키는 설명("사용자 엔드포인트를 위한 REST 래퍼")은 모델에게 결정할 것을 주지 않습니다. Anthropic의 도구 작성 가이드와 도구 정의 모범 사례 모두 동일한 패턴을 제시합니다: 도구를 언제 사용할지, 무엇을 반환하는지, 언제 사용하지 말아야 하는지를 명시하세요.
여기서 두 가지 규칙이 대부분의 일을 합니다. 첫째, 의미가 명확하도록 매개변수 이름을 지으세요: user_id, 절대 user나 id가 아닌 이유는 user라는 이름이 모델을 UUID가 들어가야 할 자리에 이름이나 이메일을 전달하도록 유도하기 때문입니다. 둘째, 제외 사항을 명시적으로 명시하세요. "사용자 검색에는 사용하지 마세요"는 양의 설명보다 훨씬 더 많은 도구 선택 오류를 방지합니다. 왜냐하면 모델은 단일의 명확하게 경계지어진 도구를 오해하기보다는 겹치는 도구를 혼동하기 훨씬 더 자주 하기 때문입니다. 이러한 정의가 OpenAI, Anthropic, Google API에 어떻게 도달하는지 공급자 수준의 메커니즘에 대해서는 다중 공급자 함수 호출 가이드를 참조하세요.
실천 방법 2: 스키마를 평탄하고 작업 지향적으로 유지하기
입력 스키마를 평탄하게 유지하되, 작업에 실제로 필요한 모든 필드만 포함하고 불필요한 필드는 제외하세요. 선택적 분기가 있는 중첩 객체는 인자 전달 오류의 온상입니다: 모델은 예제를 본 적 없는 구조를 추론해야 하기 때문입니다. OpenAI 함수 호출 가이드는 임의의 JSON 스키마를 허용하지만, 허용적이라는 것이 신뢰할 수 있다는 뜻은 아닙니다.
작업에 맞게 평탄화하세요:
값의 범위가 정해진 모든 필드에서는 열거형이 자유 텍스트를 능가합니다. 필수 배열은 선택적인 모든 것을 능가합니다. 모델이 거의 항상 필요로 하는 필드가 있다면, API에서 선택적으로 호출하더라도 도구 스키마에서 필수로 설정하세요. 당신은 API를 반영하고 있지 않습니다. 특정 모델이 올바르게 채울 수 있는 표면을 설계하고 있습니다.
2단계: 도구 자체가 아니라 도구 세트를 관리하기
에이전트가 한 줌 이상의 도구를 가지면 개별 도구의 품질만으로는 충분하지 않습니다. 왜냐하면 선택 오류가 모델이 읽는 목록의 크기에 따라 증가하기 때문입니다.
실천 방법 3: 다단계 API 시퀀스를 원자적 도구로 래핑하기
고정된 API 호출 시퀀스를 하나의 원자적 도구로 통합하세요. Anthropic의 엔지니어링 글에서는 schedule_event와 get_customer_context를 모델로 사용합니다: 전체 작업을 수행하는 하나의 호출이 에이전트가 매번 올바르게 연결해야 하는 세 개의 호출보다 낫습니다. 체인의 각 링크는 모델이 정지하거나, 잘못 재시도하거나, 루프할 수 있는 또 다른 턴입니다.
경험상의 규칙: 모델이 항상 A 다음에 B를 호출해야 한다면, A와 B는 두 가지 모습을 한 하나의 도구입니다.
실천 방법 4: 도구를 동적으로 네임스페이싱, 프루닝, 필터링하기
모든 도구 이름에 네임스페이싱을 적용하고 각 에이전트에는 현재 작업에 필요한 도구의 부분집합만 표시하세요. 일반적인 이름은 두 개의 통합을 연결하는 순간 충돌합니다. 두 개의 MCP 서버가 모두 search라는 도구를 노출하는 에이전트를 상상해보세요: 두 개의 동일한 동사, 구별할 방법이 없습니다. Anthropic은 접두사 네임스페이싱으로부터 측정 가능한 평가 개선을 문서화했습니다.
프루닝은 네이밍만큼 중요합니다. 지원 에이전트가 암호 질문에 답할 때 결제 도구를 로드할 필요가 없습니다. 플래너가 작업을 필요한 도구만 로드하는 워커에게 라우팅하는 플래너-워커 패턴이 표준 해결책입니다; LangGraph의 동적 도구 로딩 방법서는 구현 과정을 설명합니다. 너무 많은 도구의 기준은 무엇인가요? 에이전트당 5-10개를 법칙이 아닌 작업 범위로 생각하세요: 정확도는 목록이 커질수록 떨어지며, 해결책은 더 큰 모델이 아니라 필터링입니다. 라우팅 및 필터링 계층 자체를 선택하고 있다면, 최고의 함수 호출 라이브러리 모음에서 옵션을 비교하세요.
3단계: 반환되는 것과 나가는 것 제어하기
루프는 양방향으로 작동하지만, 대부분의 팀은 아웃바운드 절반만 엔지니어링합니다. 도구가 반환하는 것은 얼마나 많은 컨텍스트 윈도우가 다음 턴에 남는지를 결정하고, 검증이 거부하는 것은 모델이 실수에서 배우는지 아니면 반복하는지를 결정합니다.
실천 방법 5: 간결하고 높은 신호 결과 반환하기
모델이 작용할 수 있는 가장 작은 결과를 반환하되, 원시 ID 대신 사람이 읽을 수 있는 식별자를 사용하세요. Anthropic의 엔지니어링 글은 기본 결과가 206 토큰을 실행한 도구를 문서화했습니다; 간결한 response_format 설정은 동일한 결과를 72 토큰으로 줄였으며, 약 1/3 크기입니다. 이를 작업당 수십 번의 호출로 곱하면 에이전트가 완료되는지 여부를 결정합니다.
동일한 출처의 두 가지 추가 세부 사항: Anthropic은 도구 정의에 response_format 열거형(상세 대 간결)을 지원하므로, 소방호를 파싱하지 않고도 원하는 형태를 선언할 수 있습니다. 그리고 Claude Code는 도구 응답을 25,000 토큰으로 제한하며, 이는 어느 경우든 비대한 결과를 자르는 확정 한계입니다. Anthropic은 또한 그들의 발견으로서, UUID를 의미론적 이름으로 해석하면 검색 환각을 현저히 줄였다고 보고했으며, 이것이 위의 "이후" 페이로드가 "Dana Kim"이라고 하고 c9a1...f2가 아닌 이유입니다. 비대한 응답도 비용 문제입니다; 전체 그림을 보려면 LLM API 비용을 줄이는 가이드를 참조하세요.
실천 방법 6: 모든 호출을 검증하고 오류가 모델을 가르치도록 하기
모든 도구 호출을 서버측에서 검증하고 수정 사항을 포함하는 오류를 반환하세요. Martin Fowler의 함수 호출 글은 이를 직설적으로 표현했습니다: 모델의 출력을 절대 신뢰하지 마세요. 열거형이 들어가야 할 자리에 문자열을 전달하고 존재하지 않는 ID를 발명할 것입니다.
오류 문자열이 전부입니다. 비교해보세요:
도구가 반환하는 모든 검증 오류는 모델의 다음 시도를 위해 작성하는 프롬프트입니다. 제약 조건의 이름을 지정하고 수정 도구를 가리키는 오류는 재시도 루프를 원샷 복구로 변환합니다. 이것은 또한 당신의 첫 번째 보안 방어선입니다; 우리의 LLM 가드레일 가이드는 이를 깊이 있게 다룹니다.
4단계: 안전하게 만들고 측정 가능하게 만드는 방법은?
...