첫 번째 에이전트 데모는 마법처럼 느껴질 수 있습니다. 프롬프트를 읽고, 도구(tool)를 호출하며, 유용한 답변을 작성하는 모습을 보면 어려운 부분은 모두 끝났다고 생각하게 됩니다.

그러다 그것을 실제로 배포(ship)하려고 시도하게 됩니다.

갑자기 진짜 질문들이 나타납니다: 실행 환경(run)은 어디에 있는가? 모델이 타임아웃(timeout)되면 어떻게 되는가? 두 명의 사용자가 동일한 워크플로우(workflow)를 두 번 시작할 수 있는가? 에이전트가 올바른 소스를 사용했는지, 예산(budget) 내에서 작동했는지, 그리고 중간에 조용히 실패하지 않았음을 어떻게 증명할 것인가?

이 런북(runbook)은 “내 노트북에서는 잘 작동했다”와 “사용자가 안전하게 신뢰할 수 있다” 사이의 간극을 메우기 위한 것입니다. 우리는 큐(queues), 멱등성(idempotency), 상태 확인(health checks), 예산 제한(budget limits), 평가(evals), 감사 로그(audit logs), 그리고 릴리스 게이트(release gates)를 갖춘 로컬 AI 에이전트를 신뢰할 수 있는 API 기반 워크플로우로 전환할 것입니다.

목표는 에이전트를 완전히 자율적으로 만드는 것이 아닙니다. 목표는 에이전트가 운영하기에 충분히 지루할 정도로 안정적이게 만드는 것입니다.

데모 이후 에이전트 배포가 실패하는 이유

대부분의 튜토리얼은 해피 패스(happy path)를 보여줍니다:

1. 작업(task) 정의
2. 프레임워크(framework) 선택
3. 도구(tools) 추가
4. 에이전트 실행
5. 답변 출력

이는 유용하지만, 프로덕션(production) 환경은 다른 실패 모드(failure modes)를 가집니다.

배포된 에이전트는 다음 상황에서도 살아남아야 합니다:

• 느린 모델 응답
• 불안정한 도구(flaky tools)
• 중복 요청
• 사용자 취소
• 부분적인 진행 상황
• 잘못 검색된 컨텍스트(retrieved context)
• 토큰 급증(token spikes)
• 스키마 드리프트(schema drift)
• 안전하지 않은 도구 인자(tool arguments)
• 제공업체 중단(provider outages)
• 끝나지 않는 백그라운드 작업

최근의 AI 툴링(tooling) 트렌드는 이를 더욱 시급하게 만듭니다. 에이전트 시스템(Agentic systems)은 채팅창을 벗어나 실제 워크플로우로 이동하고 있습니다. 빌더(builders)들은 모델을 GitHub, Discord, 이메일, CRM, 데이터베이스, 브라우저 세션, 그리고 유료 API에 연결하고 있습니다. 새로운 제품들은 또한 '검토 우선(review-first)' 동작 방식에 집중하고 있습니다. 즉, 에이전트가 실제 사용자 데이터에 접근하기 전에 제안하고, 설명하고, 기다리는 방식입니다.

이는 올바른 방향입니다. 하지만 배포 레이어(deployment layer)가 첫날부터 신뢰성을 위해 설계되어 있을 때만 작동합니다.

아키텍처: 최소한의 신뢰할 수 있는 에이전트 시스템

진지한 에이전트 워크플로우를 위해서는 모델 호출을 제품의 전부로 취급하는 것을 피해야 합니다. 다음과 같은 작은 부품 시스템을 사용하십시오:

Client
  |
  v
...

각 구성 요소는 하나의 작업만을 수행합니다:

• API 서버 (API server): 요청을 수락하고, 인증 (auth)을 검증하며, 실행 (runs)을 생성하고, 상태를 반환합니다.
• 실행 데이터베이스 (Run database): 상태, 입력 해시 (input hash), 소유자, 예산, 진행 상황 및 결과를 저장합니다.
• 작업 큐 (Job queue): 시간이 오래 걸리는 작업이 요청 타임아웃 (request timeouts)에 걸리지 않도록 관리합니다.
• 워커 (Worker): 에이전트를 단계별로 실행합니다.
• 도구 게이트웨이 (Tool gateway): 권한, 스키마 (schemas), 속도 제한 (rate limits) 및 로깅 (logging)을 강제합니다.
• 감사 로그 (Audit log): 어떤 일이, 왜, 누구의 권한 하에 발생했는지를 기록합니다.

FastAPI, Express, Django, Rails 또는 이미 사용 중인 어떤 스택으로도 이를 구축할 수 있습니다. 프레임워크보다 패턴이 더 중요합니다.

1단계: 프롬프트 작성 전에 에이전트 계약(Agent Contract) 정의하기

프롬프트를 작성하기 전에 계약 (contract)을 정의하십시오.

에이전트 계약은 다음을 명시합니다:

• 에이전트가 수락하는 입력 (input)
• 반환해야 하는 출력 형태 (output shape)
• 사용할 수 있는 도구 (tools)
• 절대로 해서는 안 되는 행동
• 실행 가능한 최대 시간
• 사용 가능한 최대 비용
• 승인을 요청해야 하는 시점
• 첨부해야 하는 증거 (evidence)

계약 예시:

{
  "agent": "support_issue_triage",
  "input": {
...

이 계약은 프롬프트, 테스트, API 문서, 모니터링 및 검토 전반에 걸쳐 공유되는 진실의 근거 (shared truth)가 됩니다.

2단계: API를 기본적으로 비동기(Asynchronous)로 만들기

일반적인 HTTP 요청 내부에서 의미 있는 에이전트 작업을 실행하지 마십시오. 타임아웃이 발생하거나, 잘못된 재시도 (retry)가 일어나거나, 부하 상황에서 서버를 차단 (block)할 수 있습니다.

대신 다음 패턴을 사용하십시오:

1. 클라이언트가 요청을 보냅니다.

2. API가 이를 검증합니다.

3. API가 agent_run 행을 생성합니다.

4. API가 작업을 큐에 넣습니다 (enqueues).

5. 워커가 진행 상황과 최종 결과를 기록합니다.

간단한 Python 구조:

from fastapi import FastAPI, Depends
from pydantic import BaseModel
from uuid import uuid4
...

이 작은 설계 선택이 많은 고통을 방지해 줍니다. 사용자는 실행 ID (run ID)를 받게 됩니다. 귀하의 시스템은 모니터링, 취소, 재시도, 조사 및 감사를 수행할 수 있는 내구성 있는 객체 (durable object)를 확보하게 됩니다.

3단계: 사용자가 더블 클릭하기 전에 멱등성(Idempotency) 추가하기

사용자는 페이지를 새로고침합니다. 브라우저는 재시도합니다. 모바일 네트워크는 끊깁니다. 웹훅(Webhook)은 재전송됩니다. 만약 동일한 요청이 두 개의 라이브 에이전트 실행(agent run)을 생성할 수 있다면, 결국 중복 작업이나 중복 쓰기(duplicate writes)가 발생하게 될 것입니다.

멱등성 키(Idempotency key)를 추가하세요.

import hashlib
import json

...

쓰기 작업(write actions)에 있어 멱등성은 선택 사항이 아닙니다. 이는 "에이전트가 안전하게 재시도했는가"와 "에이전트가 고객에게 비용을 두 번 청구했는가"의 차이를 만듭니다.

4단계: 제품 기능처럼 실행 상태(Run State)를 저장하기

에이전트 실행(agent run)은 단순한 로그 덩어리여서는 안 됩니다. 구조화된 상태(structured state)를 저장하세요.

최소한 유용한 필드:

agent_runs
- id
- tenant_id
...

그 다음 단계(steps)를 별도로 저장하세요:

agent_run_steps
- id
- run_id
...

이렇게 하면 사용자나 엔지니어가 실제로 던지는 질문에 답할 수 있는 충분한 세부 정보를 얻을 수 있습니다:

• 이 실행은 왜 실패했는가?
• 어떤 단계가 느렸는가?
• 에이전트가 올바른 도구(tool)를 호출했는가?
• 고객 B의 실행에서 고객 A의 컨텍스트(context)를 사용했는가?
• 재시도가 위험한 동작을 반복했는가?

5단계: 모든 도구 뒤에 게이트웨이(Gateway) 배치하기

에이전트의 리스크를 가장 빠르게 만드는 방법은 런타임 정책 계층(runtime policy layer) 없이 모델이 도구를 직접 호출하게 두는 것입니다.

대신, 도구 게이트웨이(tool gateway)를 만드세요. 워커(worker)는 게이트웨이에 도구 실행을 요청합니다. 게이트웨이는 다음을 확인합니다:

• 이 도구가 이 에이전트에게 허용되는가?
• 이 사용자 및 테넌트(tenant)에게 허용되는가?
• 인자(arguments)가 유효한가?
• 모델이 신뢰할 수 있는 서버 상태(server state)에서 가져와야 하는 필드를 직접 제공했는가?
• 이 동작이 읽기 전용(read-only)인가, 쓰기(write)인가, 유료(paid)인가, 아니면 파괴적(destructive)인가?
• 이 동작에 승인이 필요한가?
• 실행이 여전히 예산(budget) 범위 내에 있는가?

정책 형태(policy shape) 예시:

TOOL_POLICY = {
    "search_issues": {"risk": "low", "approval": False},
    "read_issue": {"risk": "low", "approval": False},
...

프롬프트(Prompt)는 안전한 동작을 요청할 수 있습니다. 게이트웨이는 이를 강제(enforce)합니다.

6단계: 폭주하는 작업을 막는 예산(Budget) 구축하기

신뢰할 수 있는 에이전트는 엄격한 제한(hard limits)을 가집니다. 느낌(vibes)이나 "간결하게 해주세요" 같은 요청이 아니라, 실제 카운터(counters)가 필요합니다.

최소한 다음을 추적하세요:

• 실행당 모델 호출 횟수 (model calls per run)
• 실행당 도구 호출 횟수 (tool calls per run)
• 총 토큰 수 (total tokens)
• 예상 비용 (estimated cost)
• 재시도 횟수 (retry count)
• 실제 실행 시간 (wall-clock runtime)
• 출력 크기 (output size)
• 외부 API 호출 (external API calls)

예산에 도달하면, 우아하게 실패(fail gracefully) 처리하세요:

{
  "status": "failed",
  "error_code": "BUDGET_EXCEEDED",
...

이는 청구 금액이 치솟는 동안 워커(worker)가 30분 동안 헛돌게 두는 것보다 훨씬 낫습니다.

7단계: 전체 경로를 테스트하는 상태 확인(Health Checks) 추가하기

기본적인 /health 엔드포인트는 서버가 깨어 있다는 것만 증명할 뿐입니다. 에이전트 시스템에는 더 깊은 확인이 필요합니다.

다음 세 가지 수준을 사용하세요:

1. 활성 상태 확인 (Liveness check)

프로세스가 실행 중인가요?

GET /health/live -> 200 OK

2. 준비 상태 확인 (Readiness check)

서비스가 의존성(dependencies)에 도달할 수 있나요?

GET /health/ready
- database: ok
- queue: ok
...

3. 합성 에이전트 확인 (Synthetic agent check)

아주 작은 안전한 에이전트가 전체 과정을 완료할 수 있나요?

다음 작업을 수행하는 예약된 테스트를 실행하세요:

• 가짜 실행(fake run) 생성
• 모의(mock) 또는 저비용 모델 경로 사용
• 안전한 읽기 전용 도구 호출
• 구조화된 출력(structured output) 검증
• 지연 시간(latency) 및 비용 기록

이를 통해 자격 증명(credentials) 오류, 스키마 불일치(schema mismatches), 또는 변경된 모델 응답 형식과 같이 일반적인 상태 확인에서 놓칠 수 있는 문제들을 잡아낼 수 있습니다.

8단계: 워크플로 평가(Workflow Evals)로 배포 차단하기

단위 테스트(Unit tests)만으로는 충분하지 않습니다. 워크플로를 테스트하는 평가(evals)가 필요합니다.

실제 실패 사례에 대한 피스처(fixtures)를 생성하세요:

A 간단한 평가 결과에는 다음이 포함되어야 합니다:

{
  "case_id": "duplicate_issue_low_keyword_overlap",
  "passed": true,
...

핵심 평가(core evals)를 통과하지 못하면 새로운 프롬프트, 모델, 도구 또는 검색(retrieval) 설정을 배포하지 마세요.

9단계: 초안 작성, 승인, 실행 분리하기

많은 프로덕션 에이전트가 최종 작업을 직접 수행해서는 안 됩니다. 대신 초안을 작성해야 합니다.

다음 패턴을 사용하세요:

에이전트 조사(investigates) -> 에이전트 작업 초안 작성(drafts action) -> 사람 또는 정책이 승인(approves) -> 시스템 실행(executes)

예를 들어:

• 지원 답변 초안 작성(draft), 하지만 전송하지는 않음
• 이슈(issue) 종료 제안(suggest), 하지만 종료하지는 않음
• 데이터베이스 업데이트 준비(prepare), 하지만 실행하지는 않음
• 환불 권장(recommend), 하지만 환불을 처리하지는 않음

이것은 제품을 약하게 만드는 것이 아닙니다. 오히려 더 높은 이해관계(higher-stakes)가 걸린 워크플로우(workflows)에서도 사용 가능하게 만듭니다.

승인 기록(Approval records)에는 다음 사항이 저장되어야 합니다:

• 제안된 작업 (proposed action)
• 인자 (arguments)
• 근거 (evidence)
• 위험 수준 (risk level)
• 검토자 (reviewer)
• 승인 또는 거절 (approval or rejection)
• 타임스탬프 (timestamp)
• 최종 실행된 작업 ID (final executed action ID)

고객이 “왜 에이전트가 이렇게 행동했나요?”라고 물을 때, 그 기록은 황금과 같은 가치를 지니게 됩니다.

10단계: 사용자가 조치를 취할 수 있는 실패 메시지 설계하기

에이전트 실행 실패가 단순히 Something went wrong(문제가 발생했습니다)으로 끝나서는 안 됩니다.

유용한 실패 출력에는 다음 내용이 포함되어야 합니다:

• 무엇이 실패했는지
• 변경된 사항이 있는지 여부
• 어떤 근거가 저장되었는지
• 재시도(retry)가 안전한지 여부
• 사용자가 다음에 무엇을 할 수 있는지

예시:

{
  "status": "failed",
  "error_code": "TOOL_TIMEOUT",
...

이는 신뢰를 구축합니다. 사용자에게 필요한 것은 완벽함이 아닙니다. 명확한 경계(boundaries)입니다.

11단계: 프롬프트, 도구, 모델을 함께 버전 관리하기

어떤 프롬프트와 모델이 출력을 생성했는지 알 수 없다면, 디버깅(debugging)은 추측의 영역이 됩니다.

이들을 함께 버전 관리하세요:

agent_version: support_triage_v4
prompt_version: triage_prompt_2026_07_28
model: selected_by_router
...

실행이 실패했을 때, 이전 버전들과 비교할 수 있습니다. 새로운 모델이 특정 케이스는 개선했지만 다른 케이스를 망가뜨렸을 경우, 깔끔하게 롤백(roll back)할 수 있습니다.

배포 체크리스트

에이전트 워크플로우(agent workflow)를 실제 사용자에게 공개하기 전에, 다음 목록을 확인하십시오:

• 에이전트가 명문화된 계약(contract)을 가지고 있습니다.
• 요청이 영구적인 실행 기록(durable run records)을 생성합니다.
• 긴 작업은 요청 스레드(request thread)가 아닌 워커(worker)에서 실행됩니다.
• 중복 요청이 멱등성(idempotent)을 유지합니다.
• 각 실행에는 모델, 도구, 런타임 및 비용 예산(budgets)이 설정되어 있습니다.
• 도구는 정책 게이트웨이(policy gateway)를 거칩니다.
• 테넌트(Tenant) 및 사용자 범위(scope)가 서버 측에서 강제됩니다.
• 위험한 작업은 승인을 위해 일시 중지됩니다.
• 진행 상황이 영구적인 상태(durable state)로부터 스트리밍됩니다.
• 실패 메시지는 사용자가 읽을 수 있고 재시도 가능(retry-aware)해야 합니다.
• 워크플로우 평가(Workflow evals)가 안전하지 않은 배포를 차단합니다.
• 프롬프트, 도구, 모델 및 검색 설정(retrieval configs)에 버전이 지정되어 있습니다.
• 감사 로그(Audit logs)를 통해 발생한 일을 설명할 수 있습니다.
• 합성 체크(Synthetic checks)가 에이전트의 전체 경로를 테스트합니다.

만약 이것이 데모보다 더 많은 작업처럼 느껴진다면, 실제로 그렇습니다. 하지만 사용자가 신뢰를 보낸 후 통제 불능이 된 워크플로우를 수습하는 것보다는 훨씬 적은 작업량입니다.

실제 사용 사례

이 런북(runbook)은 지원 분류(support triage), 고객 조사, 내부 운영 및 개발자 워크플로우 자동화에 적합합니다. 각 사례에서 안전한 패턴은 동일합니다: 조사하고, 초안을 작성하고, 증거를 첨부하고, 범위를 강제하며, 고객 데이터나 외부 시스템을 변경하기 전에 승인을 요청하는 것입니다.

최종 결론

로컬 에이전트 데모는 모델이 해당 작업을 한 번 수행할 수 있음을 증명합니다. 배포된 에이전트 시스템은 귀하의 제품이 해당 작업을 반복적으로, 안전하게, 그리고 증거와 함께 처리할 수 있음을 증명합니다.

그 차이는 하나의 마법 같은 프레임워크에 있는 것이 아닙니다. 그것은 에이전트를 둘러싼 런북(runbook)에 있습니다: 영구적인 상태(durable state), 큐(queues), 예산(budgets), 도구 정책(tool policy), 승인 게이트(approval gates), 평가(evals), 상태 확인(health checks) 및 감사 로그(audit logs)입니다.

터미널을 열지 않고도 다음 질문에 답할 수 있을 때 에이전트를 출시하십시오:

이 실행에서 어떤 일이 일어났는가? 비용은 얼마였는가? 무엇을 건드렸는가? 그리고 재시도해도 안전한가?

귀하의 시스템이 이에 답할 수 있다면, 신뢰할 수 있는 AI 제품에 훨씬 더 가까워진 것입니다.

FAQ

AI 에이전트 배포 런북(runbook)이란 무엇인가요?

AI 에이전트 배포 런북(runbook)은 에이전트를 로컬 프로토타입에서 신뢰할 수 있는 프로덕션(production) 워크플로우로 전환하기 위한 실질적인 운영 계획입니다. 이는 API 설계, 큐(queues), 실행 상태(run state), 도구 권한(tool permissions), 예산(budgets), 모니터링(monitoring), 평가(evals), 승인(approvals) 및 장애 처리(failure handling)를 다룹니다.

AI 에이전트 API는 동기(synchronous) 방식이어야 하나요, 아니면 비동기(asynchronous) 방식이어야 하나요?

AI 에이전트를 배포할 때 가장 큰 실수는 무엇인가요?

가장 큰 실수는 모델 호출(model call) 자체를 제품으로 취급하는 것입니다. 프로덕션 에이전트에는 내구성이 있는 상태(durable state), 범위가 제한된 도구(scoped tools), 예산(budgets), 평가(evals), 로그(logs) 및 명확한 장애 동작(failure behavior)이 필요합니다. 이러한 계층이 없다면, 작은 문제들이 비용이 많이 드는 사고로 이어지게 됩니다.

AI 에이전트가 안전하지 않은 행동을 하지 못하도록 어떻게 막나요?

모든 도구를 정책 게이트웨이(policy gateway) 뒤에 배치하십시오. 도구를 위험도에 따라 분류하고, 인자(arguments)를 검증하며, 테넌트 범위(tenant scope)를 강제하고, 예산을 제한하십시오. 또한 메시지 전송, 레코드 변경, 데이터 삭제 또는 비용 지출과 같은 고위험 작업에 대해서는 승인(approval)을 요구해야 합니다.

프로덕션 AI 에이전트를 어떻게 모니터링하나요?

실행 상태(run status), 단계별 지연 시간(step latency), 모델 호출(model calls), 도구 호출(tool calls), 비용(cost), 재시도(retries), 장애(failures), 승인 대기(approval waits), 출력 검증 오류(output validation errors) 및 사용자 피드백을 추적하십시오. 깨진 의존성(dependencies)을 포착하기 위해 정해진 일정에 따라 작은 안전한 워크플로우를 실행하는 합성 체크(synthetic checks)를 추가하십시오.

에이전트 평가(evals)는 얼마나 자주 실행해야 하나요?

프롬프트(prompt), 모델(model), 검색(retrieval) 또는 도구 정책(tool-policy)이 변경될 때마다 빠른 워크플로우 평가(fast workflow evals)를 실행하십시오. 주요 릴리스 전에는 더 큰 규모의 평가 세트(suite)를 실행하십시오. 실제 사고와 사용자 수정 사항으로부터 사례를 지속적으로 추가하십시오.