매일 아침 AI 에이전트를 개발하는 엔지니어들은 실제 API와 씨름하며 골머리를 앓는다. 에이전트가 외부 도구를 호출할 때마다 개인정보가 노출될 위험이 있거나, 의도치 않은 데이터 변경이 발생할까 봐 조마조마한 상황이 반복되기 때문이다. 그렇다고 정적인 모의 객체(Static Mocks, 고정된 응답을 반환하는 테스트용 코드)를 쓰자니, 에이전트가 여러 단계에 걸쳐 상태를 주고받는 복잡한 작업을 수행할 때마다 테스트가 깨지기 일쑤다. 최근 개발자 커뮤니티에서는 이러한 문제를 해결하기 위해 실제 환경과 유사한 반응을 생성하는 도구 테스트 프레임워크에 대한 관심이 뜨겁다.

ToolSimulator의 기능과 사용법

ToolSimulator(AI 에이전트의 도구 호출을 가상으로 시뮬레이션하는 프레임워크)는 Strands Evals(AI 에이전트의 성능을 평가하고 테스트하는 개발 도구 모음)의 일부로 공개되었다. 이 도구는 에이전트의 도구 호출을 가로채어 LLM 기반 응답 생성기로 라우팅한다. 생성기는 도구 스키마와 에이전트의 입력값, 현재 시뮬레이션 상태를 종합해 문맥에 맞는 응답을 실시간으로 만들어낸다. 사용자는 별도의 수동 피스처(Fixtures, 테스트를 위해 미리 정의된 데이터)를 작성할 필요가 없다. 설치와 사용은 Strands Evals SDK(소프트웨어 개발 키트)를 통해 즉시 가능하다.

도구를 등록하는 과정은 간단하다. ToolSimulator 인스턴스를 생성한 뒤 @simulator.tool() 데코레이터를 사용해 함수를 감싸면 된다. 실제 함수 본문은 비워두어도 무방하다.

@simulator.tool()
def search_flights(destination: str, date: str) -> str:
 """Search for available flights to a destination on a specific date."""
 pass

기본적으로 ToolSimulator는 도구의 스키마와 독스트링(Docstring, 코드의 기능을 설명하는 주석)에서 동작 방식을 자동으로 추론한다. 추가 설정 없이도 바로 시작할 수 있다는 점이 강점이다.

기존 모의 테스트와의 차이점

예전에는 개발자가 직접 하드코딩된 응답을 일일이 작성하거나, 실제 API를 호출하여 테스트하는 방식이 주를 이루었다. 하지만 실제 API는 호출할 때마다 상태가 변하는 데이터베이스 환경을 완벽히 반영하지 못한다. 예를 들어 항공권 예약 에이전트가 첫 번째 호출에서 검색을 수행하고 두 번째 호출에서 예약 상태를 확인할 때, 정적인 모의 객체는 첫 번째 호출의 결과가 두 번째 호출에 반영되는 상태 변화를 추적하지 못한다. 이제는 ToolSimulator가 에이전트의 도구 호출을 가로채어 상태 레지스트리(State Registry, 시뮬레이션 내의 데이터 상태를 관리하는 저장소)를 업데이트함으로써, 후속 호출에서도 일관된 세계관을 유지한다.

고급 기능을 활용하면 더욱 정교한 테스트가 가능하다. share_state_id를 사용해 여러 도구가 동일한 백엔드 상태를 공유하도록 설정할 수 있으며, initial_state_description을 통해 자연어로 초기 상태를 정의할 수 있다. 특히 표 형식 데이터의 경우 DataFrame.describe()(데이터프레임의 통계적 요약을 생성하는 함수)를 활용해 통계적 분포를 전달하면, 실제 데이터를 직접 노출하지 않고도 현실적인 응답을 얻어낼 수 있다. 또한 Pydantic(데이터 검증 및 설정을 위한 파이썬 라이브러리) 모델을 사용해 출력 스키마를 강제할 수도 있다.

python

상태 공유 예시

@simulator.tool(share_state_id="flight_db")

def book_flight(flight_id: str):

pass

개발자가 바로 체감하는 변화는 테스트의 안전성과 확장성이다. 이제는 실제 API 호출 없이도 복잡한 다단계 워크플로우를 안전하게 검증할 수 있게 되었다. 특히 GoalSuccessRateEvaluator(에이전트의 목표 달성률을 측정하는 평가 도구)와 결합하면, 에이전트의 도구 호출 궤적 전체를 분석하여 성능을 정량적으로 평가할 수 있다. 이는 프로덕션 환경에 배포하기 전 에이전트의 신뢰성을 확보하는 데 결정적인 역할을 한다. Strands Evals 공식 문서에서 상세한 가이드를 확인할 수 있다.

AI 에이전트의 도구 호출 검증은 이제 정적 모의 테스트를 넘어 문맥을 이해하는 지능형 시뮬레이션의 영역으로 진입했다.