파일 업로드부터 Human Review, Pause/Resume까지 — AI Agent 시리즈 최종편

앞의 세 편에서 우리는 단순한 Worker에서 시작해 Agent Orchestrator, MCP Tool, 그리고 운영 가능한 Agent Runtime의 구조까지 살펴봤다.

이번 최종편의 목표는 지금까지 설명한 구성 요소를 실제로 연결하는 것이다.

Invoice Upload
      ↓
FastAPI
      ↓
Redis Streams
      ↓
Agent Worker
      ↓
Agent Runtime
      ↓
MCP Tools
      ↓
Invoice Analysis
      ↓
Confidence = 0.58
      ↓
Human Review
      ↓
WAITING_HUMAN
      ↓
Worker 종료

      ... 몇 시간 후 ...

Human APPROVE
      ↓
Redis Resume Event
      ↓
Agent Worker
      ↓
Load Checkpoint
      ↓
ERP Registration
      ↓
COMPLETED

완전한 상용 시스템 전체를 구현하기보다 실제 서비스로 확장할 수 있는 최소 구조를 만드는 데 집중한다.

1. 최종 아키텍처

                     User
                      │
                   Upload
                      ↓
                   FastAPI
                      │
            ┌─────────┴─────────┐
            ↓                   ↓
      Object Storage       Redis Streams
                                │
                                ↓
                           Agent Worker
                                │
                                ↓
                         Agent Runtime
                         ┌──────┴──────┐
                         ↓             ↓
                     State Store   Orchestrator
                                       │
                                       ↓
                                  LLM Decision
                                       │
                                       ↓
                                   MCP Client
                                       │
                                       ↓
                                   MCP Server
                                       │
                    ┌──────────────────┼──────────────────┐
                    ↓                  ↓                  ↓
              Document Tool      Analysis Tool      Business Tool
                    │                  │                  │
                    └──────────────────┼──────────────────┘
                                       ↓
                                  Service Layer
                                       │
                         ┌─────────────┼─────────────┐
                         ↓             ↓             ↓
                      Storage          DB        External API

FastAPI는 파일 업로드와 Review API, Redis Streams는 Start/Resume Event, Worker는 Runtime 실행, Runtime은 State와 종료 조건, Orchestrator는 다음 행동, MCP는 Tool 연결, Service Layer는 실제 업무를 담당한다.

2. 프로젝트 구조

agent-backend/
│
├── api/
│   ├── upload.py
│   └── review.py
├── agent/
│   ├── runtime.py
│   ├── orchestrator.py
│   ├── state.py
│   └── worker.py
├── mcp_server/
│   └── server.py
├── services/
│   ├── document_service.py
│   ├── analysis_service.py
│   ├── review_service.py
│   └── erp_service.py
├── repositories/
│   ├── agent_repository.py
│   └── document_repository.py
├── infrastructure/
│   ├── redis.py
│   └── database.py
└── main.py

처음부터 Microservice로 나눌 필요는 없다. 하나의 Python 프로젝트 안에서도 책임을 분리해두면 나중에 필요한 부분만 독립시킬 수 있다.

3. Agent State 정의

from dataclasses import dataclass, field
from typing import Any

@dataclass
class AgentState:
    run_id: str
    document_id: str
    status: str = "CREATED"
    step: int = 0
    last_tool: str | None = None
    retry_count: int = 0
    document_type: str | None = None
    confidence: float | None = None
    human_result: dict | None = None
    context: dict[str, Any] = field(default_factory=dict)

State는 단순한 LLM 대화 기록이 아니라 Agent Runtime이 중단되고 다시 실행되어도 복구할 수 있는 시스템 상태다.

4. State를 DB에 저장한다

CREATE TABLE agent_runs (
    run_id VARCHAR(64) PRIMARY KEY,
    document_id VARCHAR(64) NOT NULL,
    status VARCHAR(32) NOT NULL,
    current_step INT NOT NULL DEFAULT 0,
    last_tool VARCHAR(100),
    retry_count INT NOT NULL DEFAULT 0,
    state_json JSON NOT NULL,
    created_at DATETIME NOT NULL,
    updated_at DATETIME NOT NULL
);

Tool 실행 이력도 별도로 저장한다.

CREATE TABLE agent_steps (
    id BIGINT AUTO_INCREMENT PRIMARY KEY,
    run_id VARCHAR(64) NOT NULL,
    step_no INT NOT NULL,
    tool_name VARCHAR(100) NOT NULL,
    input_json JSON,
    output_json JSON,
    status VARCHAR(32) NOT NULL,
    error_message TEXT,
    started_at DATETIME NOT NULL,
    finished_at DATETIME,
    UNIQUE KEY uq_agent_step (run_id, step_no)
);

agent_runs는 현재 상태, agent_steps는 실행 이력을 담당한다.

5. 파일 업로드 API

from fastapi import APIRouter, UploadFile

router = APIRouter()

@router.post("/documents")
async def upload_document(file: UploadFile):
    document = await document_service.save(file)

    run = await agent_service.create_run(
        document_id=document.id
    )

    await event_bus.publish_start(
        run_id=run.run_id,
        document_id=document.id,
    )

    return {
        "document_id": document.id,
        "run_id": run.run_id,
        "status": "QUEUED",
    }

FastAPI가 직접 Agent를 실행하지 않는 것이 중요하다.

HTTP Request
     ↓
File Save
     ↓
Agent Run 생성
     ↓
Event Publish
     ↓
HTTP Response

6. Redis Streams에 START Event를 넣는다

import redis.asyncio as redis

redis_client = redis.Redis(
    host="localhost",
    port=6379,
    decode_responses=True,
)

async def publish_agent_start(run_id: str, document_id: str):
    await redis_client.xadd(
        "agent:events",
        {
            "event": "START",
            "run_id": run_id,
            "document_id": document_id,
        },
    )

7. Consumer Group

Stream: agent:events
        │
        ↓
Consumer Group: agent-workers
        │
    ┌───┼───┐
    ↓   ↓   ↓
   W1  W2  W3

async def ensure_consumer_group():
    try:
        await redis_client.xgroup_create(
            name="agent:events",
            groupname="agent-workers",
            id="0",
            mkstream=True,
        )
    except Exception as e:
        if "BUSYGROUP" not in str(e):
            raise

실제 운영에서는 구체적인 Redis 예외 타입을 처리하는 편이 좋다.

8. Agent Worker

async def run_worker(worker_name: str):
    while True:
        messages = await redis_client.xreadgroup(
            groupname="agent-workers",
            consumername=worker_name,
            streams={"agent:events": ">"},
            count=10,
            block=5000,
        )

        for stream, entries in messages:
            for message_id, data in entries:
                try:
                    await handle_event(data)

                    await redis_client.xack(
                        "agent:events",
                        "agent-workers",
                        message_id,
                    )
                except Exception:
                    logger.exception("Agent event failed")

Worker는 업무 규칙을 알 필요가 없다. Event를 받아 Runtime을 실행할 뿐이다.

9. START와 RESUME Event

async def handle_event(event):
    event_type = event["event"]

    if event_type == "START":
        state = await agent_repository.load(
            event["run_id"]
        )
        await agent_runtime.run(state)
        return

    if event_type == "RESUME":
        await resume_agent(event)
        return

    raise ValueError(f"Unknown event: {event_type}")

10. MCP Tool은 기존 Service를 감싼다

from mcp.server.fastmcp import FastMCP

mcp = FastMCP("document-agent-tools")

@mcp.tool()
def get_document(document_id: str) -> dict:
    return document_service.get_document(document_id)

@mcp.tool()
def extract_document_content(document_id: str) -> dict:
    return document_service.extract_content(document_id)

@mcp.tool()
def analyze_invoice(document_id: str) -> dict:
    return analysis_service.analyze_invoice(document_id)

@mcp.tool()
def request_human_review(
    run_id: str,
    document_id: str,
    reason: str,
) -> dict:
    return review_service.create_review(
        run_id=run_id,
        document_id=document_id,
        reason=reason,
    )

@mcp.tool()
def create_erp_record(
    document_id: str,
    operation_id: str,
) -> dict:
    return erp_service.create_invoice(
        document_id=document_id,
        operation_id=operation_id,
    )

MCP Server에는 Agent Runtime의 State 관리 코드를 넣지 않는다. Tool은 실제 업무 기능 제공에 집중한다.

11. Orchestrator의 역할

Orchestrator는 현재 State와 사용 가능한 MCP Tool을 보고 다음 행동을 결정한다.

Current State
      +
Available MCP Tools
      +
System Instruction
      ↓
LLM
      ↓
Next Action

예를 들어 System Instruction에는 다음과 같은 규칙을 넣을 수 있다.

You process uploaded business documents.

Use the available tools to analyze the document.

Do not call write tools unless the result has been validated.

If confidence is too low to safely continue,
request human review.

Never retry the same failed action indefinitely.

Finish when the document has been successfully processed.

하지만 Prompt만으로 모든 안전을 보장해서는 안 된다.

Max Steps, Permission, Idempotency, Timeout 같은 제한은 Runtime 코드에서도 적용해야 한다.

12. Decision 구조를 명시적으로 만든다

LLM의 응답을 자유로운 문자열로 받기보다 구조화된 Decision으로 다루는 편이 좋다.

from dataclasses import dataclass
from typing import Any


@dataclass
class AgentDecision:
    action: str

    tool_name: str | None = None
    arguments: dict[str, Any] | None = None

    reason: str | None = None

action은 다음 정도로 제한할 수 있다.

TOOL
FINISH
HUMAN_REVIEW
FAIL

그러면 Runtime은 LLM의 자연어를 직접 해석하는 대신 명확한 상태를 기준으로 동작할 수 있다.

13. Agent Runtime의 기본 Loop

이제 핵심인 Runtime을 만들어보자.

MAX_STEPS = 10


class AgentRuntime:

    async def run(self, state: AgentState):

        state.status = "RUNNING"

        await agent_repository.save(state)

        while state.step < MAX_STEPS:

            decision = await orchestrator.decide(
                state
            )

            if decision.action == "FINISH":

                state.status = "COMPLETED"

                await agent_repository.save(
                    state
                )

                return

            if decision.action == "FAIL":

                state.status = "FAILED"

                await agent_repository.save(
                    state
                )

                return

            if decision.action == "HUMAN_REVIEW":

                await self.pause_for_human(
                    state,
                    decision,
                )

                return

            await self.execute_tool(
                state,
                decision,
            )

        state.status = "MAX_STEPS_EXCEEDED"

        await agent_repository.save(state)

Runtime의 책임이 조금 더 명확해졌다.

Orchestrator
    ↓
무엇을 할지 결정

Runtime
    ↓
그 결정을 실행해도 되는지 통제

MCP
    ↓
실제 Tool 연결

14. Tool 실행 전 Policy를 검사한다

Agent가 Tool을 선택했다고 무조건 실행해서는 안 된다.

예를 들어 다음과 같이 Tool을 분류할 수 있다.

READ_TOOLS = {
    "get_document",
    "extract_document_content",
    "analyze_invoice",
}

WRITE_TOOLS = {
    "create_erp_record",
}

Write Tool에는 추가 검증을 적용한다.

async def validate_tool_call(
    state,
    decision,
):

    if decision.tool_name == "create_erp_record":

        if state.human_result is None:
            raise PermissionError(
                "Human approval is required"
            )

        if state.human_result["action"] != "APPROVE":
            raise PermissionError(
                "Invoice was not approved"
            )

LLM은 create_erp_record를 선택할 수 있다.

하지만 실제 실행 권한은 Runtime이 결정한다.

Tool Selection과 Tool Authorization은 서로 다른 문제다.

15. MCP Tool을 실행한다

개념적인 MCP Client 호출은 다음과 같다.

async def call_mcp_tool(
    tool_name: str,
    arguments: dict,
):

    result = await mcp_client.call_tool(
        tool_name,
        arguments=arguments,
    )

    return result

Runtime에서는 Tool 실행 전후로 Step을 기록한다.

async def execute_tool(
    self,
    state,
    decision,
):

    await validate_tool_call(
        state,
        decision,
    )

    state.step += 1

    step = await agent_repository.start_step(
        run_id=state.run_id,
        step_no=state.step,
        tool_name=decision.tool_name,
        arguments=decision.arguments,
    )

    try:

        result = await call_mcp_tool(
            decision.tool_name,
            decision.arguments,
        )

        await agent_repository.complete_step(
            step.id,
            result=result,
        )

        state.last_tool = decision.tool_name

        self.apply_result(
            state,
            decision.tool_name,
            result,
        )

        await agent_repository.save(state)

    except Exception as e:

        await agent_repository.fail_step(
            step.id,
            error=str(e),
        )

        raise

여기서 agent_repository.save(state)가 Checkpoint 역할을 한다.

16. Tool Result를 State에 반영한다

Tool마다 반환 결과가 다르다.

예를 들어 analyze_invoice 결과가 다음과 같다고 하자.

{
  "document_type": "invoice",
  "vendor": "ABC Corp",
  "amount": 12500000,
  "confidence": 0.58
}

State에 필요한 정보를 반영한다.

def apply_result(
    self,
    state,
    tool_name,
    result,
):

    state.context[
        tool_name
    ] = result

    if tool_name == "analyze_invoice":

        state.document_type = (
            result["document_type"]
        )

        state.confidence = (
            result["confidence"]
        )

전체 Tool Result를 LLM Context에 계속 쌓을 필요는 없다.

DB에는 전체 이력을 보관하고, Orchestrator에는 현재 판단에 필요한 State만 전달하는 방식이 더 효율적이다.

17. Invoice 분석 결과가 0.58이라면

이제 실제 시나리오를 따라가 보자.

Agent는 다음 순서로 Tool을 호출했다.

Step 1
get_document
      ↓
SUCCESS

Step 2
extract_document_content
      ↓
SUCCESS

Step 3
analyze_invoice
      ↓
confidence = 0.58

Orchestrator가 다음 Decision을 반환한다.

{
  "action": "HUMAN_REVIEW",
  "reason": "Invoice analysis confidence is too low"
}

Runtime은 더 이상 Tool을 계속 호출하지 않는다.

Human Review 상태로 전환한다.

18. Human Review Task를 만든다

async def pause_for_human(
    self,
    state,
    decision,
):

    review = await review_service.create(
        run_id=state.run_id,
        document_id=state.document_id,
        reason=decision.reason,
        data=state.context.get(
            "analyze_invoice"
        ),
    )

    state.status = "WAITING_HUMAN"

    state.context["review_id"] = (
        review.id
    )

    await agent_repository.save(state)

여기서 중요한 부분은 마지막이다.

return

Runtime은 종료된다.

Worker도 이 Event 처리를 끝낸다.

Agent Runtime
      ↓
WAITING_HUMAN
      ↓
Checkpoint Save
      ↓
return
      ↓
Worker는 다음 Event 처리

Agent가 몇 시간 동안 살아 있는 것이 아니다.

Agent Run의 상태만 살아 있다.

19. Human Review API

담당자가 Review 화면에서 결과를 확인한다고 해보자.

API는 다음과 같이 만들 수 있다.

from pydantic import BaseModel


class ReviewRequest(BaseModel):
    action: str
    edited_data: dict | None = None


@router.post(
    "/reviews/{review_id}"
)
async def submit_review(
    review_id: str,
    request: ReviewRequest,
):

    review = await review_service.complete(
        review_id=review_id,
        action=request.action,
        edited_data=request.edited_data,
    )

    await event_bus.publish_resume(
        run_id=review.run_id,
        review_id=review.id,
    )

    return {
        "status": "ACCEPTED"
    }

가능한 Action은 예를 들어 다음과 같다.

APPROVE
REJECT
EDIT

20. Resume Event를 Redis Streams에 넣는다

async def publish_resume(
    run_id: str,
    review_id: str,
):

    await redis_client.xadd(
        "agent:events",
        {
            "event": "RESUME",
            "run_id": run_id,
            "review_id": review_id,
        },
    )

Redis에는 다음과 같은 Event가 들어간다.

XADD agent:events *
     event RESUME
     run_id run_123
     review_id review_123

Worker 입장에서는 START와 RESUME 모두 그냥 Event다.

21. Resume 처리

async def resume_agent(event):

    state = await agent_repository.load(
        event["run_id"]
    )

    if state.status != "WAITING_HUMAN":
        return

    review = await review_service.get(
        event["review_id"]
    )

    state.human_result = {
        "action": review.action,
        "edited_data": review.edited_data,
    }

    state.status = "RUNNING"

    await agent_repository.save(state)

    await agent_runtime.run(state)

이제 Agent는 5시간 전의 Python 프로세스가 아니다.

새로운 Worker가 DB에서 State를 읽고 논리적인 Agent Run을 이어간다.

22. REJECT라면 어떻게 할까?

Human Review 결과가 REJECT라면 굳이 LLM에게 다시 물어볼 필요가 없을 수도 있다.

if review.action == "REJECT":

    state.status = "FAILED"

    state.context[
        "failure_reason"
    ] = "Rejected by human"

    await agent_repository.save(state)

    return

이것은 의미적 판단이 아니라 명확한 업무 규칙이다.

코드가 처리하는 것이 더 좋다.

23. EDIT라면 어떻게 할까?

담당자가 Invoice 데이터를 수정했다고 해보자.

{
  "action": "EDIT",
  "edited_data": {
    "vendor": "ABC Corporation",
    "amount": 12450000
  }
}

이 경우 State에 수정 결과를 넣고 Agent에게 다시 판단을 맡길 수 있다.

if review.action == "EDIT":

    state.context[
        "human_edited_invoice"
    ] = review.edited_data

Agent는 다음 단계에서 다시 Validation Tool을 호출하거나 ERP 등록을 선택할 수 있다.

24. APPROVE라면 ERP 등록

승인이 완료되면 다음 Tool을 호출할 수 있다.

Human APPROVE
      ↓
Agent Resume
      ↓
create_erp_record

하지만 ERP 등록은 Write Tool이다.

반복 실행에 안전해야 한다.

25. ERP Tool에 Idempotency를 적용한다

operation_id를 Agent Run과 업무 작업을 조합해서 만든다.

operation_id = (
    f"{state.run_id}:create_erp_record"
)

MCP Tool 호출은 다음과 같다.

{
  "document_id": "doc_123",
  "operation_id": "run_123:create_erp_record"
}

ERP Service에서는 이미 처리한 Operation인지 확인한다.

def create_invoice(
    document_id: str,
    operation_id: str,
):

    existing = operation_repository.find(
        operation_id
    )

    if existing:
        return existing.result

    result = erp_client.create_invoice(
        document_id
    )

    operation_repository.save(
        operation_id=operation_id,
        result=result,
    )

    return result

Worker가 ERP 등록 직후 죽더라도 같은 operation_id로 다시 실행하면 중복 등록을 막을 수 있다.

26. Redis Streams에서도 장애 복구를 생각해야 한다

Consumer가 메시지를 읽은 뒤 XACK하기 전에 죽을 수 있다.

XREADGROUP
     ↓
Agent 실행
     ↓
Worker Crash
     ↓
XACK 못함

이 메시지는 Pending 상태로 남는다.

따라서 운영 환경에서는 Pending Entry를 감시하고 일정 시간 이상 처리되지 않은 메시지를 다른 Worker가 Claim하는 전략이 필요하다.

개념적으로는 다음과 같다.

Pending Message
      ↓
Idle Time > Threshold
      ↓
Claim
      ↓
Another Worker
      ↓
Resume Processing

Redis Streams의 전달 보장과 Agent Tool의 Idempotency는 함께 생각해야 한다.

Queue가 메시지를 다시 전달할 수 있기 때문이다.

27. Runtime Retry와 Tool Retry를 구분한다

OCR API가 일시적으로 실패하는 것은 Tool 내부에서 Retry할 수 있다.

Technical Failure
      ↓
Tool Retry

반면 Invoice 분석 신뢰도가 낮아 다른 방법을 선택하는 것은 Agent의 판단이다.

Semantic Failure
      ↓
Agent Decision

Runtime에서는 Tool의 결과를 보고 다음과 같이 처리할 수 있다.

if result.get("retryable"):

    state.retry_count += 1

    if state.retry_count > 3:
        state.status = "FAILED"

다만 네트워크 재시도와 의미적 재시도를 같은 Counter로 관리하지 않는 편이 더 명확하다.

28. Loop Detection

Max Steps만으로도 무한 실행은 막을 수 있지만 반복 패턴을 감지하면 더 빨리 중단할 수 있다.

extract_document_content
run_ocr
extract_document_content
run_ocr

최근 Tool History를 확인한다.

def has_repeating_pattern(
    history: list[str],
) -> bool:

    if len(history) < 4:
        return False

    last_four = history[-4:]

    return (
        last_four[0] == last_four[2]
        and
        last_four[1] == last_four[3]
    )

Loop가 감지되면 Human Review로 보내거나 실패 처리할 수 있다.

29. Agent Run을 어떻게 관찰할까?

관리 화면에서는 최소한 다음 정도를 볼 수 있으면 좋다.

Run ID
Document
Status
Current Step
Last Tool
Started At
Updated At
LLM Calls
Tool Calls
Token Usage
Estimated Cost
Human Review
Error

하나의 Run을 클릭하면 Timeline을 보여줄 수 있다.

10:00:01 START

10:00:02 get_document
         SUCCESS

10:00:03 extract_document_content
         SUCCESS

10:00:05 analyze_invoice
         confidence = 0.58

10:00:06 HUMAN_REVIEW
         WAITING

15:14:22 HUMAN_APPROVE

15:14:23 RESUME

15:14:25 create_erp_record
         SUCCESS

15:14:26 COMPLETED

Agent 시스템에서는 이런 Timeline이 디버깅에 특히 유용하다.

30. 비용도 Run 단위로 기록한다

LLM을 여러 번 호출하는 Agent는 일반 API보다 비용 구조가 복잡하다.

agent_usage

run_id
step_no
model
input_tokens
output_tokens
cost
latency_ms

그러면 다음과 같은 지표를 계산할 수 있다.

Average Cost per Run

Average LLM Calls per Run

Average Tool Calls per Run

Human Review Rate

Completion Rate

Average Steps

P95 Run Duration

Agent가 유연해졌지만 고정 Workflow보다 비용이 지나치게 증가하고 있지는 않은지 확인할 수 있다.

31. 전체 실행 흐름을 다시 따라가 보자

이제 처음부터 끝까지 한 번에 연결해보자.

1단계 — Upload

User
  ↓
POST /documents
  ↓
Object Storage
  ↓
Document Record
  ↓
Agent Run 생성

State:

{
  "run_id": "run_123",
  "document_id": "doc_123",
  "status": "CREATED",
  "step": 0
}

2단계 — START Event

XADD agent:events *
     event START
     run_id run_123

Worker가 Event를 읽는다.

Redis Streams
      ↓
Agent Worker
      ↓
Load State
      ↓
Agent Runtime

3단계 — Document 처리

get_document
      ↓
extract_document_content
      ↓
analyze_invoice

결과:

{
  "vendor": "ABC Corp",
  "amount": 12500000,
  "confidence": 0.58
}

4단계 — Human Review

confidence = 0.58
      ↓
HUMAN_REVIEW
      ↓
Review Task 생성
      ↓
Checkpoint
      ↓
WAITING_HUMAN
      ↓
Runtime 종료

이 시점에 실행 중인 Agent 프로세스는 없다.

DB에 논리적인 Agent Run만 남아 있다.

5단계 — 5시간 뒤 승인

Human
  ↓
APPROVE
  ↓
POST /reviews/review_123

Resume Event가 발생한다.

XADD agent:events *
     event RESUME
     run_id run_123

6단계 — Resume

Agent Worker
      ↓
Load State
      ↓
Load Human Result
      ↓
RUNNING
      ↓
Agent Runtime

7단계 — ERP 등록

create_erp_record
      ↓
operation_id 확인
      ↓
ERP API
      ↓
SUCCESS

8단계 — 완료

{
  "run_id": "run_123",
  "document_id": "doc_123",
  "status": "COMPLETED",
  "last_tool": "create_erp_record"
}

최종 Timeline은 다음과 같다.

Invoice Upload
      ↓
Agent Start
      ↓
get_document
      ↓
extract_document_content
      ↓
analyze_invoice
      ↓
confidence = 0.58
      ↓
Human Review
      ↓
Checkpoint
      ↓
WAITING_HUMAN

      ... 5시간 후 ...

Human APPROVE
      ↓
Resume Event
      ↓
Load Checkpoint
      ↓
Agent Resume
      ↓
create_erp_record
      ↓
COMPLETED

32. 이 구조에서 Agent가 실제로 판단하는 것은 생각보다 많지 않다

전체 시스템을 보면 Agent가 모든 것을 결정하는 것처럼 보일 수 있다.

하지만 실제로 Agent가 판단할 영역을 다시 분리해보면 그렇지 않다.

코드가 담당하는 영역:

File Size Limit
Authentication
Authorization
State Transition
Max Steps
Timeout
Retry Limit
Idempotency
Consumer Recovery
Unique Constraint
Human Approval Policy

Agent가 담당할 수 있는 영역:

Document Classification
Tool Selection
OCR 필요 여부
Alternative Analysis Strategy
Semantic Validation
Additional Analysis 필요 여부
Human Review 필요 여부

이 구분이 중요하다.

LLM이 잘하는 것은 모호한 상황에서 의미를 해석하고 다음 행동을 선택하는 것이다.

반면 시스템의 안전성과 일관성을 보장하는 것은 코드가 더 잘한다.

33. “Agent가 알아서 한다”는 표현을 조심해야 한다

Agent 시스템을 설명할 때 흔히 다음과 같이 표현한다.

“Agent가 알아서 Tool을 선택하고 업무를 처리한다.”

개념적으로는 맞다.

하지만 운영 시스템에서는 조금 더 정확하게 표현하는 편이 좋다.

Agent
    ↓
허용된 범위 안에서
    ↓
사용 가능한 Tool 중
    ↓
현재 Context에 적합한 행동을 제안한다
    ↓
Runtime Policy 검증
    ↓
실행

즉 Agent의 자유는 Runtime이 허용한 경계 안에서의 자유다.

이 경계가 없다면 Agent는 자동화 시스템이 아니라 예측하기 어려운 프로그램이 될 수 있다.

34. MCP를 사용하는 이유도 다시 명확해진다

이번 시스템에서 MCP가 Agent Runtime을 만들어준 것은 아니다.

Redis Streams를 대신한 것도 아니다.

State Store를 제공한 것도 아니다.

Human Review를 구현해준 것도 아니다.

MCP가 담당한 것은 명확하다.

Agent
  ↓
"What can I do?"
  ↓
MCP
  ↓
Available Capabilities

예를 들어 기존 백엔드에 다음 기능이 있었다.

Document Service
OCR Service
Invoice Analyzer
ERP Service
Notification Service

MCP를 통해 이것을 Agent가 사용할 수 있는 Capability로 제공했다.

get_document
run_ocr
analyze_invoice
create_erp_record
send_notification

MCP의 가치는 기존 백엔드의 능력을 Agent가 사용할 수 있는 공통 인터페이스로 연결하는 데 있다.

35. 처음부터 모든 것을 MCP로 만들 필요도 없다

기존 시스템에 REST API가 있다면 MCP Tool 내부에서 REST API를 호출해도 된다.

Agent
  ↓
MCP Tool
  ↓
REST API
  ↓
Existing Service

같은 프로세스 안의 Service Layer를 직접 호출할 수도 있다.

Agent
  ↓
MCP Tool
  ↓
Service Layer
  ↓
Repository

중요한 것은 기술을 많이 사용하는 것이 아니다.

기존 시스템의 경계를 유지하면서 Agent에게 필요한 Capability를 제공하는 것이다.

36. 실제 서비스로 확장한다면

이번 예제를 Production 수준으로 확장한다면 다음 항목을 추가로 고려할 수 있다.

Authentication / Authorization

Tenant Isolation

Tool Permission

Secret Management

Distributed Lock

Pending Message Recovery

Dead Letter Queue

Rate Limit

Circuit Breaker

Structured Logging

Tracing

Metrics

LLM Cost Tracking

Prompt / Tool Versioning

Agent Evaluation

Human Review SLA

Audit Log

특히 Multi-Tenant SaaS라면 모든 Tool 호출에 Tenant Context를 명확하게 전달하고 서버 측에서 다시 검증해야 한다.

Agent가 전달한 tenant_id를 그대로 신뢰해서는 안 된다.

37. Agent Version도 기록하는 것이 좋다

Agent Prompt와 Tool Description이 변경되면 같은 문서에서도 실행 결과가 달라질 수 있다.

따라서 Run에 다음 정보를 기록하는 것이 좋다.

{
  "agent_version": "1.3.0",
  "prompt_version": "invoice-v4",
  "toolset_version": "2026-09-01",
  "model": "example-model"
}

나중에 품질이 갑자기 달라졌을 때 어떤 변경 때문인지 추적하기 쉬워진다.

Agent도 결국 운영되는 Software다.

Versioning이 필요하다.

38. 테스트는 어떻게 할까?

Agent 시스템이라고 테스트를 LLM에게 맡길 수는 없다.

계층별로 나누는 것이 좋다.

Tool Test

Input
 ↓
Tool
 ↓
Expected Output

Tool 자체는 가능한 한 Deterministic하게 테스트한다.

Runtime Test

LLM Decision을 Mock으로 고정할 수 있다.

Decision 1 = get_document
Decision 2 = analyze_invoice
Decision 3 = HUMAN_REVIEW

그 상태에서 Runtime이 올바르게 State를 전환하는지 확인한다.

Resume Test

WAITING_HUMAN
      ↓
APPROVE Event
      ↓
RUNNING
      ↓
COMPLETED

Failure Test

Tool Timeout
Worker Crash
Duplicate Event
Duplicate Write
Redis Redelivery
Human Review Expired

Happy Path보다 이런 테스트가 운영 환경에서는 더 중요할 수 있다.

39. Agent Evaluation도 필요하다

Runtime이 안정적이라고 Agent의 판단이 좋은 것은 아니다.

다음 질문은 별도의 Evaluation 영역이다.

올바른 Tool을 선택했는가?

불필요한 Tool을 호출하지 않았는가?

Human Review를 너무 자주 요청하지 않는가?

잘못된 문서를 Invoice로 분류하지 않는가?

비용 대비 충분히 좋은 결과를 내는가?

따라서 두 가지 품질을 구분할 필요가 있다.

Runtime Reliability
        +
Agent Decision Quality

둘 다 좋아야 실제 업무에서 사용할 수 있다.

40. 최종 아키텍처

이번 시리즈에서 만든 구조를 마지막으로 한 번 정리해보자.

                         ┌──────────────────┐
                         │       User       │
                         └────────┬─────────┘
                                  │
                               Upload
                                  │
                                  ↓
                         ┌──────────────────┐
                         │     FastAPI      │
                         └────────┬─────────┘
                                  │
                     ┌────────────┴────────────┐
                     ↓                         ↓
              Object Storage             Redis Streams
                                               │
                                               ↓
                                         Agent Worker
                                               │
                                               ↓
                                        Agent Runtime
                                  ┌────────────┼────────────┐
                                  ↓            ↓            ↓
                               State      Orchestrator   Checkpoint
                                               │
                                               ↓
                                          LLM Decision
                                               │
                                               ↓
                                           MCP Client
                                               │
                                               ↓
                                           MCP Server
                                               │
                             ┌─────────────────┼─────────────────┐
                             ↓                 ↓                 ↓
                         Document          Analysis          Business
                           Tools             Tools             Tools
                             │                 │                 │
                             └─────────────────┼─────────────────┘
                                               ↓
                                          Service Layer
                                               │
                              ┌────────────────┼────────────────┐
                              ↓                ↓                ↓
                           Storage          Database       External API
                                                                 │
                                                                 ↓
                                                               ERP

Human Review
     │
     └──────────→ Resume Event ──────────→ Redis Streams

이 구조에서 Agent는 시스템 전체가 아니다.

Agent는 기존 백엔드 위에 추가된 의사결정 계층이다.

41. 이 시리즈에서 말하고 싶었던 것

처음의 질문은 단순했다.

파일이 업로드되면 Agent가 깨어나 알아서 분석하고 저장하도록 만들 수 없을까?

가능하다.

하지만 실제 시스템을 만들어보면 중요한 것은 “Agent가 얼마나 똑똑한가”만이 아니다.

Event를 어떻게 전달할 것인가?

State를 어디에 저장할 것인가?

실패하면 어떻게 복구할 것인가?

중복 실행을 어떻게 막을 것인가?

사람이 필요하면 어떻게 멈출 것인가?

몇 시간 뒤 어떻게 다시 시작할 것인가?

Agent에게 어디까지 권한을 줄 것인가?

무엇을 했는지 어떻게 추적할 것인가?

결국 우리가 다시 만나게 되는 것은 익숙한 백엔드 엔지니어링 문제들이다.

Queue, State, Retry, Idempotency, Timeout, Authorization, Observability, Recovery.

Agent가 등장했다고 이 문제들이 사라지는 것은 아니다.

오히려 Agent의 실행 경로가 동적으로 변하기 때문에 더 중요해진다.

42. 가장 중요한 원칙

이 시리즈를 한 문장으로 정리한다면 다음과 같다.

Agent에게 판단을 맡기되, 실행의 통제권까지 모두 넘기지는 않는다.

코드가 잘하는 것은 코드에게 맡긴다.

Permission
Timeout
Retry Limit
Idempotency
State Transition
Validation

Agent가 잘하는 것은 Agent에게 맡긴다.

Semantic Understanding
Tool Selection
Contextual Decision
Alternative Strategy
Human Review 판단

그리고 MCP가 그 둘 사이에서 기존 백엔드의 Capability를 Agent에게 연결한다.

Backend Capability
        ↓
       MCP
        ↓
      Agent

이렇게 보면 Agent 시스템은 기존 백엔드와 완전히 다른 새로운 세계가 아니다.

우리가 이미 알고 있는 Backend Architecture 위에 LLM 기반 의사결정 계층을 추가하는 것에 가깝다.

시리즈를 마치며

Part 1에서는 Worker에서 Agent Orchestrator로 넘어가는 이유를 살펴봤다.

Part 2에서는 Python으로 MCP Tool을 만들었다.

Part 3에서는 Agent Loop, State, Retry, Checkpoint, Human-in-the-Loop을 통해 운영 가능한 Agent Runtime을 설계했다.

그리고 이번 Part 4에서는 그것들을 하나로 연결했다.

Part 1
Why Agent?

        ↓

Part 2
How to build MCP Tools?

        ↓

Part 3
How to run Agents safely?

        ↓

Part 4
How to connect everything?

처음에는 단순한 Worker였다.

File
 ↓
Worker
 ↓
Result

마지막에는 다음 구조가 되었다.

Event
 ↓
Agent Runtime
 ↓
Decision
 ↓
MCP Tool
 ↓
Existing Backend
 ↓
State / Human / Recovery

Agent를 실제 업무에 연결하는 순간부터 중요한 것은 멋진 Demo가 아니다.

실패해도 복구되고, 중복 실행에도 안전하고, 사람이 개입할 수 있으며, 어떤 판단과 실행이 있었는지 추적할 수 있는 시스템을 만드는 것이다.

그 위에서 Agent의 판단 능력이 비로소 실제 비즈니스의 자동화 능력이 된다.

Agent Loop, 상태 관리, Retry 그리고 Human-in-the-Loop

1부에서는 Worker에서 Agent Orchestrator로 확장하는 이유를 살펴봤고, 2부에서는 Python 백엔드 기능을 MCP Tool로 제공했다.

이제 Agent에게 get_document, extract_document_content, run_ocr, analyze_document, save_analysis, request_human_review 같은 능력이 생겼다.

그렇다면 Agent에게 “이 문서를 알아서 처리해”라고 하면 끝일까?

개발 데모에서는 가능하다. 하지만 운영 환경에서는 여기서부터 진짜 문제가 시작된다.

같은 Tool을 반복 호출하면?
잘못된 Tool을 선택하면?
Tool이 실패하면?
Worker가 죽으면?
이미 저장한 데이터를 다시 저장하면?
사람의 승인이 필요하면?
5시간 뒤 승인되면 어디서부터 다시 시작할까?

MCP Tool을 만드는 것과 운영 가능한 Agent 시스템을 만드는 것은 다른 문제다.

1. Agent의 본질은 Loop다

가장 단순한 Agent 실행 구조는 다음과 같다.

        ┌──────────────────┐
        │                  │
        ↓                  │
   LLM Decision            │
        ↓                  │
     Tool Call             │
        ↓                  │
    Tool Result ───────────┘

현재 State와 Tool 목록을 LLM에게 전달하고, LLM이 다음 Tool을 선택하고, 실행 결과를 다시 State에 넣는다.

async def run_agent(state):
    while True:
        decision = await llm.decide(
            state=state,
            tools=available_tools,
        )

        if decision.type == "finish":
            return state

        result = await call_tool(
            name=decision.tool_name,
            arguments=decision.arguments,
        )

        state.add_tool_result(
            tool_name=decision.tool_name,
            result=result,
        )

문제는 while True다. 실행 경로가 코드에 고정되어 있지 않기 때문에 Runtime이 Agent의 행동을 제한해야 한다.

2. 반드시 종료 조건이 있어야 한다

COMPLETED
FAILED
WAITING_HUMAN
MAX_STEPS_EXCEEDED
TIMEOUT

예를 들어 최대 Step을 제한한다.

MAX_STEPS = 10

async def run_agent(state):
    while state.step < MAX_STEPS:
        decision = await decide_next_action(state)

        if decision.type == "finish":
            state.status = "COMPLETED"
            return state

        result = await execute_tool(decision)
        state.add_result(result)
        state.step += 1

    state.status = "MAX_STEPS_EXCEEDED"
    return state

Agent에게 판단의 자유를 주더라도 실행 범위까지 무제한으로 주어서는 안 된다.

3. Max Steps만으로 충분하지 않다

다음처럼 같은 패턴을 반복할 수도 있다.

extract_document_content
        ↓
run_ocr
        ↓
extract_document_content
        ↓
run_ocr
        ↓
...

따라서 Loop Detection도 필요하다.

중요한 것은 Agent가 계속 행동하고 있다는 사실과 문제를 해결하고 있다는 사실은 다르다는 점이다.

4. Tool 실패와 Agent 실패는 다르다

Tool Failure
     ↓
Recoverable?
   ┌────┴────┐
   ↓         ↓
  YES        NO
   ↓         ↓
Retry /     Agent
Alternative FAILED

예를 들어 일시적인 OCR 오류는 복구 가능할 수 있다.

{
  "success": false,
  "reason": "OCR_TEMPORARY_ERROR",
  "retryable": true
}

지원하지 않는 파일 형식은 재시도해도 의미가 없을 수 있다.

{
  "success": false,
  "reason": "UNSUPPORTED_FILE_FORMAT",
  "retryable": false
}

5. Retry는 Agent가 할까, Tool이 할까?

네트워크 Timeout이나 일시적인 5xx 오류까지 LLM에게 판단시킬 필요는 없다.

async def run_ocr(document_id):
    for attempt in range(3):
        try:
            return await ocr_client.analyze(document_id)
        except TemporaryError:
            if attempt == 2:
                raise
            await asyncio.sleep(2 ** attempt)

반면 분석 결과의 신뢰도가 낮아 다른 Analyzer나 Human Review를 선택하는 것은 의미적 판단이다.

Technical Retry
      ↓
Tool / Service Layer

Semantic Retry
      ↓
Agent / Orchestrator

6. Timeout도 계층별로 나눈다

HTTP Timeout
LLM Timeout
Tool Timeout
Agent Step Timeout
Agent Run Timeout
Human Review Timeout

Human Review는 일반 Timeout과 다르다. 몇 시간 동안 프로세스를 붙잡아 두는 대신 Workflow를 Pause하는 편이 좋다.

7. Agent에게 State가 필요한 이유

{
  "run_id": "run_123",
  "document_id": "doc_123",
  "status": "RUNNING",
  "step": 3,
  "last_tool": "analyze_document",
  "document_type": "invoice",
  "confidence": 0.58,
  "retry_count": 0
}

Agent Runtime은 이 State를 기준으로 다음 행동을 결정한다.

8. State와 LLM Context는 같은 것이 아니다

LLM Context
- System Prompt
- Tool Definitions
- Previous Tool Results
- Current Task

Runtime State
- run_id
- status
- step
- retry_count
- last_tool
- checkpoint
- document_id

LLM Context는 모델의 판단을 위한 정보이고, Runtime State는 시스템이 Agent 실행을 관리하고 복구하기 위한 정보다.

9. State는 메모리에만 두면 안 된다

Worker가 죽어도 복구하려면 중요한 State를 외부 저장소에 기록해야 한다.

agent_runs
- run_id
- document_id
- status
- current_step
- last_tool
- retry_count
- created_at
- updated_at

agent_steps
- id
- run_id
- step_no
- tool_name
- input
- output
- status
- started_at
- finished_at
- error

10. Checkpoint를 만든다

Tool Execute
     ↓
Tool Result
     ↓
Save Checkpoint
     ↓
Next Decision

Worker가 죽으면 새 Worker가 마지막 Checkpoint를 불러와 Resume할 수 있다.

Worker Crash
     ↓
New Worker
     ↓
Load run_123
     ↓
Last Checkpoint
     ↓
Resume

11. Resume은 생각보다 어렵다

다음 상황을 보자.

Step 5
save_analysis
      ↓
Database INSERT 성공
      ↓
Worker Crash
      ↓
Checkpoint 저장 실패

DB에는 데이터가 있지만 State에는 성공 기록이 없다. 새 Worker는 save_analysis를 다시 호출할 수 있다.

그래서 Write Tool의 Idempotency가 중요하다.

12. Agent 시스템의 Idempotency

예를 들어 operation_id를 사용한다.

{
  "operation_id": "run_123_step_5",
  "document_id": "doc_123"
}

DB에서 operation_id를 Unique하게 관리하면 재호출 시 이전 결과를 반환할 수 있다.

First Call
run_123_step_5
      ↓
INSERT
      ↓
SUCCESS

Second Call
run_123_step_5
      ↓
Already Processed
      ↓
Return Previous Result

13. Human-in-the-Loop가 들어오면 구조가 달라진다

Invoice 분석 결과가 다음과 같다고 해보자.

{
  "document_type": "invoice",
  "confidence": 0.58,
  "amount": 12500000
}

Agent는 Human Review를 선택한다.

analyze_invoice
      ↓
confidence = 0.58
      ↓
request_human_review

사람이 10초 뒤 응답할지, 5시간 뒤 응답할지 알 수 없다. Worker를 계속 실행한 채 기다리는 것은 비효율적이다.

14. Human Review에서는 Agent를 Pause한다

Agent
  ↓
request_human_review
  ↓
Create Review Task
  ↓
Save Checkpoint
  ↓
status = WAITING_HUMAN
  ↓
Worker 종료

State는 다음처럼 저장할 수 있다.

{
  "run_id": "run_123",
  "document_id": "doc_123",
  "status": "WAITING_HUMAN",
  "current_step": 5,
  "last_tool": "request_human_review",
  "confidence": 0.58
}

이 상태에서는 Agent 프로세스가 존재할 필요가 없다.

15. 사람이 승인하면 Event가 Agent를 다시 깨운다

5시간 뒤 담당자가 승인했다고 해보자.

Human
  ↓
Approve
  ↓
Review API
  ↓
Event

Redis Streams를 사용한다면 다음과 같은 Resume Event를 만들 수 있다.

XADD agent:resume *
     run_id run_123
     action approved

Redis Stream
      ↓
Agent Worker
      ↓
Load run_123
      ↓
Resume Agent

파일 업로드 Event가 Agent를 처음 깨웠듯이 Human Approval Event가 Agent를 다시 깨운다.

16. Pause와 Resume을 코드로 생각해보자

async def run_agent(state):
    while True:
        decision = await decide_next_action(state)

        if decision.type == "human_review":
            await create_review_task(state)

            state.status = "WAITING_HUMAN"
            await save_checkpoint(state)

            return

        result = await execute_tool(decision)

        state.add_result(result)
        await save_checkpoint(state)

사람의 응답이 들어오면 별도 Handler가 실행된다.

async def resume_agent(run_id, human_result):
    state = await load_state(run_id)

    state.human_result = human_result
    state.status = "RUNNING"

    await save_checkpoint(state)
    await run_agent(state)

핵심은 await human_response()로 몇 시간 동안 기다리지 않는다는 것이다.

State를 저장하고 프로세스를 종료한 뒤 Event가 들어오면 다시 실행한다.

17. Human Review에도 Timeout이 필요하다

사람이 영원히 응답하지 않을 수도 있다.

{
  "review_id": "review_123",
  "run_id": "run_123",
  "status": "WAITING",
  "expires_at": "2026-09-14T12:00:00"
}

만료되면 EXPIRED로 바꾸거나 담당자에게 재알림을 보낼 수 있다.

WAITING_HUMAN
      ↓
TTL / Deadline
      ↓
Expired?
 ┌────┴────┐
 ↓         ↓
NO        YES
 ↓         ↓
Wait    Re-notify / EXPIRED

18. Human Review 결과도 구조화해야 한다

단순히 “승인”만 있는 것은 아니다.

APPROVE
REJECT
EDIT

EDIT라면 사람이 수정한 데이터도 함께 반환할 수 있다.

{
  "action": "EDIT",
  "data": {
    "vendor": "OpenAI Korea",
    "amount": 12500000
  }
}

Agent는 Human Result를 새로운 State로 받아 다음 작업을 이어간다.

19. Agent가 Resume될 때 LLM을 다시 호출해야 할까?

항상 그럴 필요는 없다.

사람의 승인 이후 다음 행동이 명확하다면 코드가 바로 실행할 수도 있다.

Human APPROVE
      ↓
Policy
      ↓
create_erp_record

반대로 사람이 수정한 내용에 따라 추가 검증이 필요하다면 Agent에게 다시 판단을 맡길 수 있다.

Human EDIT
      ↓
Agent
      ↓
Validate Again?
      ↓
Next Tool

여기에서도 같은 원칙이 적용된다.

결정적인 규칙은 코드가 처리하고, 의미적 판단이 필요한 지점에서 Agent를 사용한다.

20. Agent의 상태 머신을 명시적으로 만들어보자

Agent를 자유로운 Loop로만 생각하지 않고 상태 머신으로 보는 것도 유용하다.

CREATED
   ↓
RUNNING
   ├──→ COMPLETED
   ├──→ FAILED
   ├──→ WAITING_HUMAN
   │         ↓
   │       RESUME
   │         ↓
   └────── RUNNING

예를 들어 다음 상태를 정의할 수 있다.

CREATED
RUNNING
WAITING_HUMAN
COMPLETED
FAILED
EXPIRED
CANCELLED

상태 전이를 명확하게 정의하면 운영과 장애 복구가 쉬워진다.

21. Tool 실행과 Agent Decision을 모두 기록한다

Tool 실행 기록뿐 아니라 Agent가 어떤 결정을 내렸는지도 추적할 필요가 있다.

run_123

Step 1
Decision: get_document
Result: SUCCESS

Step 2
Decision: extract_document_content
Result: SUCCESS

Step 3
Decision: analyze_invoice
Result: confidence 0.58

Step 4
Decision: request_human_review
Result: WAITING

5 hours later

Step 5
Human: APPROVE

Step 6
Decision: create_erp_record
Result: SUCCESS

이런 실행 이력은 디버깅, 감사, 비용 분석, Agent 품질 평가에 모두 도움이 된다.

22. Observability에서 봐야 할 것

일반 API의 latency와 error rate만으로는 충분하지 않다.

Agent Run Count
Completion Rate
Failure Rate
Average Steps
Tool Calls per Run
LLM Calls per Run
Average Run Duration
Human Review Rate
Retry Rate
Loop Detection Count
Tool Error Rate
Token Usage
Cost per Run

예를 들어 Human Review 비율이 지나치게 높다면 Agent Prompt나 Analyzer 품질에 문제가 있을 수 있다.

평균 Step이 갑자기 증가한다면 Agent가 불필요한 Tool을 호출하기 시작했을 수도 있다.

23. Agent의 비용도 Runtime 문제다

Agent Loop에서는 LLM 호출이 여러 번 발생할 수 있다.

Decision 1 → LLM
Tool
Decision 2 → LLM
Tool
Decision 3 → LLM
Tool
Decision 4 → LLM

따라서 Run 단위로 다음을 기록하는 것이 좋다.

input_tokens
output_tokens
llm_calls
tool_calls
model
total_cost

Agent가 더 유연하다는 이유만으로 고정 Workflow보다 훨씬 많은 비용을 사용하고 있지는 않은지 확인해야 한다.

24. 모든 Tool Result를 LLM Context에 계속 넣어야 할까?

Agent가 오래 실행되면 Context가 계속 커질 수 있다.

Step 1 Result
Step 2 Result
Step 3 Result
...
Step 30 Result

Runtime State와 LLM Context를 분리하면 이 문제를 다루기 쉬워진다.

DB에는 전체 이력을 보관하되 LLM에는 현재 판단에 필요한 요약된 State만 전달할 수 있다.

Full History
    ↓
Database

Relevant State
    ↓
LLM Context

이것은 비용과 Context Window 관리에도 중요하다.

25. MCP Server는 Agent Runtime이 아니다

역할을 다시 구분해보자.

Agent Runtime
- State
- Loop
- Retry
- Pause / Resume
- Checkpoint

Orchestrator
- Next Action 결정
- Tool 선택

MCP
- Tool 연결
- Tool Schema
- Tool 호출

Tool
- 실제 업무 수행

MCP가 Agent의 상태를 저장하거나 Workflow를 복구해주는 것은 아니다.

MCP는 Capability Interface이고, Agent Runtime은 실행 엔진이다.

이 둘을 구분해야 아키텍처가 명확해진다.

26. 전체 Runtime 구조

                    Event
                      │
                      ↓
                 Agent Worker
                      │
                      ↓
                Load / Create State
                      │
                      ↓
                 Agent Runtime
                      │
              ┌───────┴───────┐
              ↓               ↓
         Orchestrator       State Store
              │
              ↓
          LLM Decision
              │
              ↓
           MCP Client
              │
              ↓
           MCP Server
              │
              ↓
             Tool
              │
              ↓
          Service Layer
              │
              ↓
        External Systems

Tool Result가 돌아오면 Checkpoint를 저장하고 다음 Decision을 수행한다.

27. Invoice 예제로 전체 흐름을 따라가 보자

사용자가 Invoice PDF를 업로드한다.

Invoice Upload
      ↓
FastAPI
      ↓
Object Storage
      ↓
Redis Stream
      ↓
Agent Worker

Agent Run을 생성한다.

{
  "run_id": "run_123",
  "document_id": "doc_123",
  "status": "RUNNING",
  "step": 0
}

Agent가 문서를 조회한다.

Step 1
get_document
      ↓
SUCCESS

내용을 추출한다.

Step 2
extract_document_content
      ↓
SUCCESS

Invoice를 분석한다.

Step 3
analyze_invoice
      ↓
confidence = 0.58

신뢰도가 낮다.

Step 4
request_human_review
      ↓
WAITING_HUMAN

Checkpoint를 저장하고 Worker는 종료된다.

28. 5시간 뒤

담당자가 검토 화면에서 내용을 확인한다.

금액과 거래처가 맞다.

Human
  ↓
APPROVE

Resume Event가 발생한다.

XADD agent:resume *
     run_id run_123
     action APPROVE

새 Worker가 State를 읽는다.

Load run_123
      ↓
status = WAITING_HUMAN
      ↓
human_result = APPROVE
      ↓
status = RUNNING

이제 다음 작업을 실행한다.

create_erp_record
      ↓
SUCCESS

최종 State를 저장한다.

{
  "run_id": "run_123",
  "document_id": "doc_123",
  "status": "COMPLETED",
  "last_tool": "create_erp_record"
}

전체 흐름은 다음과 같다.

Invoice Upload
      ↓
Agent Start
      ↓
Extract
      ↓
Analyze
      ↓
Confidence = 0.58
      ↓
Human Review
      ↓
Agent Pause

      ... 5시간 후 ...

Human Approve
      ↓
Resume Event
      ↓
Agent Resume
      ↓
ERP Registration
      ↓
Completed

이제 Agent는 단순히 LLM이 Tool 몇 개를 호출하는 프로그램이 아니다.

29. 실제 운영에서는 Agent를 “오래 실행되는 함수”로 만들지 않는다

다음과 같은 구현은 피하는 편이 좋다.

async def process_invoice():
    result = await analyze()

    human_result = await wait_for_human()

    await register_erp(human_result)

wait_for_human()이 5시간 동안 Worker를 붙잡고 있을 수 있기 때문이다.

대신 실행을 작은 구간으로 나눈다.

Execution Segment 1
Upload → Analyze → Human Review
                 ↓
               PAUSE

Execution Segment 2
Human Event → Resume → ERP

Agent Run이라는 논리적 실행은 계속되지만 실제 프로세스는 필요할 때만 살아난다.

30. Queue와 Agent는 경쟁 관계가 아니다

Agent를 도입했다고 Redis Streams나 SQS가 필요 없어지는 것은 아니다.

오히려 Event Driven Architecture와 잘 결합된다.

Upload Event
     ↓
Agent Start

Human Event
     ↓
Agent Resume

Retry Event
     ↓
Agent Retry

Timeout Event
     ↓
Agent Expire

Queue는 언제 실행할 것인가를 전달하고 Agent는 실행된 뒤 무엇을 할 것인가를 판단한다.

31. 어디까지 Agent에게 맡겨야 할까?

다음은 코드가 처리하는 편이 좋다.

Permission Check
File Size Limit
Retry Count Limit
Unique Constraint
Timeout
State Transition Validation
Idempotency

다음은 Agent가 개입할 가치가 있다.

Document Classification
Tool Selection
Alternative Analysis Strategy
Semantic Validation
Additional Information 필요 여부
Human Review 필요 여부

Agent를 많이 사용하는 것이 좋은 아키텍처는 아니다.

불확실성이 있는 곳에만 Agent를 넣는 것이 더 중요하다.

32. Agent Runtime에서 최소한 필요한 안전장치

운영 시스템이라면 최소한 다음을 고려해야 한다.

Max Steps
Loop Detection
Tool Timeout
Agent Run Timeout
Retry Policy
Idempotency
State Persistence
Checkpoint
Tool Permission
Human Approval
Audit Log
Observability
Cost Tracking

이것들이 없으면 Agent는 똑똑한 자동화 도구가 아니라 예측하기 어려운 백엔드 프로세스가 될 수 있다.

33. 결국 Agent는 새로운 형태의 Workflow Runtime이다

전통적인 Workflow는 실행 경로가 미리 정해져 있다.

A → B → C → D

Agent Workflow는 일부 경로가 런타임에 결정된다.

             ┌→ B → D
             │
A → Agent ───┼→ C → E
             │
             └→ Human → F

하지만 운영 시스템의 관점에서는 여전히 State, Retry, Timeout, Checkpoint, Resume, Audit이 필요하다.

즉 Agent가 기존 Workflow Engine의 문제를 없애는 것이 아니다.

오히려 Workflow Runtime 위에 LLM 기반 의사결정을 추가한다고 보는 편이 정확하다.

34. 1부부터 다시 연결해보자

1부의 시작은 아주 단순했다.

File Upload
    ↓
Worker
    ↓
Analyze
    ↓
Save

업무가 복잡해지면서 판단을 분리했다.

File Upload
    ↓
Agent Orchestrator
    ↓
Tools

2부에서는 Tool을 MCP로 제공했다.

Agent
  ↓
MCP Client
  ↓
MCP Server
  ↓
Tools

3부에서는 Agent가 실제 운영 환경에서 살아남기 위한 Runtime을 추가했다.

                  Agent Runtime
                       │
        ┌──────────────┼──────────────┐
        ↓              ↓              ↓
      State        Orchestrator    Checkpoint
                       │
                       ↓
                      MCP
                       │
                       ↓
                     Tools
                       │
        ┌──────────────┼──────────────┐
        ↓              ↓              ↓
      Retry          Human          Audit
                     Review

이제 처음의 단순한 Worker가 꽤 다른 형태의 시스템으로 발전했다.

마치며

MCP Tool을 Agent에게 연결하는 것 자체는 어렵지 않다.

어려운 것은 Agent에게 자유를 준 이후다.

언제 멈출 것인가?
실패하면 어떻게 복구할 것인가?
같은 Tool을 다시 호출해도 안전한가?
Worker가 죽으면 어디서 다시 시작할 것인가?
사람을 기다려야 하면 어떻게 Pause할 것인가?
몇 시간 뒤 어떻게 Resume할 것인가?
Agent가 무엇을 했는지 어떻게 추적할 것인가?
비용이 얼마나 들었는지 어떻게 알 것인가?

이 문제들을 해결하면서 Agent는 단순한 Tool Calling 프로그램에서 상태를 가진 Workflow Runtime으로 바뀐다.

그리고 여기서 중요한 원칙은 하나다.

Agent에게 판단을 맡기되, 실행의 통제권까지 모두 넘기지는 않는다.

LLM은 의미적 판단과 Tool 선택에 강점이 있다.

반면 Timeout, Retry Limit, Idempotency, Permission, State Transition 같은 규칙은 코드가 더 잘한다.

둘을 적절하게 결합하는 것이 운영 가능한 Agent 시스템의 핵심이다.

다음 글

4부 — Agent Runtime을 실제 Python 코드로 만들어보기

Redis Streams + State Store + MCP로 Pause/Resume 가능한 Agent 구현

다음 편에서는 지금까지의 개념을 실제 코드 구조로 내려볼 수 있다.

FastAPI
   ↓
Redis Streams
   ↓
Agent Worker
   ↓
Agent Runtime
   ├── State Store
   ├── Orchestrator
   └── MCP Client
          ↓
       MCP Server
          ↓
        Tools

그리고 다음 시나리오를 실제 구현 대상으로 삼을 수 있다.

Invoice Upload
      ↓
Agent 실행
      ↓
분석
      ↓
Human Review 요청
      ↓
WAITING_HUMAN
      ↓
Worker 종료

      ... 승인 Event ...

Agent Resume
      ↓
ERP 등록
      ↓
COMPLETED

여기까지 구현하면 지금까지 설명한 Agent Architecture가 실제 동작하는 백엔드 프로그램의 형태를 갖추게 된다.

Worker에서 Agent Orchestrator로

백엔드에서 흔한 요구사항이 있다.

사용자가 파일을 업로드하면 자동으로 분석하고 결과를 저장한다.

처음에는 단순하다.

File Upload
    ↓
Worker
    ↓
Parse
    ↓
Analyze
    ↓
Save

def process_document(document_id):
    file = download_file(document_id)
    text = parse_document(file)
    result = analyze_document(text)
    save_result(document_id, result)

처리 과정이 항상 같다면 이 구조가 가장 단순하다. 문제는 시스템이 발전하면서 파일 종류와 업무 규칙이 늘어날 때 시작된다.

1. 처음에는 Worker 하나면 충분했다

처음에는 PDF만 처리했지만 Excel, 이미지, 스캔 PDF가 추가될 수 있다.

if file_type == "pdf":
    text = parse_pdf(file)
elif file_type == "xlsx":
    data = parse_excel(file)
elif file_type in ["jpg", "png"]:
    data = analyze_image(file)

if not text:
    text = run_ocr(file)

여기까지는 관리할 만하다. 하지만 요구사항은 계속 늘어난다.

2. 어려운 것은 “다음에 무엇을 해야 하는가”다

Invoice라면 텍스트 추출뿐 아니라 금액, 거래처, 날짜, 통화, 세금 등을 추출하고 검증해야 한다.

File Upload
     ↓
Parse
     ↓
Invoice Detection
     ↓
Invoice Extraction
     ↓
Validation

신뢰도가 높으면 저장한다. 낮으면 재분석, 다른 모델, OCR 또는 Human Review가 필요할 수 있다.

                    ┌── Save
                    │
Analysis → Decision ├── Retry
                    ├── Another Model
                    └── Human Review

문제는 이제 “파일을 어떻게 처리할까?”가 아니라 “현재 상태에서 다음에 무엇을 실행할까?”가 된다.

3. Workflow와 Agent의 차이

실행 순서가 명확한 RAG 적재 파이프라인을 생각해보자.

Upload → Parse → Chunk → Embedding → Vector DB

이런 작업에는 Agent가 필요하지 않다. 코드나 Redis Streams, RabbitMQ, SQS 같은 Queue 기반 Workflow가 더 단순하고 예측 가능하다.

반대로 처리 경로를 미리 결정하기 어렵다면 이야기가 달라진다.

4. 처리 경로를 미리 결정하기 어려운 경우

                     ┌── PDF Parser
                     ├── Excel Analyzer
File Upload → 판단 ──┼── OCR
                     ├── Vision Model
                     └── Invoice Extractor

분석 이후에도 판단이 이어진다.

Analyze
   ↓
Validate
   ↓
Decision
   ├── Save
   ├── Retry
   ├── Additional Analysis
   └── Human Review

물론 if/elif로도 만들 수 있다. 하지만 조건이 계속 늘어나면 Worker는 단순 실행 프로그램이 아니라 거대한 의사결정 프로그램이 된다.

5. Worker에게서 “판단”을 분리한다

                 Orchestrator
                      │
              "무엇을 해야 하지?"
                      │
          ┌───────────┼───────────┐
          ↓           ↓           ↓
       Parser      Analyzer     Database

Orchestrator는 직접 PDF를 분석하거나 DB에 저장하지 않는다. 현재 상황을 보고 어떤 작업을 실행할지 결정한다.

Orchestrator
    ├── get_document
    ├── extract_text
    ├── analyze_document
    ├── extract_invoice
    ├── validate_invoice
    ├── save_analysis
    └── request_human_review

이 Orchestrator가 Agent 역할을 한다.

6. Agent를 “생각하는 Worker”라고 생각해보자

기존 Worker는 개발자가 정한 순서를 실행한다.

A → B → C → D

Agent는 현재 상태를 보고 사용할 작업을 선택한다.

          ┌── B
A → Agent ├── C
          └── D

Invoice 분석 결과의 신뢰도가 높다면 저장하고 낮다면 Human Review로 보낼 수 있다. 같은 시스템에서도 런타임 상태에 따라 실행 경로가 달라진다.

7. Agent는 실제 기능을 어떻게 호출할까?

Python 함수를 Agent 코드에서 직접 호출할 수도 있다. 하지만 기능이 많아질수록 Agent와 실제 업무 기능이 강하게 결합된다.

Agent Application
│
├── Agent Logic
├── PDF Parser
├── OCR
├── Invoice Analyzer
├── Database
└── Human Review

그래서 질문이 생긴다.

Agent가 사용할 기능을 독립적인 Tool로 제공할 수 없을까?

이 지점에서 MCP가 등장한다.

8. MCP를 이용해 Agent와 Tool을 분리한다

              ┌─────────────────────┐
              │     Orchestrator    │
              │        Agent        │
              └──────────┬──────────┘
                         │
                        MCP
                         │
        ┌────────────────┼────────────────┐
        ↓                ↓                ↓
    File Tools        AI Tools        Data Tools
    get_document      classify        save_result
    extract_text      summarize       update_status
    run_ocr           extract_info    get_analysis

Agent는 Tool 내부 구현을 알 필요가 없다. 어떤 Tool이 존재하고, 무엇을 하며, 어떤 입력과 출력을 갖는지가 중요하다.

9. MCP는 Agent의 “능력 목록”을 제공한다

기존 REST API가 다른 프로그램이 사용할 기능을 제공하는 인터페이스라면, MCP Tool은 Agent가 발견하고 선택해서 사용할 수 있는 능력을 제공하는 인터페이스라고 볼 수 있다.

Tool: extract_invoice

Description:
Extract structured invoice information from a document.

Input:
{
  "document_id": "string"
}

Output:
{
  "vendor": "string",
  "amount": "number",
  "currency": "string",
  "confidence": "number"
}

Agent는 Tool 이름과 Description, Schema를 보고 사용할 기능을 판단한다.

10. 모든 함수를 MCP Tool로 만들 필요는 없다

다음 같은 내부 함수까지 Agent에게 제공할 필요는 적다.

normalize_string
calculate_hash
convert_datetime
remove_whitespace

반면 다음은 Agent가 선택할 가치가 있다.

analyze_document
extract_invoice
search_documents
request_human_review
save_analysis

함수(Function)와 Agent Tool은 같은 것이 아니다. Tool은 Agent가 선택할 가치가 있는 행동 단위여야 한다.

11. 파일 업로드가 Agent를 깨운다

Agent가 계속 파일 업로드를 감시할 필요는 없다. 기존 Event Driven Architecture를 활용하면 된다.

User
  │ Upload
  ↓
FastAPI
  ├── Object Storage
  └── Event
        ↓
   Redis Streams
        ↓
   Agent Worker

예를 들어 다음 이벤트가 Agent 실행의 시작점이 된다.

XADD document:uploaded * document_id 12345

Redis Stream
      ↓
Agent Worker
      ↓
Orchestrator
      ↓
MCP Client
      ↓
MCP Server
      ↓
Tools

즉 Agent가 파일을 감시하는 것이 아니라 Event가 Agent를 깨우는 것이다.

12. 전체 아키텍처

                    User
                      │
                   Upload
                      ↓
                  FastAPI
                      │
             ┌────────┴────────┐
             ↓                 ↓
       Object Storage       Redis Stream
                               │
                               ↓
                         Agent Worker
                               │
                               ↓
                         Orchestrator
                               │
                            MCP Client
                               │
                               ↓
                           MCP Server
                               │
          ┌────────────────────┼────────────────────┐
          ↓                    ↓                    ↓
      File Tools           AI Tools            Data Tools

FastAPI는 요청과 파일 저장, Queue는 이벤트 전달, Agent Worker는 Agent 실행, Orchestrator는 다음 행동 결정, MCP Server는 Tool 제공, Tool은 실제 업무 수행을 담당한다.

13. 기존 Workflow는 없어지는가?

그렇지 않다. 중요한 것은 어디까지 Workflow로 만들고 어디부터 Agent에게 맡길 것인가다.

Upload
  ↓
Virus Scan
  ↓
Store File
  ↓
Create Document
  ↓
Publish Event
  ↓
────────────────────────
       Agent 영역
  ↓
Agent Orchestrator
  ├── PDF Parser
  ├── OCR
  ├── Excel Analyzer
  ├── Vision Analyzer
  └── Invoice Extractor
          ↓
       Validate
          ↓
  ┌───────┼────────┐
  ↓       ↓        ↓
 Save    Retry   Human Review

항상 실행되는 작업은 Workflow가 더 적합하다.

14. Agent가 모든 것을 직접 처리할 필요는 없다

Agent의 핵심 역할은 실행보다 판단과 조정(Orchestration) 이다.

실제 작업은 Tool이 담당한다.

                 Agent
                   │
             Decision Making
                   │
        ┌──────────┼──────────┐
        ↓          ↓          ↓
      Tool       Tool       Tool
   parse_pdf    run_ocr   save_result

15. 기존 서비스를 버리고 MCP를 다시 만드는 것은 아니다

기존 Service Layer를 그대로 활용할 수 있다.

Agent
  ↓
MCP Tool
  ↓
Existing Service
  ↓
Database / Storage / AI

MCP는 기존 백엔드를 대체하기보다 Agent가 기존 백엔드 기능을 사용할 수 있도록 새로운 인터페이스를 추가하는 것에 가깝다.

16. MCP Tool의 경계가 중요하다

get_file_path, calculate_hash, normalize_filename 같은 내부 함수를 모두 Tool로 노출하기보다 다음처럼 의미 있는 업무 단위로 묶는 편이 좋다.

prepare_document
extract_document_content
analyze_invoice
validate_analysis
save_analysis
request_human_review

Tool은 함수의 단위가 아니라 Agent가 선택할 수 있는 행동의 단위다.

17. MCP를 사용한다고 시스템이 자동으로 좋아지는 것은 아니다

모든 문서가 항상 Parse → Chunk → Embedding → Save 순서로 처리된다면 Agent에게 다음 행동을 물어볼 이유가 없다.

Agent를 넣으면 LLM 호출 비용, 지연시간, 장애 지점과 예측 불가능성이 늘어날 수 있다.

따라서 먼저 물어봐야 한다.

이 시스템에는 정말 ‘판단’이 필요한가?

18. Agent + MCP가 유리한 상황

다음 특징이 있다면 검토할 가치가 있다.

• 입력 종류가 PDF, Excel, Image, Invoice, Contract처럼 다양하다.
• 분석 결과에 따라 Save, Retry, Additional Analysis, Human Review 등 다음 행동이 달라진다.
• OCR, Vision, ERP, Email, Slack 등 사용할 기능이 계속 증가한다.
• 업무 규칙이 복잡해져 단순한 고정 Workflow로 표현하기 어려워진다.

이런 지점에서 Agent Orchestrator의 가치가 생긴다.

19. 결국 중요한 것은 “판단”과 “실행”의 분리다

기존 Worker
 ├── Decision
 └── Execution

Agent 기반 구조에서는 이를 분리한다.

             Orchestrator
                  │
              Decision
                  │
                  ↓
                 MCP
                  │
        ┌─────────┼─────────┐
        ↓         ↓         ↓
      Tool      Tool      Tool
                 Execution

실제 비즈니스 로직은 기존 Service가 담당할 수도 있다.

Agent
  ↓
Orchestrator
  ↓
MCP Tool
  ↓
Service
  ↓
Infrastructure

20. Agent는 Workflow를 없애는 기술이 아니다

Queue도, Worker도, Redis Streams나 RabbitMQ, SQS도 여전히 유용하다. Database와 Service Layer도 그대로 존재한다.

달라지는 것은 일부 영역에서 Agent가 현재 상황을 보고 실행할 Tool을 선택한다는 점이다.

Developer
    ↓
Available Tools
    ↓
Agent
    ↓
Runtime Decision

Agent는 Workflow를 없애는 기술이 아니라, Workflow를 미리 결정하기 어려운 지점에 들어가는 기술이다.

그리고 MCP는 그 Agent가 사용할 수 있는 능력을 Tool 형태로 제공하는 방법 중 하나다.

마치며

처음에는 단순했다.

File Upload
    ↓
Worker
    ↓
Analyze
    ↓
Save

하지만 업무가 복잡해지면서 처리 과정에 판단이 들어오기 시작했다.

                     ┌── OCR
                     ├── PDF Parser
File Upload → Agent ─┼── Vision
                     ├── Invoice Analyzer
                     └── Human Review

판단과 실제 실행을 분리하면 다음 구조를 생각할 수 있다.

File Upload
     ↓
Event
     ↓
Agent Worker
     ↓
Orchestrator
     ↓
MCP
     ↓
Tools

이제 다음 질문이 자연스럽게 생긴다.

실제 Python 백엔드 기능을 어떻게 MCP Tool로 만들 수 있을까?

다음 글에서는 Python으로 MCP Server를 만들고, 기존 Service를 MCP Tool로 노출하고, Tool의 Input/Output Schema를 정의하는 방법을 살펴본다.

다음 글

2부 — Python으로 파일 분석용 MCP Tool 직접 만들어보기

Agent
  ↓
MCP Client
  ↓
MCP Server
  ├── get_document
  ├── extract_document_content
  ├── analyze_document
  └── save_analysis

그리고 “그냥 Python 함수를 호출하는 것과 MCP Tool을 사용하는 것은 무엇이 다른가?”라는 문제까지 이어서 살펴본다.