AX LABS
← 블로그 AX Ops 방법론

에이전트 변경은 기록돼야 한다

프롬프트만 버전 관리하면 원인을 놓친다

AX LABS 7분 읽기

현장에서 에이전트가 흔들릴 때 가장 먼저 보는 것은 프롬프트다. 누가 문장을 바꿨는지, system prompt가 달라졌는지, 예시가 빠졌는지를 찾는다. 그런데 실제 원인은 거기에만 있지 않다. 같은 프롬프트라도 호출 가능한 tool이 바뀌면 행동이 바뀐다. MCP 서버가 추가되면 검색 경로가 바뀐다. hook이 새로 들어가면 특정 작업이 막힌다. 평가셋이 바뀌면 합격 기준도 바뀐다.

에이전트 운영에서 “프롬프트 버전 관리”라는 말은 너무 좁다. 운영팀이 추적해야 하는 것은 문장이 아니라 행동 조건 전체다.

변경 단위는 프롬프트가 아니라 릴리스 매니페스트다

에이전트는 하나의 코드 파일처럼 움직이지 않는다. 모델, system prompt, instruction, tool schema, 권한 정책, memory, retrieval 설정, MCP 서버, hook, guardrail, 평가셋이 한 번의 실행을 만든다.

그래서 AX Ops에서는 에이전트 변경을 agent_release_manifest로 묶는다. 이 매니페스트는 “이번 배포에서 무엇이 행동을 바꿀 수 있는가”를 적는 장부다.

항목 기록해야 할 값 빠지면 생기는 문제
Prompt commit, tag, 작성자, 변경 의도 출력 변화의 원인을 감으로 찾는다
Tool 이름, schema version, permission 같은 요청이 다른 작업을 실행한다
MCP server version, endpoint, allowed scope 외부 시스템 접근 경로가 추적되지 않는다
Runtime model, temperature, routing rule 재현 실행이 불가능해진다
Eval dataset version, pass rule, reviewer 좋아졌는지 나빠졌는지 판단이 흔들린다

LangSmith는 prompt version, environment, access control, commit tag를 관리 대상으로 둔다. Phoenix도 prompt를 version, store, deploy하고 trace에서 model call, retrieval, tool use를 본다. 이 흐름은 분명하다. 프롬프트는 운영 자산이 되었고, 에이전트 변경은 추적 가능한 릴리스 자산이 되어야 한다. https://docs.langchain.com/langsmith/manage-prompts, https://arize.com/docs/phoenix

프롬프트 diff만 남기는 조직은 에이전트의 실제 변경을 절반만 기록한다.

Tool schema는 API 계약처럼 다뤄야 한다

프롬프트는 의도를 바꾼다. tool schema는 가능한 행동을 바꾼다. 운영 리스크는 후자에서 더 크게 나온다.

예를 들어 search_customer tool에 include_inactive 필드가 추가되면 에이전트는 과거와 다른 고객군을 볼 수 있다. send_email tool의 required field가 바뀌면 실패율이 늘어난다. permission 기본값이 바뀌면 사람이 승인하던 일이 자동 실행으로 넘어간다.

따라서 tool 변경에는 세 가지 규칙이 필요하다.

  1. schema는 semantic version으로 올린다.
  2. breaking change는 prompt 변경과 분리해 배포한다.
  3. tool 호출 trace에는 tool version과 manifest id를 반드시 남긴다.

MCP를 쓰는 조직은 이 원칙을 더 엄격하게 적용해야 한다. 2025-06-18 MCP specification은 protocol message와 structure의 source of truth를 TypeScript schema로 둔다고 명시한다. 표준이 있다는 말은, 내부 운영에서도 schema 기준으로 변경을 관리해야 한다는 뜻이다. https://modelcontextprotocol.io/specification/2025-06-18/basic/index

Claude Code의 settings도 같은 교훈을 준다. 공식 문서는 .claude/settings.json을 source control에 넣어 팀과 공유할 수 있는 project setting으로 설명하고, hooks는 PreToolUse, PostToolUse, SubagentStart, ConfigChange 같은 lifecycle event에서 실행된다. 이것들은 단순 설정이 아니다. 에이전트 행동을 바꾸는 운영 코드다. https://code.claude.com/docs/en/settings, https://code.claude.com/docs/en/hooks

Trace는 사후 로그가 아니라 변경 검증 장치다

변경을 기록해도 실행과 연결되지 않으면 소용없다. 모든 trace에는 manifest_id가 들어가야 한다. 그래야 장애가 났을 때 “이 답변은 어떤 prompt, 어떤 tool schema, 어떤 MCP scope, 어떤 eval 기준에서 나온 것인가”를 역추적한다.

OpenAI Agents SDK는 tracing에서 LLM generation, tool call, handoff, guardrail, custom event를 수집한다고 설명한다. 2026년 4월 OpenAI는 Agents SDK 확장에서 model-native harness와 sandbox execution을 발표했다. 에이전트 운영의 중심이 prompt 작성에서 harness 관리로 이동했다는 신호다. https://openai.github.io/openai-agents-js/guides/tracing, https://openai.com/index/the-next-evolution-of-the-agents-sdk/

AX Ops의 검증 흐름은 단순하다.

  1. 변경 요청에 manifest draft를 붙인다.
  2. 과거 trace에서 대표 케이스를 뽑아 replay한다.
  3. eval dataset version을 고정하고 전후 결과를 비교한다.
  4. canary 배포 후 production trace를 같은 manifest로 묶는다.
  5. 문제 발생 시 manifest 단위로 rollback한다.

이 구조가 없으면 회의가 길어진다. 프롬프트 담당자는 tool을 본다. 개발팀은 모델을 본다. 현업은 “전에는 됐다”고 말한다. 맞는 말이지만 운영 판단에는 부족하다. 전에는 어떤 조합이었는지가 남아 있어야 한다.

참고와 다음 행동은 같이 가야 한다

프롬프트·도구 버전 관리는 문서 정리 업무가 아니다. 운영 중인 에이전트의 원인 추적 능력을 만드는 일이다. 최소 단위는 prompt registry가 아니라 agent release manifest다. 그리고 그 manifest는 trace, eval, rollout, rollback과 연결되어야 한다.

참고한 최근 12개월 내 1차 출처는 다음과 같다.

AX LABS는 이 구조를 AX Ops의 변경·검증·운영 루프로 설계한다. 프롬프트를 잘 쓰는 팀이 아니라, 변경을 추적하고 되돌릴 수 있는 팀이 에이전트를 운영한다. AX Ops 방법론 →