agentfork로 에이전트 오류를 단계별로 재현하고 고친다

agentfork는 대규모 언어 모델(LLM) 에이전트의 실행 기록을 저장하고, 문제가 생긴 단계부터 프롬프트·모델·도구 결과를 바꿔 여러 번 시험하는 도구다. 실행은 로컬에서 이뤄지며 계정이나 서버가 필요하지 않고 데이터도 기기 밖으로 나가지 않는다.

예를 들어 주문 API가 "amount": 4999, "currency": "USD"를 반환했을 때, 환불 에이전트가 금액이 센트 단위라는 점을 놓치면 49.99달러짜리 노트북에 4,999달러를 환불할 수 있다. 예제 코드에서 agentfork는 3단계부터 모델과 프롬프트를 바꿔 반복 실행하도록 한다. 원문 예시에서는 gpt-4o-mini와 gpt-4o 모두 잘못된 금액을 반환했고, 큰 모델은 실행당 비용이 15배였지만 문제를 해결하지 못했다. 프롬프트에 API 금액을 100으로 나눠 환불하라는 문장을 더한 경우에는 3회 중 3회가 기대한 49.99를 포함했다.

앞 단계는 캐시에서 재생하므로 바뀐 단계만 비용을 내고 실행할 수 있다. 여러 변형을 각각 반복해 실행하고 통과율을 비교하며, 기본 병렬 실행 수는 4다. 통과 여부는 최종 출력에 지정한 문자열이 있는지를 기준으로 판단한다.

설치와 계측에는 다음과 같은 구성 요소를 사용한다.

pip install "agentfork-cli[openai]" # or agentfork-cli[anthropic]

from openai import OpenAI
from agentfork import trace, tool, wrap_openai

client = wrap_openai(OpenAI()) # records every LLM call (wrap_anthropic for Claude)

@tool # records every tool call
def lookup_order(order_id): ...

@trace # one run = one call of your agent
def run_agent(question): ...

에이전트를 평소처럼 실행하면 기록이 .agentfork/traces.db에 저장된다. LangGraph도 지원하며, LangGraph 예제처럼 채팅 모델과 도구 호출을 감싸서 사용할 수 있다. 다만 streaming=True 모델과 OpenAI Responses API는 아직 기록되지 않는다.

CLI에서는 agentfork list로 최근 실행을 확인하고, agentfork show <id> [--full]로 실행 단계와 전체 JSON을 살펴볼 수 있다. agentfork fork는 지정한 단계부터 한 가지 변경을 적용해 다시 실행하며, agentfork sweep은 여러 변경을 반복 시험해 통과율·토큰·시간·비용을 비교한다. agentfork diff는 실행 두 건을 단계별로 비교하고, agentfork save-test는 캐시를 이용해 CI에서 API 키 없이 재생할 수 있는 pytest 테스트를 저장한다.

웹 UI를 쓰려면 pip install "agentfork-cli[openai,ui]"로 설치한 뒤 agentfork ui를 실행한다. 주소는 http://127.0.0.1:8000이며, 실행 기록이 저장된 .agentfork/ 폴더가 있는 위치에서 시작해야 한다. 서버는 자신의 컴퓨터에서만 접속할 수 있다. UI에서 단계별 입력·출력을 확인하고 변경을 시험하거나 실행 결과를 나란히 비교할 수 있다.

비용은 OpenAI와 Anthropic 모델의 공개 가격을 바탕으로 추정한다. 가격 정보가 없는 모델은 비용이 -로 표시되며, .agentfork/prices.json에 입력·출력 토큰 100만 개당 달러 가격을 추가할 수 있다. 제작자는 agentfork가 실행 기록 재생뿐 아니라 한 단계의 여러 변형을 반복 시험해 근거를 바탕으로 수정안을 고르는 데 초점을 둔다고 설명한다.

부록: 원문 예시

$ agentfork sweep 543da612 --step 3 --repeat 3 --expect "49.99" --model gpt-4o-mini,gpt-4o Estimated cost: about $0.0050   variant             ok    pass   tokens   time      cost   sample output   original            1/1   0/1       446   1.7s   $0.0001   I have processed a refund of $4,999.00...   model=gpt-4o-mini   3/3   0/3       446   1.4s   $0.0001   I have processed a refund of $4,999.00...   model=gpt-4o        3/3   0/3       394   1.2s   $0.0015   The full amount of $4,999.00 for order A123...