AI 에이전트를 위한 효과적인 도구 작성: 앤트로픽 엔지니어링 가이드

앤트로픽은 AI 에이전트를 위한 도구를 구축하고 최적화하는 포괄적인 방법론을 도입하며, 소프트웨어 개발 패러다임을 시스템 간의 결정론적 계약에서 에이전트와 시스템 간의 비결정론적 계약으로 전환했습니다. 핵심 통찰은 도구가 LLM의 '기능성(affordances)'에 특화되어야 한다는 점입니다. 전통적인 API 유연성보다는 맥락 효율성과 의미적 명확성을 우선시해야 합니다.

에이전트 중심의 도구 개발 패러다임

전통적인 소프트웨어는 특정 입력이 항상 동일한 출력을 생성하는 결정론적 계약을 기반으로 합니다. 반면 AI 에이전트는 비결정론적입니다. 동일한 프롬프트에 대해 도구를 호출할 수도 있고, 내부 지식에 의존하거나 명확화를 요청할 수도 있습니다.

에이전트의 효과를 극대화하기 위해 개발자들은 표준 API처럼 도구를 작성하는 방식에서 벗어나, 에이전트가 전략을 성공적으로 실행할 수 있는 "표면적(surface area)"을 넓히도록 설계해야 합니다. 에이전트에게 친화적인 도구는 일반적으로 인간의 직관적인 워크플로우와 일치합니다.

도구 개발을 위한 체계적인 워크플로우

앤트로픽은 도구 성능을 개선하기 위해 프로토타이핑, 평가, 에이전트 주도 최적화의 반복 주기를 권장합니다.

1. 프로토타이핑 및 로컬 테스트

개발자는 빠른 프로토타입부터 시작해야 하며, Claude Code를 활용해 초기 구현을 생성할 수 있습니다. 한 번의 생성을 개선하기 위해 앤트로픽은 관련 SDK나 API에 대해 LLM 친화적인 문서(예: llms.txt 파일)를 제공하는 것을 제안합니다. 도구는 다음과 같은 방식으로 로컬에서 테스트할 수 있습니다:

로컬 MCP 서버: claude mcp add를 사용해 Claude Code에 연결.
데스크톱 확장 프로그램(DXT): Claude 데스크톱 앱에 통합.
직접 API 호출: Anthropic API를 사용해 프로그래밍 방식으로 테스트.

2. 평가 기반 최적화

과적합을 방지하고 실제 세계에서의 효과성을 보장하기 위해 체계적인 측정이 필요합니다. 이를 위해 다음과 같은 접근이 필요합니다:

복잡한 작업 생성: 단순한 "샌드박스" 프롬프트를 피하고, 다단계의 실제 시나리오(예: 로그를 분석해 영향을 받은 사용자를 식별하여 고객 청구 분쟁을 해결하는 것)를 활용.
검증 가능한 결과: 프롬프트에 정답 응답을 연결하거나, LLM 기반 판정기(판단자)를 사용해 검증.
프로그래밍 방식 실행: LLM API 호출과 도구 실행을 번갈아 수행하는 while 루프 내에서 평가 에이전트를 실행.
교차 사고: 도구 호출 전에 "교차 사고(interleaved thinking)" 또는 사고의 흐름(CoT) 블록을 사용해, 에이전트가 도구를 사용하지 못하거나 비효율적인 경로를 선택한 이유를 진단.

3. 에이전트 주도 개선

앤트로픽은 에이전트가 자신의 실패 기록을 분석하는 데 매우 효과적임을 발견했습니다. 평가 기록을 Claude Code에 다시 입력함으로써 개발자는 도구 구현과 설명을 자동으로 재구성하여 자기 일관성과 성능을 보장할 수 있습니다.

고성능 도구를 위한 핵심 원칙

전략적 도구 선택

더 많은 도구가 반드시 더 나은 성능을 의미하지는 않습니다. 에이전트는 전통적인 소프트웨어에 비해 제한된 맥락 창을 가지고 있습니다.

강제적 도구 회피: 모든 데이터를 반환하는 list_contacts 도구(에이전트가 토큰 단위로 읽도록 강제) 대신 search_contacts 도구를 구현.
기능 통합: 여러 개의 별도 API 호출을 하나의 고수준 도구로 통합. 예를 들어 list_users와 create_event 도구를 별도로 두는 대신, 가용성과 스케줄링을 한 번의 호출로 처리하는 schedule_event 도구를 만듭니다.

네임스페이싱 및 경계 정의

에이전트가 여러 MCP 서버를 통해 수백 개의 도구에 접근할 때 혼동을 방지하기 위해 네임스페이싱(공통 접두사 아래 관련 도구 그룹화)을 사용해야 합니다.

예시: asana_projects_search와 jira_projects_search를 사용하면 에이전트가 서로 다른 서비스 간의 경계를 명확히 구분할 수 있습니다.

맥락과 신호 최적화

도구 응답은 고신호 정보를 우선시하고 토큰 낭비를 최소화해야 합니다.

의미적 식별자: 암호화된 UUID 대신 자연어 이름이나 0부터 시작하는 인덱스 ID를 사용해 환각 현상을 줄입니다.
응답 형식: response_format 열거형(예: CONCISE 대비 DETAILED)을 구현. 간결한 응답은 토큰을 절약하지만, 상위 도구 호출에 필요한 ID를 제공하기 위해 상세한 응답이 필요할 수 있습니다.
토큰 효율성: 페이징, 범위 선택, 자르기 등을 사용해 맥락을 관리합니다. 앤트로픽은 Claude Code 도구 응답의 기본값을 25,000 토큰으로 설정합니다.

도구 사양을 위한 프롬프트 엔지니어링

도구 설명은 에이전트 맥락 내에서 방향을 제시하는 메커니즘 역할을 합니다. 앤트로픽은 Claude Sonnet 3.5가 SWE-bench Verified 평가에서 최고 성능을 달성하는 데 있어 도구 설명의 정밀한 개선이 결정적인 역할을 했다고 지적합니다.

명확한 맥락 제공: 신입 직원에게 설명하는 것처럼, 특수 용어와 전문적인 쿼리 형식을 포함해 설명.
모호하지 않은 이름 사용: user_id와 같이 구체적인 매개변수 이름을 사용해 엄격한 데이터 모델을 강제.