AI 도구 호출 설계: 함수 이름보다 중요한 입력·오류·부작용

에이전트도 선택하기 쉬운 인터페이스가 필요합니다

Anthropic의 도구 설계 글은 도구 선택, 설명, 반환 정보와 평가를 함께 다룹니다. 일반적인 API가 준비되어 있어도 모델이 어떤 도구를 언제 써야 하는지 이해하기 어려우면 호출 품질이 떨어질 수 있습니다. 실제 사용자의 질문과 연결되는 업무 단위로 도구를 검토해 보세요.

'update_record'처럼 무엇이 바뀌는지 드러나지 않는 이름보다 '주문 배송지 변경'처럼 목적이 보이는 도구가 관리하기 쉽습니다. 그렇다고 모든 세부 행동을 거대한 도구 하나에 넣으면 입력과 부작용이 복잡해집니다. 도구를 선택한 이유와 호출 결과를 사람이 검토할 수 있을 정도의 범위를 유지하세요.

식별자와 필수 조건을 명확히 합니다

오류 응답은 다음 행동을 결정할 수 있게 만듭니다

권한 부족, 입력 오류와 일시적인 서버 장애를 모두 '실패'로 반환하면 에이전트가 같은 요청을 반복할 수 있습니다. 오류 종류, 재시도 가능 여부와 필요한 수정 정보를 나누세요. 다만 내부 SQL, 스택 전체나 비밀 값까지 반환할 필요는 없습니다. 개발자용 로그에는 별도 추적 ID로 연결하면 됩니다.

검색 도구가 결과를 찾지 못한 경우도 정상적인 결과로 정의해야 합니다. '없음'과 검색 서비스 장애를 구분하지 않으면 없는 정보를 만들어 답하거나 중요한 자료가 없다고 잘못 안내할 수 있습니다. 결과가 부분적으로 반환됐을 때에는 그 사실과 후속 조회 방법도 알려주세요.

변경 도구는 재호출되어도 결과가 안전해야 합니다

사용자가 한 번 요청했어도 네트워크 지연이나 에이전트의 재시도로 호출이 중복될 수 있습니다. 업무 요청 ID를 두고 이미 처리한 작업을 확인하세요. 조회와 실행 사이에 주문 상태가 달라질 수 있으므로 변경 직전에 서버가 조건을 다시 검사해야 합니다. 모델이 만든 인자는 검증해야 할 입력으로 취급합니다.

도구 품질을 확인하는 질문 묶음

• 비슷한 이름의 도구 중 올바른 것을 선택하는가
• 모호한 주문명에서 고유 ID를 먼저 확인하는가
• 필수 값이 빠지면 추측하지 않고 부족한 정보를 요청하는가
• 권한 오류를 재시도로 해결하려 하지 않는가
• 응답이 끊긴 뒤 같은 작업을 중복 실행하지 않는가