P7-6.1 계획, 도구 호출, 승인 흐름 실습¶

Section ID: P7-6.1 Version: v2026.07.22

RAG가 문서를 찾아 답에 붙이는 구조였다면, 에이전트(agent) 프로젝트는 도구를 호출하고, 관찰을 읽고, 다음 행동을 고르는 구조입니다. 여기서 중요한 것은 agent를 막연한 지능으로 설명하지 않는 것입니다. 에이전트를 목표를 들고 실행 루프를 돌리되, 외부 조건이 막히면 blocked 상태로 멈출 수도 있는 구조로 읽으면 충분합니다.

즉, 핵심은 도구를 썼다가 아니라 왜 이 도구를 지금 썼는가, 무엇을 보고 다음 행동을 정했는가, 왜 어떤 시점에서는 더 진행하지 못하고 blocked로 멈췄는가를 기록하는 데 있습니다.

도구 실행 루프와 멈춤 상태¶

• 도구를 쓰는 에이전트 프로젝트는 어떤 실행 루프로 적어야 하는가?
• RAG와 에이전트의 차이는 무엇인가?
• 성공, 계속 진행, blocked 상태를 같은 실행 기록 안에서 어떻게 구분하는가?

목표 -> 도구 선택 -> 관찰 -> 다음 행동 -> blocked 또는 보고 구조를 프로젝트 문서로 닫는 데 집중합니다. 즉, 권한 정책의 세부 설계보다, 관찰을 다 했더라도 외부 승인이나 사람 결정이 없으면 run이 blocked 상태로 끝날 수 있다는 점을 먼저 붙잡습니다.

판단 기준¶

• 에이전트를 계획 -> 행동 -> 관찰 -> 다음 행동 루프로 설명할 수 있습니다.
• 완료, 계속 진행, blocked를 같은 실행 기록 안에서 구분할 수 있습니다.
• 도구 호출 흐름이 끝까지 진행되지 못해도 그 상태를 프로젝트 문서로 남길 수 있습니다.

왜 blocked 상태를 같이 봐야 하나¶

에이전트 프로젝트를 처음 보면 종종 도구를 여러 개 부르면 결국 끝난다고 생각합니다. 하지만 실제 운영에서는 그렇지 않습니다. 다음과 같은 경우가 바로 생깁니다.

• 필요한 정보는 다 모았지만 승인 전이라 변경을 실행할 수 없는 경우
• 외부 시스템 응답이 오지 않아 다음 행동이 열리지 않는 경우
• 사람 검토가 오기 전까지는 계속 진행하면 안 되는 경우

그래서 에이전트 프로젝트 입구에서는 정상 완료뿐 아니라 현재는 여기서 멈춰야 한다는 상태도 같이 적어 두는 편이 좋습니다.

RAG와 에이전트의 차이¶

RAG와 에이전트는 둘 다 LLM 프로젝트이지만 중심 질문이 다릅니다.

즉, 에이전트는 답변 생성보다 실행 제어 쪽이 더 중심입니다.

프로젝트 질문 설정¶

프로젝트는 결제 API 5xx 오류가 급증했다는 운영 티켓을 받고, 현재 상태를 확인한 뒤 안전한 다음 행동을 정리할 수 있는가?라는 질문에서 시작합니다. 이 질문이 좋은 이유는 조회 도구만으로도 꽤 많은 판단이 가능하지만, 마지막 단계에서는 승인이라는 외부 조건 때문에 run이 blocked 상태가 될 수 있다는 점까지 함께 보여 줄 수 있기 때문입니다.

예를 들어 오류율 급증과 최근 배포 존재만 바로 붙여 보면, 빠르게는 원인은 최근 배포이므로 즉시 롤백이라고 적고 싶어질 수 있습니다. 하지만 더 안전한 다음 판단은 그렇게 실행부터 뛰는 것이 아니라, 메트릭이 실제로 얼마나 악화됐는가, 배포 시점과 장애 시점이 얼마나 가깝게 겹치는가, 지금 변경을 실행해도 되는 승인 상태인가를 차례로 적는 것입니다. 그래야 원인 가설, 실행 가능성, 실행 허용 여부를 한 줄로 섞지 않게 됩니다.

flowchart TD
  A["문제 장면<br/>오류율 급증과 최근 배포가 함께 보임"]
  B["빠른 판단<br/>즉시 롤백 실행"]
  C["메트릭 확인<br/>악화 강도와 고객 영향"]
  D["배포 이력 확인<br/>장애 시점과 실제로 겹치는가"]
  E["승인 상태 확인<br/>지금 실행 허용 범위인가"]
  F["더 안전한 판단<br/>근거와 승인 상태를 나눠 다음 행동 결정"]

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

프로젝트 흐름¶

flowchart TD
  A["운영 티켓 읽기"]
  B["조회 도구 선택"]
  C["도구 실행과 관찰"]
  D["다음 행동 초안 작성"]
  E{"외부 승인 또는 사람 결정이 필요한가?"}
  F["blocked 상태로 멈추고 보고"]
  G["계속 진행 또는 종료"]

  A --> B --> C --> D --> E
  E -- 예 --> F
  E -- 아니오 --> G
  G --> B

이 도식에서 중요한 점은 실행 루프와 blocked 분기가 함께 있다는 것입니다. 좋은 에이전트 기록은 도구 호출이 어디까지 성공했는지뿐 아니라, 어디서부터는 더 진행하면 안 되는지도 남깁니다.

입력 파일¶

• 파일 경로: p7-6-agent-triage-steps.csv · CSV 미리보기
• 한 행의 의미: 운영 티켓 처리 루프의 한 단계
• 핵심 열: step, tool, reason, result_status, result_summary, observation, review_state, next_action

이번 파일은 단순 성공 로그가 아닙니다. 여기서도 한 단계마다 왜 이 도구를 불렀는가, 무엇을 봤는가, 현재 상태가 계속 진행인지 blocked인지, 다음 행동이 무엇인가까지 같이 적혀 있습니다.

실행 기록 기준¶

• 계획 목록에서 각 도구가 왜 필요한지 먼저 표시합니다.
• 실행 기록에서 결과 상태와 검토 상태가 다른 역할을 한다는 점을 확인합니다.
• blocked 단계가 어느 도구에서 생겼는지 따로 뽑습니다.
• 최종 보고 문장에 확인한 사실, 아직 실행하지 말아야 할 행동, 다음 운영 행동을 나누어 적습니다.

운영 티켓 예제¶

이번 run은 다음 여섯 단계로 흘러갑니다.

이 예제에서 바로 롤백을 실행하지 않는 이유는 간단합니다. 할 수 있는가보다 지금 해도 되는가가 먼저이기 때문입니다.

Python 예제¶

예제는 에이전트 실행 기록에서 완료 단계와 blocked 단계를 함께 읽는 것입니다. 코드 자체는 단순하지만, 출력은 현재 핵심 질문에 맞게 계획, 실행 기록, blocked 요약, 최종 보고를 같이 남기도록 구성합니다.

• 문제 상황: 운영 티켓 하나를 읽고 안전한 다음 행동을 정리하되, 승인 전이면 blocked 상태로 멈춘다.
• 입력: 티켓 1개, 조회 도구 3개, 승인 요청 1개, 상태 보고 1개, 승인 대기 확인 1개
• 기대 출력: 계획 목록, 실행 기록, blocked 단계 목록, 최종 보고
• 확인할 개념:
• 도구 결과는 다음 행동을 정하는 입력이다
• 모든 관찰이 끝나도 외부 조건이 없으면 run은 blocked 상태가 될 수 있다
• blocked는 실패와 다른 실행 상태다

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59

# 결제 API 장애 티켓 대응에서 agent 계획, 도구 실행 기록, blocked 단계, 최종 운영 보고를 정리하는 예제입니다.
import csv
from pathlib import Path

목표 = "결제 API 장애 티켓을 읽고 안전한 다음 행동을 정리한다"
data_path = Path("docs/assets/part-07/chapter-06/p7-6-agent-triage-steps.csv")
step_rows = list(csv.DictReader(data_path.open(encoding="utf-8")))
대표_steps = {str(step) for step in range(1, 7)}
step_rows = [row for row in step_rows if row["step"] in 대표_steps]

계획_단계 = [
    {
        "단계": int(row["step"]),
        "도구": row["tool"],
        "이유": row["reason"],
    }
    for row in step_rows
]

실행_기록 = [
    {
        "단계": int(row["step"]),
        "도구": row["tool"],
        "결과 상태": row["result_status"],
        "결과 요약": row["result_summary"],
        "관찰": row["observation"],
        "검토 상태": row["review_state"],
        "다음 행동": row["next_action"],
    }
    for row in step_rows
]

blocked_단계 = [
    {
        "단계": entry["단계"],
        "도구": entry["도구"],
        "관찰": entry["관찰"],
        "다음 행동": entry["다음 행동"],
    }
    for entry in 실행_기록
    if entry["결과 상태"] == "보류" or entry["검토 상태"] == "blocked"
]

최종_보고 = {
    "목표": 목표,
    "완료 단계 수": sum(entry["결과 상태"] == "성공" for entry in 실행_기록),
    "blocked 단계 수": len(blocked_단계),
    "현재 판단": "최근 배포 영향 가능성은 높지만 롤백 실행은 승인 전이라 blocked 상태다",
    "다음 운영 행동": "온콜 리드 승인 도착 전까지 상태 보고를 유지한다",
}

print("읽은 파일 =", data_path)
print("목표 =", 목표)
print("계획 목록 =", 계획_단계)
print("실행 기록 =")
for entry in 실행_기록:
    print(entry)
print("blocked 단계 =", blocked_단계)
print("최종 보고 =", 최종_보고)

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

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12

읽은 파일 = docs/assets/part-07/chapter-06/p7-6-agent-triage-steps.csv
목표 = 결제 API 장애 티켓을 읽고 안전한 다음 행동을 정리한다
계획 목록 = [{'단계': 1, '도구': '티켓 읽기', '이유': '현재 장애 요청과 우선순위를 먼저 알아야 한다'}, {'단계': 2, '도구': '메트릭 조회', '이유': '실제 오류율과 지연이 얼마나 악화됐는지 확인해야 한다'}, {'단계': 3, '도구': '배포 이력 조회', '이유': '최근 변경이 장애 시점과 겹치는지 봐야 한다'}, {'단계': 4, '도구': '승인 요청 작성', '이유': '프로덕션 변경 전에는 누가 승인해야 하는지 명확히 남겨야 한다'}, {'단계': 5, '도구': '사용자 상태 보고 작성', '이유': '지금 무엇이 끝났고 무엇이 blocked 상태인지 함께 알려야 한다'}, {'단계': 6, '도구': '승인 응답 대기 확인', '이유': '다음 행동을 진행할 수 있는 외부 조건이 충족됐는지 확인해야 한다'}]
실행 기록 =
{'단계': 1, '도구': '티켓 읽기', '결과 상태': '성공', '결과 요약': 'P1 티켓을 확인했다', '관찰': '결제 API 5xx 오류율 급증, 고객 영향 있음', '검토 상태': '계속 진행', '다음 행동': '메트릭 조회'}
{'단계': 2, '도구': '메트릭 조회', '결과 상태': '성공', '결과 요약': '최근 15분 메트릭을 읽었다', '관찰': '오류율 12.8%, p95 지연 2.4초, 정상 기준보다 크게 높다', '검토 상태': '긴급 검토', '다음 행동': '배포 이력 조회'}
{'단계': 3, '도구': '배포 이력 조회', '결과 상태': '성공', '결과 요약': '최근 배포를 확인했다', '관찰': '18분 전 결제 서비스 v2.3.1 배포가 있었다', '검토 상태': '최근 배포 영향 의심', '다음 행동': '승인 요청 작성'}
{'단계': 4, '도구': '승인 요청 작성', '결과 상태': '성공', '결과 요약': '온콜 리드 승인 요청 초안을 만들었다', '관찰': '롤백은 기능적으로 가능하지만 아직 자동 실행 허용 범위 밖이다', '검토 상태': '승인 대기', '다음 행동': '사용자 상태 보고 작성'}
{'단계': 5, '도구': '사용자 상태 보고 작성', '결과 상태': '성공', '결과 요약': '현재 상태 보고를 작성했다', '관찰': '장애 원인 후보와 blocked 상태를 함께 보고하고 승인 대기라고 명시했다', '검토 상태': 'blocked 상태 공유', '다음 행동': '승인 응답 대기'}
{'단계': 6, '도구': '승인 응답 대기 확인', '결과 상태': '보류', '결과 요약': '승인이 아직 도착하지 않았다', '관찰': '롤백 실행은 준비됐지만 승인 없이는 진행할 수 없어 현재 run 은 blocked 상태로 남는다', '검토 상태': 'blocked', '다음 행동': '사람 승인 도착 전까지 종료'}
blocked 단계 = [{'단계': 6, '도구': '승인 응답 대기 확인', '관찰': '롤백 실행은 준비됐지만 승인 없이는 진행할 수 없어 현재 run 은 blocked 상태로 남는다', '다음 행동': '사람 승인 도착 전까지 종료'}]
최종 보고 = {'목표': '결제 API 장애 티켓을 읽고 안전한 다음 행동을 정리한다', '완료 단계 수': 5, 'blocked 단계 수': 1, '현재 판단': '최근 배포 영향 가능성은 높지만 롤백 실행은 승인 전이라 blocked 상태다', '다음 운영 행동': '온콜 리드 승인 도착 전까지 상태 보고를 유지한다'}

결과를 어떻게 읽는가¶

예제의 핵심은 여섯 번째 단계입니다.

즉, 이번 run은 끝까지 완료된 자동화가 아니라 충분한 관찰과 안전한 멈춤이 있는 에이전트 run입니다.

결과 해석 기준¶

프로젝트 기록 예시¶

1
2
3
4
5
6

목표:
자동으로 완료한 단계:
blocked가 생긴 단계:
blocked 이유:
지금 실행하지 말아야 할 행동:
다음 운영 행동:

왜 blocked는 실패와 다른가¶

blocked는 도구가 망가졌다는 뜻이 아닙니다.

• 필요한 메트릭은 읽었습니다.
• 최근 배포도 확인했습니다.
• 다음 행동 후보도 정리했습니다.
• 다만 프로덕션 변경을 실행할 외부 승인이 아직 없습니다.

따라서 이 상태를 실패로 기록하면 문제 원인을 잘못 읽게 됩니다. 더 정확한 표현은 현재 정책 아래에서 더 진행하면 안 되므로 blocked입니다.

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

이번 에이전트 실습에서는 조회 도구 3개와 문서화 단계 2개를 통해 장애 강도와 최근 배포 근거를 확보했다. 그러나 롤백 실행은 승인 전이라 실제 변경 단계로 넘어가지 못했고, 마지막 단계는 승인 응답 대기 상태에서 blocked로 종료됐다. 따라서 이 run은 실패라기보다 외부 승인 미충족 때문에 안전하게 멈춘 실행으로 정리하는 편이 더 정확하다.

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

• 어느 단계까지는 자동으로 진행됐는가
• 어디서 blocked가 생겼는가
• blocked 이유가 기능 실패인지 외부 조건인지
• 지금 시점의 다음 행동이 무엇인지

직접 바꿔 보며 확인할 것¶

1. CSV에서 6단계의 result_status를 성공으로 바꾸고 다음 행동을 롤백 실행으로 바꿔 봅니다. 관찰할 점: blocked 단계가 사라지면 최종 보고 문장이 어떻게 달라지는가?

2. 4단계 승인 요청 작성을 지워 봅니다. 관찰할 점: 6단계의 blocked가 갑자기 튀어나온 것처럼 읽히지 않는가? 즉, blocked에도 준비 단계가 필요하다는 점이 보이는가?

3. 5단계 사용자 상태 보고 작성을 빼 봅니다. 관찰할 점: blocked는 남아 있지만 사용자나 운영자가 지금 상태를 어떻게 알 수 있는지 비어 버리지 않는가?

핵심 확인 기준은 도구를 많이 불렀는가보다 어디서 멈춰야 하는지까지 실행 기록에 남겼는가입니다.

이어서 점검할 질문¶

이어서 점검할 질문은 다음과 같습니다.

체크리스트¶

출처와 참고 자료¶

• 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