두 AI 에이전트 실행 경로가 달라진 지점 찾기

어제는 하나의 답변을 내놓았던 에이전트가 오늘 다른 답변을 내놓았습니다. 코드는 같고, 입력 파일도 같은데 결정(decision)이 다릅니다. 무언가를 수정하기 전에, 두 실행 과정이 어디서 갈라졌는지 알아야 합니다. 프롬프트가 변경되었나요? 모델의 응답이 변경되었나요? 아니면 모델 호출 이후에 무언가가 변경되었나요?

본 튜토리얼은 Python에서 에이전트를 실행하는 엔지니어들을 위한 것으로, 기억에 의존하기보다 기록된 두 번의 실행(run)을 통해 이러한 질문에 답하는 방법을 다룹니다. 여러분은 두 개의 실행을 Run Capsules로 캡처하고, nova diff를 사용하여 비교하며 어떤 모델 호출이 변경되었는지 읽어내고, 이 동일한 비교 과정을 CI 게이트(CI gate)로 활용하는 방법을 배울 것입니다. 아래의 모든 명령어와 출력은 공개된 novafabric 0.104.0에서 캡처되었습니다. 긴 경로나 건너뛴 줄은 …으로 표시되어 있습니다.

준비물

• Python 3.12 이상 (패키지에서 Requires-Python: >=3.12 명시)
• pip install novafabric openai
• 공개된 MSKazemi/novafabric 저장소의 examples/blackbox_demo/ 디렉토리를 비어있는 작업 디렉토리로 복사합니다. 모든 명령어는 해당 작업 디렉토리에서 실행해야 합니다.

API 키나 호스팅된 모델은 사용되지 않습니다. 예제는 127.0.0.1:9099에서 작고 OpenAI와 호환되는 목업 서버를 제공합니다.

시나리오

agent.py는 결제 서비스(payment-service) 설정을 읽어 모델에게 권장되는 변경 사항을 하나 요청하고, 그 답변을 outputs/decision.json에 기록합니다. 이 목업 서버는 에이전트가 보내는 요청 헤더에 따라 두 가지 방식 중 하나로 응답합니다: 위험한 답변(rate limiting 비활성화) 또는 안전한 답변(max_connections 감소). 따라서 알려진 이유로 동작이 다른 두 개의 실행을 얻게 되며, 이를 통해 diff가 올바른 지점을 가리키는지 확인할 수 있습니다.

1단계: 목업 모델 시작

python blackbox_demo/mock_llm_server.py &
export OPENAI_API_KEY=sk-demo-no-key-needed
export OPENAI_BASE_URL=http://127.0.0.1:9099
...

2단계: 첫 번째 실행 캡처

nova capture는 코드 변경 없이 명령을 래핑합니다. Python 워크로드에서 발생하는 모델 호출은 자동으로 기록됩니다.

$ nova capture -- python blackbox_demo/agent.py --mode bad
✓ Capsule written: …/.novafabric/capsules/01M4FBTQ7FVQEZBWQGFD2RVTW2

캡슐 경로를 변수에 저장해 두세요 (실행 ID는 다릅니다):

BAD=$HOME/.novafabric/capsules/01M4FBTQ7FVQEZBWQGFD2RVTW2

3단계: 두 번째 실행 기록하기(capture)

$ nova capture -- python blackbox_demo/agent.py --mode fixed
✓ Capsule written: …/.novafabric/capsules/01M4FBVEZDG7XVBYJBB9WD6Q8D

4단계: 두 실행 비교하기(diff)

$ nova diff "$BAD" "$FIXED"
  changed=3  added=0  removed=0

...

세 개의 항목이 변경되었습니다(~): 모델 호출 1개와 출력 파일 2개입니다. 추가되거나 제거된 것은 없습니다. 기계가 읽을 수 있는 기록의 경우, --output-format json을 추가하세요. 이 경우 모델 호출 쌍은 request_changed: false와 response_changed: true를 보고합니다.

해석 방법

• aligned: 1: diff가 각 실행에서 발생한 단일 모델 호출을 페어링했습니다.
• request_changed: false, response_changed: true: 에이전트가 두 번 모두 동일한 요청을 보냈지만 다른 응답을 받았습니다. 실행 경로가 프롬프트 빌드 코드에서 아니라 모델의 답변에서 갈라졌습니다.
• environment.changes: []: 추적할 기록된 환경 차이가 없습니다.
• outputs: 두 파일 모두 해당 응답 이후에 변경되었습니다.

5단계: CI 게이트로 사용하기

--assert-no-regressions는 nova diff가 추가되거나 제거된 호출을 포함하여 어떤 구조적 변화라도 발견하면 종료 코드 1을 반환하게 합니다. 자신과 비교하는 실행은 0으로 종료됩니다. GitHub Actions에서 --output-format github-annotation를 사용하면 변경 사항당 하나의 주석이 출력됩니다.

게이트의 의미를 이해하세요: 이는

• 변경 사항을 판단하지 않습니다. 이 차이(diff)는 구조적입니다. 어떤 호출과 어떤 파일이 다른지 알려줄 뿐, 새로운 동작이 더 나은지는 말해주지 않습니다.
• 모든 차이가 중요합니다. 실제 모델을 대상으로 할 때, 동일한 프롬프트를 두 번 실행해도 서로 다른 텍스트가 반환될 수 있으며, 게이트(gate)는 이 경우에도 실패합니다.
• 자동 모델 호출 캡처는 Python 워크로드에 한정됩니다. 다른 클라이언트는 nova api-proxy를 거칩니다.
• 봉인(Sealing)은 선택 사항이며 여기서는 사용되지 않았습니다. 캡슐 형식(capsule format)은 pre-1.0 버전입니다.

전체 버전(모든 명령어 출력, 리플레이 섹션 및 CI 예시 포함)은 원본 페이지에서 확인할 수 있습니다: https://novafabric.ai/blog/find-where-two-agent-runs-diverged/

원래 게시일: novafabric.ai. NovaFabric은 오픈 소스(Apache-2.0)이며 pre-1.0 버전입니다: github.com/MSKazemi/novafabric.