Anthropic \"Writing effective tools for agents — with agents\" 가이드

TL;DR

Anthropic은 Model Context Protocol(MCP)을 통해 LLM 에이전트용 도구를 만들고 개선하는 방법을 보여주는 단계별 가이드를 발표했습니다. 이 가이드는 Claude Code를 사용하여 도구 구현을 프로토타이핑하고, 평가하며, 자동으로 개선하는 방법을 다룹니다. 이 가이드는 다섯 가지 실용적인 원칙(도구 선택, 네임스페이싱, 의미 있는 컨텍스트 반환, 토큰 효율적인 응답, 프롬프트 엔지니어링 사양)을 정리했으며, 이는 에이전트 성능을 지속적으로 향상시킵니다.

가이드 개요

이 가이드는 개발자가 에이전트와 협력하여 에이전트 AI 시스템의 효과적인 표면적을 확장하는 고품질 도구를 구축하는 방법을 설명합니다. 프로토타입 구축, 종합 평가, 에이전트 지원 개선의 세 가지 작업 흐름 단계를 다루며, Anthropic의 내부 실험에서 도출된 간결한 설계 원칙을 제시합니다.

1. 프로토타입 구축

주요 작업

  • 로컬 MCP 서버 또는 Desktop 확장(DXT)을 설정하고 Claude Code(claude mcp add <name> <command> …) 또는 Claude Desktop 앱의 설정 → 개발자/확장 메뉴를 통해 연결합니다.
  • 도구가 의존하는 라이브러리, API 또는 MCP SDK에 대한 LLM 친화적인 문서(예: llms.txt 파일)를 제공합니다.
  • 수동으로 테스트하고 사용자 피드백을 수집하여 공식 평가 전에 거친 부분을 발견합니다.

중요성

실습 기반 프로토타이핑은 에이전트가 어떤 도구 인터페이스를 사용하기 편리하게 느끼는지 보여주며, 개발자가 전체 평가에 착수하기 전에 반복할 수 있게 합니다.

2. 체계적인 평가 실행

현실적인 작업 생성

  • Claude Code를 사용하여 실제 시나리오(예: 다단계 회의 일정 조정, 로그 분석, 유지 제안 생성)에 기반한 수십 개의 프롬프트-응답 쌍을 생성합니다.
  • 지나치게 단순한 프롬프트는 피하세요. 강력한 작업은 여러 도구 호출과 현실적인 데이터 소스를 요구해야 합니다.

평가 실행

  • 각 작업에 대해 LLM API 호출과 도구 호출을 번갈아 수행하는 에이전트 루프(while 루프)를 구현합니다.
  • 시스템 프롬프트에 추론 및 피드백 블록을 포함하여 에이전트가 도구 호출 전에 체인 오브 thought(CoT)를 생성하도록 합니다.
  • Claude에서 인터리브드 사고를 활성화하여 내부 추론을 자동으로 표시합니다.

수집할 지표

  • 검증 가능한 실제 데이터에 대한 최상위 정확도.
  • 런타임, 도구 호출 수, 총 토큰 소비량, 오류율.
  • 중복 호출이나 페이지네이션 필요성을 식별하기 위한 도구 호출 패턴 분포.

에이전트와 결과 분석

  • 에이전트의 CoT 및 피드백을 검토하여 모호한 설명, 비효율적인 구현 또는 혼란스러운 스키마를 찾습니다.
  • 원시 트랜스크립트(도구 호출 및 응답)를 검토하여 숨겨진 실패 모드를 찾습니다.
  • 관찰된 오류 패턴(예: 잘못된 매개변수 값)을 사용하여 도구 사양을 개선합니다.

3. 에이전트와 협력하여 개선

  • 평가 트랜스크립트를 연결하여 Claude Code에 제공합니다. Claude는 리팩토링을 제안하고, 불일치를 해결하며, 업데이트된 도구 정의를 생성할 수 있습니다.
  • 보류된 테스트 세트에서 성능이 안정될 때까지 수정된 도구에 대해 평가를 반복적으로 다시 실행합니다.
  • Anthropic은 Claude가 생성한 개선 사항이 수동으로 작성된 "전문가" 구현을 종종 능가한다는 것을 발견했습니다.

4. 효과적인 도구 작성 원칙

4.1 올바른 도구 선택

  • 기존 API의 얇은 래퍼보다 영향력이 크고 작업별 특화된 도구를 우선시합니다.
  • 에이전트가 필요한 데이터만 반환하는 도구를 설계합니다(예: list_contacts 대신 search_contacts).
  • 가능하면 관련 작업을 단일 도구로 통합합니다(예: schedule_event는 가용성을 찾고 이벤트를 생성).

4.2 도구 네임스페이스를 명확히 지정

  • 일관된 접두사 또는 접미사(예: asana_search, jira_search)를 사용하여 기능 도메인을 구분합니다.
  • 적절한 네임스페이싱은 로드되는 도구 설명 수를 줄이고, 컨텍스트 부하를 낮추며, 우발적인 오용을 최소화합니다.

4.3 의미 있는 컨텍스트 반환

  • 불투명한 식별자(uuid) 대신 신호가 강한 필드(name, image_url, file_type)를 출력합니다.
  • 기술적 ID가 필요한 경우 사람이 읽을 수 있는 별칭 또는 간단한 숫자 인덱스를 제공합니다.
  • response_format 열거형(예: concise vs. detailed)을 제공하여 에이전트가 필요에 따라 토큰을 적게 사용하거나 더 풍부한 페이로드를 요청할 수 있게 합니다.

4.4 토큰 효율성 최적화

  • 페이지네이션, 범위 선택, 필터링 또는 합리적인 기본값으로 잘림을 구현합니다(Claude Code는 도구 응답을 25k 토큰으로 제한).
  • 오류 메시지를 난해하게 만들지 말고 실행 가능하게 작성하여 에이전트가 수정된 입력으로 안내되도록 합니다.
  • 예: 잘린 응답은 상세한 응답에 비해 약 ⅔의 토큰을 절약하면서도 후속 작업을 가능하게 합니다.

4.5 도구 설명 프롬프트 엔지니어링

  • 새 직원에게 브리핑하듯 설명을 작성합니다: 명시적 매개변수 이름, 명확한 입력/출력 계약, 구체적인 예시.
  • 모호한 이름(user) 대신 정확한 이름(user_id)을 사용합니다.
  • 작은 문구 변경도 큰 성능 향상을 가져올 수 있습니다. Claude Sonnet 3.5는 정밀한 설명 개선 후 SWE-bench에서 최첨단 결과를 달성했습니다.

5. 향후 전망

Anthropic은 에이전트용 도구를 구축하려면 결정론적 소프트웨어 계약에서 비결정론적, 에이전트 중심 설계로 전환해야 한다고 강조합니다. 프로토타입 → 평가 → 에이전트 주도 개선을 반복함으로써 개발자는 LLM 에이전트에게 "사용하기 편리한" 도구가 무엇인지 체계적으로 발견할 수 있습니다. MCP 프로토콜과 기본 LLM이 진화함에 따라, 이 평가 중심 방법론은 점점 더 강력해지는 에이전트와 도구 생태계를 정렬하는 데 필수적으로 유지될 것입니다.

참고 자료 및 리소스

Sources