P7-6.2 권한, 로그, blocked 상태 검토¶

Section ID: P7-6.2 Version: v2026.07.22

에이전트 run이 승인 대기 때문에 blocked 상태로 멈출 수 있다는 사실만으로는 운영 기록이 충분하지 않습니다. 같은 run 안에서도 어떤 단계는 완료, 어떤 단계는 blocked, 어떤 단계는 진짜 failure일 수 있기 때문입니다.

중심 질문은 단순합니다. 실행 가능하다와 실행해도 된다를 어떻게 구분해 남기고, blocked와 failure를 어떻게 다른 운영 판단으로 읽을 것인가?

권한과 로그가 가르는 상태¶

에이전트 프로젝트에서 권한과 승인 여부를 왜 먼저 적어야 하는가?
blocked와 failure는 로그에서 어떻게 다르게 읽어야 하는가?
권한, 로그, 다음 행동이 왜 운영 판단 기준이 되는가?

권한 -> 승인 여부 -> 결과 상태 -> 다음 행동 구조를 운영 문서로 닫는 데 집중합니다. 즉, 분산 추적 인프라나 감사 시스템 전체를 설명하지 않고, 현재 run에서 보류, 실패, 완료가 어떤 이유로 갈렸는지 남기는 최소 구조를 먼저 고정합니다.

판단 기준¶

권한, 승인 여부, 범위가 왜 실행 기록의 핵심인지 설명할 수 있습니다.
blocked와 failure를 같은 실패로 뭉개지 않고 분리해 기록할 수 있습니다.
실패 로그가 다음 행동과 연결되지 않으면 운영 회고가 약해진다는 점을 설명할 수 있습니다.

왜 권한이 먼저인가¶

도구를 쓰는 에이전트는 단순 텍스트 생성보다 훨씬 강한 행동력을 가집니다.

파일 읽기
파일 수정
빌드 실행
서비스 재시작
외부 API 호출

이 행동들은 모두 위험도가 다릅니다. 그래서 프로젝트 문서에는 적어도 다음 네 가지가 먼저 있어야 합니다.

항목	왜 필요한가
권한	이 도구가 읽기인지, 쓰기인지, 변경인지 구분하기 위해
범위	어느 서비스, 어느 문서, 어느 시스템까지 영향을 주는지 고정하기 위해
승인 여부	지금 이 run에서 실행이 허용됐는지 알기 위해
결과 상태	완료, blocked, failure를 운영적으로 다르게 읽기 위해

권한 기록이 없으면 막혔다는 문장만 남고, 그 막힘이 정책 때문인지 기능 문제인지 구분하기 어렵습니다.

blocked와 failure는 왜 다른가¶

운영 기록에서 이 둘은 비슷해 보여도 해석이 다릅니다.

상태	뜻	먼저 봐야 할 것
blocked	실행할 기능은 있지만 외부 조건이 아직 충족되지 않음	승인 정책, 사람 응답, 허용 범위
failure	실행을 시도했지만 기능적으로 끝나지 못함	오류 로그, 재시도 여부, 대체 경로

따라서 승인 대기와 업로드 timeout을 같은 칸에 넣으면 다음 수정 지점이 흐려집니다.

예를 들어 장애 run을 읽다가 롤백 실행과 감사 로그 첨부 업로드가 모두 끝나지 않은 장면을 보면, 빠르게는 둘 다 실패라고 적고 넘어가기 쉽습니다. 하지만 실제 운영 판단은 다릅니다. 롤백 실행은 권한과 도구는 준비돼 있지만 승인이라는 외부 조건이 닫혀 있어 멈춘 것이고, 감사 로그 첨부 업로드는 승인도 있었는데 timeout으로 기능이 끝나지 못한 것입니다. 따라서 더 안전한 다음 판단은 둘 다 미완료라고 묶는 것이 아니라, 하나는 blocked, 다른 하나는 failure로 나누고 각자 다른 다음 행동을 적는 데 있습니다.

flowchart TD
  A["두 단계 모두 완료되지 않음"]
  B["빠른 판단: 둘 다 실패로 기록"]
  C["승인 여부와 결과 상태를 함께 확인"]
  D["롤백 실행: 승인 없음, blocked"]
  E["로그 업로드: 승인 있음, timeout failure"]
  F["다음 판단: 승인 요청과 기능 재시도를 따로 기록"]

  A --> B
  A --> C
  C --> D
  C --> E
  D --> F
  E --> F

운영 변경 시나리오 예제¶

P7-6.1의 같은 장애 티켓 흐름을 이어 받되, 예제에서는 blocked와 failure가 함께 들어 있는 실행 로그를 사용합니다.

롤백 실행은 승인 없어서 blocked입니다.
감사 로그 첨부 업로드는 권한은 있었지만 timeout으로 failure입니다.

이 차이가 있어야 무엇을 기다려야 하는가와 무엇을 고쳐야 하는가가 동시에 분리됩니다.

입력 파일¶

파일 경로: p7-6-permission-log.csv · CSV 미리보기
한 행의 의미: 도구 한 단계의 권한·승인·결과 기록
핵심 열: step, tool, permission, scope, approved, result_status, observation, next_action

이번 파일에서 특히 먼저 읽어야 하는 열은 다음 셋입니다.

열	먼저 읽는 이유
`permission`	읽기/쓰기/변경 중 어느 층위의 행동인지 바로 보이기 때문
`approved`	blocked가 정책 문제인지 아닌지 먼저 갈라 주기 때문
`result_status`	완료, 보류, 실패를 직접 구분해 주기 때문

실행 기록 기준¶

각 단계의 권한이 읽기, 쓰기, 변경 중 어디에 놓이는지 표시합니다.
approved가 아니오인 단계와 result_status가 실패인 단계를 따로 찾습니다.
blocked 단계에는 승인이나 외부 조건을 여는 다음 행동을 붙입니다.
failure 단계에는 로그 확인, 재시도, 수동 우회 같은 기능적 다음 행동을 붙입니다.

Python 예제¶

예제는 권한 기록, 승인 여부, 결과 상태를 한 번에 집계해 완료, blocked, failure를 분리해 읽는 것입니다.

문제 상황: 같은 run 안에 승인 대기 단계와 진짜 실패 단계가 함께 있다.
입력: 단계별 도구 목록, 권한 범위, 승인 여부, 결과 상태
기대 출력: 상태별 단계 수, blocked 단계 목록, failure 단계 목록, 최종 운영 메모
확인할 개념:
승인 여부만으로는 충분하지 않고 결과 상태까지 함께 봐야 한다
blocked는 정책 또는 외부 조건 문제다
failure는 기능적 종료 실패이므로 로그와 대체 경로가 필요하다

# agent 실행 권한 로그에서 완료, blocked, failure 단계를 나누고 추가 승인이나 재시도 대상 도구를 찾는 예제입니다.
import csv
from pathlib import Path

data_path = Path("docs/assets/part-07/chapter-06/p7-6-permission-log.csv")
rows = list(csv.DictReader(data_path.open(encoding="utf-8")))
대표_steps = {str(step) for step in range(1, 6)}
rows = [row for row in rows if row["step"] in 대표_steps]

실행_기록 = [
    {
        "단계": int(row["step"]),
        "도구": row["tool"],
        "필요한 권한": row["permission"],
        "범위": row["scope"],
        "승인 여부": row["approved"],
        "결과 상태": row["result_status"],
        "관찰 메모": row["observation"],
        "다음 행동": row["next_action"],
    }
    for row in rows
]

blocked_단계 = [
    entry for entry in 실행_기록 if entry["결과 상태"] == "보류"
]
failure_단계 = [
    entry for entry in 실행_기록 if entry["결과 상태"] == "실패"
]

검토_요약 = {
    "단계 수": len(실행_기록),
    "완료 단계 수": sum(entry["결과 상태"] == "완료" for entry in 실행_기록),
    "blocked 단계 수": len(blocked_단계),
    "failure 단계 수": len(failure_단계),
    "추가 승인 필요 도구": [
        entry["도구"] for entry in blocked_단계
    ],
    "재시도 또는 수동 조치 필요 도구": [
        entry["도구"] for entry in failure_단계
    ],
}

print("읽은 파일 =", data_path)
print("실행 기록 =")
for entry in 실행_기록:
    print(entry)
print("blocked 단계 =", blocked_단계)
print("failure 단계 =", failure_단계)
print("검토 요약 =", 검토_요약)

실행 결과 예시는 다음과 같습니다.

읽은 파일 = docs/assets/part-07/chapter-06/p7-6-permission-log.csv
실행 기록 =
{'단계': 1, '도구': '메트릭 조회', '필요한 권한': '읽기', '범위': '관측 대시보드', '승인 여부': '예', '결과 상태': '완료', '관찰 메모': '오류율 12.8%, p95 지연 2.4초', '다음 행동': '배포 이력 조회'}
{'단계': 2, '도구': '배포 이력 조회', '필요한 권한': '읽기', '범위': '배포 기록', '승인 여부': '예', '결과 상태': '완료', '관찰 메모': '18분 전 결제 서비스 v2.3.1 배포 확인', '다음 행동': '롤백 실행 검토'}
{'단계': 3, '도구': '롤백 실행', '필요한 권한': '변경', '범위': '결제 서비스 프로덕션', '승인 여부': '아니오', '결과 상태': '보류', '관찰 메모': '프로덕션 변경은 온콜 리드 승인 전까지 자동 실행 금지', '다음 행동': '온콜 리드 승인 요청'}
{'단계': 4, '도구': '감사 로그 첨부 업로드', '필요한 권한': '쓰기', '범위': '장애 감사 저장소', '승인 여부': '예', '결과 상태': '실패', '관찰 메모': '감사 저장소 업로드가 timeout 으로 실패해 자동 보존이 끝나지 않았다', '다음 행동': '실패 로그를 보고에 첨부하고 수동 등록 요청'}
{'단계': 5, '도구': '상태 보고 작성', '필요한 권한': '쓰기', '범위': '장애 기록 문서', '승인 여부': '예', '결과 상태': '완료', '관찰 메모': '현재는 롤백 실행 전이며 승인 대기 상태이고 감사 로그 업로드는 실패했다고 보고', '다음 행동': '사람 검토 대기'}
blocked 단계 = [{'단계': 3, '도구': '롤백 실행', '필요한 권한': '변경', '범위': '결제 서비스 프로덕션', '승인 여부': '아니오', '결과 상태': '보류', '관찰 메모': '프로덕션 변경은 온콜 리드 승인 전까지 자동 실행 금지', '다음 행동': '온콜 리드 승인 요청'}]
failure 단계 = [{'단계': 4, '도구': '감사 로그 첨부 업로드', '필요한 권한': '쓰기', '범위': '장애 감사 저장소', '승인 여부': '예', '결과 상태': '실패', '관찰 메모': '감사 저장소 업로드가 timeout 으로 실패해 자동 보존이 끝나지 않았다', '다음 행동': '실패 로그를 보고에 첨부하고 수동 등록 요청'}]
검토 요약 = {'단계 수': 5, '완료 단계 수': 3, 'blocked 단계 수': 1, 'failure 단계 수': 1, '추가 승인 필요 도구': ['롤백 실행'], '재시도 또는 수동 조치 필요 도구': ['감사 로그 첨부 업로드']}

결과를 어떻게 읽는가¶

이번 출력에서 가장 중요한 대비는 3단계와 4단계입니다.

단계	이번 기록에서 읽어야 할 점	해석
롤백 실행	기능적으로는 가능하지만 승인 없어서 보류됐다	blocked
감사 로그 첨부 업로드	승인과 권한은 있었지만 timeout으로 끝나지 못했다	failure

이 둘은 다음 행동이 다릅니다.

blocked는 승인 요청, 사람 응답 대기처럼 외부 조건을 여는 행동으로 이어집니다.
failure는 재시도, 수동 등록, 오류 원인 추적처럼 기능 문제를 줄이는 행동으로 이어집니다.

따라서 같은 run 안에서도 보류와 실패를 하나의 실패 표지로 묶으면 운영 회고가 약해집니다.

결과 해석 기준¶

관찰	읽어야 할 뜻
`롤백 실행`은 변경 권한이 필요하다	실행 영향 범위가 커서 승인 여부를 먼저 봐야 한다
`롤백 실행`은 승인 없음으로 보류된다	blocked는 정책 또는 외부 조건 문제다
`감사 로그 첨부 업로드`는 승인됐지만 실패한다	failure는 기능적으로 끝나지 못한 상태다
두 단계의 다음 행동이 다르다	blocked와 failure를 같은 실패로 묶으면 후속 조치가 흐려진다

프로젝트 기록 예시¶

미완료 단계:
권한과 범위:
승인 여부:
결과 상태:
blocked 또는 failure 판단:
다음 행동:

왜 로그와 다음 행동을 같이 남겨야 하나¶

예제에서 4단계 감사 로그 첨부 업로드를 보겠습니다.

필요한 권한은 쓰기였습니다.
승인 여부는 예였습니다.
그런데도 결과 상태는 실패였습니다.

즉, 이 단계는 정책 때문에 막힌 것이 아니라 기능적으로 끝나지 못한 것입니다. 만약 여기서 업로드 실패만 적고 다음 행동을 비워 두면, 다음 반복에서 무엇을 해야 할지 다시 처음부터 고민해야 합니다.

반대로 지금처럼 실패 로그를 보고에 첨부하고 수동 등록 요청까지 남기면, 현재 run이 멈춘 이유와 운영 우회 경로가 같이 보입니다.

표 하나로 요약하면¶

상태	예제 사례	지금 적어야 할 다음 행동
완료	메트릭 조회, 배포 이력 조회, 상태 보고 작성	결과를 다음 단계 판단에 사용
blocked	롤백 실행	승인 요청과 사람 응답 대기
failure	감사 로그 첨부 업로드	실패 로그 첨부, 수동 등록, 재시도 검토

이 표가 있으면 실행 상태가 곧바로 운영 행동 기준으로 번역됩니다.

실행 결과에서 바로 남길 회고 문장¶

이번 run에서는 읽기 도구와 보고 도구는 대부분 완료됐다. 그러나 롤백 실행은 승인 여부가 아니오였기 때문에 blocked 상태로 남았고, 감사 로그 첨부 업로드는 승인과 권한은 있었지만 timeout으로 failure가 발생했다. 따라서 이번 회고에서는 blocked 단계는 승인 정책과 사람 응답 흐름을, failure 단계는 저장소 안정성과 수동 우회 절차를 각각 다시 보아야 한다.

이 회고 문장에서 독자가 붙잡아야 할 형식은 다음입니다.

어떤 단계가 blocked였는가
어떤 단계가 failure였는가
둘의 원인이 어떻게 다른가
다음 행동이 각각 무엇인가

직접 바꿔 보며 확인할 것¶

롤백 실행의 approved 값을 예로 바꿔 봅니다. 관찰할 점: blocked 단계가 사라질 때 검토 요약과 다음 행동이 어떻게 줄어드는가?
감사 로그 첨부 업로드의 result_status를 완료로 바꿔 봅니다. 관찰할 점: failure 단계가 사라지면 회고 문장이 승인 정책 쪽으로 더 기울지 않는가?
감사 로그 첨부 업로드의 approved를 아니오로 바꿔 봅니다. 관찰할 점: 같은 도구라도 지금 문제를 failure로 읽을지 blocked로 읽을지가 어떻게 달라지는가?

핵심 확인 기준은 막혔다보다 왜 막혔고 그래서 다음 행동이 무엇인가입니다.

체크리스트¶

확인할 것	스스로 답할 질문
권한 기록	권한, 범위, 승인 여부를 먼저 적었는가?
상태 분리	blocked와 failure를 같은 상태로 뭉개지 않았는가?
실패 로그	실패 로그가 재시도나 수동 조치 같은 다음 행동과 연결돼 있는가?
승인 대기	승인 대기를 기능 실패와 다른 운영 문제로 읽었는가?
회고 문장	각 미완료 단계의 원인과 다음 행동을 따로 적었는가?

출처와 참고 자료¶

OpenAI, Function calling, OpenAI API Docs, 확인 날짜: 2026-06-29. https://developers.openai.com/api/docs/guides/function-calling
Model Context Protocol, What is MCP?, 확인 날짜: 2026-06-29. https://modelcontextprotocol.io/docs/getting-started/intro