OpenAI 에이전트 구축 가이드

개요

OpenAI 공식 “A Practical Guide to Building Agents” 종합 정리. 에이전트 = 사용자를 대신해 독립적으로 워크플로를 수행하는 시스템 (단순 LLM 앱 ❌). 핵심 3요소: 모델 + 도구 + 지침. 단일 에이전트에서 시작해 필요할 때만 다중 에이전트로 확장. 가드레일은 다계층 방어, 사람 개입은 핵심 안전장치. 성공적 배포 = 작게 시작 + 실제 검증 + 점진 확장.

출처: OpenAI 공식 문서 (PDF 제공)
위치: 에이전트 시대의 사실상 표준 가이드

에이전트의 정의

에이전트인가? (체크)

✅ 에이전트:
  - LLM이 워크플로 실행을 관리·제어
  - 의사결정 + 워크플로 완료 인식
  - 실패 시 사용자에게 제어권 반환
  - 도구로 외부 시스템과 상호작용
  - 가드레일 내에서 동적 도구 선택

❌ 에이전트 아님:
  - 단순 챗봇
  - 단일 턴 LLM
  - 감정 분류기
  - LLM을 통합했지만 실행 제어 안 함

에이전트를 도입해야 하는 시점

3가지 적합한 워크플로

유형	예시	왜?
복잡한 의사결정	환불 승인	미묘한 판단·예외 처리
유지보수 어려운 규칙	벤더 보안 리뷰	방대한 규칙셋, 업데이트 비용 큼
비정형 데이터 의존	보험 청구 처리	자연어 해석, 문서에서 의미 추출

결제 사기 분석 비교

전통적 규칙 엔진:
  ✗ 사전 설정 기준 체크리스트
  ✗ 명확한 규칙 위반만 탐지

LLM 에이전트:
  ✅ 맥락 평가
  ✅ 미묘한 패턴 고려
  ✅ 명확한 규칙 위반 없이도 의심 식별
  → "숙련된 조사관" 역할

→ 기준에 안 맞으면 결정론적 솔루션이 더 적합

핵심 3요소

1. Model (모델)

모든 작업에 최강 모델 ❌

원칙:
  ✓ 평가(eval)로 성능 기준선 확립
  ✓ 최강 모델로 정확도 목표 달성
  ✓ 가능한 곳에서 작은 모델로 교체 (비용·지연 ↓)

작업별 모델 매칭:
  단순 검색·분류 → 작고 빠른 모델 (Haiku, Gemini Flash)
  환불 승인 → 강력한 모델 (Opus, GPT-5)

→ 관련: oh-my-claudecode & Claude 멀티에이전트 (스마트 모델 라우팅)

2. Tools (도구)

3가지 유형

유형	역할	예시
Data	맥락·정보 검색	DB 쿼리, CRM, PDF, 웹 검색
Action	시스템 상호작용	이메일·문자, CRM 업데이트, 티켓 이관
Orchestration	다른 에이전트 호출	환불·리서치·작성 에이전트

도구 설계 원칙

✓ 표준화된 정의 (다대다 관계 지원)
✓ 잘 문서화 + 철저히 테스트
✓ 재사용 가능 (발견성 ↑, 버전 관리 ↑)

레거시 시스템 (API 없음):
  → computer-use 모델로 UI 직접 조작

3. Instructions (지침)

모범 사례:
  ✓ 기존 문서 활용 (운영 절차·정책)
  ✓ 작업 분해 (밀도 높은 리소스 → 작은 단계)
  ✓ 명확한 액션 정의 (각 단계 = 특정 액션·출력)
  ✓ 엣지 케이스 포착 (조건부 분기)

자동화 팁:
  o1·o3-mini 같은 추론 모델로
  기존 문서에서 자동 지침 생성

→ 관련: Codex 플랫폼 (SDLC 가이드) (agents.md 베스트 프랙티스), GPT-5.4 프론트엔드 디자인 가이드

오케스트레이션

단일 에이전트 시스템 (권장 시작점)

도구를 점진적으로 추가:
  복잡성 관리 ↑
  평가·유지보수 단순 ↑

run 루프:
  종료 조건까지 반복
  - 도구 호출
  - 특정 구조화 출력
  - 오류
  - 최대 턴 수 도달

프롬프트 템플릿 전략:
  여러 개별 프롬프트 ❌
  → 정책 변수를 받는 단일 유연 프롬프트 ✅

다중 에이전트로 전환 시점

일반 권장:
  단일 에이전트 역량 먼저 최대화
  → 더 많은 에이전트 = 추가 복잡성·오버헤드

분할 시점:
  1. 복잡한 로직 (다수의 if-then-else)
     → 각 논리 세그먼트 별도 에이전트
  
  2. 도구 과부하
     - 문제는 도구 수 ❌, 유사성·중복 ✅
     - 15개 명확히 구분된 도구 = OK
     - 10개 미만 중복 도구 = 어려움

매니저 패턴 ⭐

중앙 LLM "매니저"
  ↓ 도구 호출
전문 에이전트 네트워크
  → 결과를 통합된 상호작용으로 합성

적합:
  하나의 에이전트만 워크플로 실행 제어
  + 사용자 접근

예시:
  번역 매니저
    → 스페인어 / 프랑스어 / 이탈리아어 에이전트

탈중앙화 패턴 (Handoff)

에이전트가 다른 에이전트에게
  실행을 '핸드오프' (단방향 전환)

Agents SDK:
  핸드오프 = 도구·함수의 일종
  최신 대화 상태 전달
  새 에이전트가 즉시 실행

예시:
  트리아지 에이전트
    → 기술지원 / 영업 / 주문관리 에이전트

선언적 vs 코드 우선

방식	장점	단점
선언적 (Declarative)	시각적 명확성	동적 워크플로 번거로움, DSL 학습
코드 우선 (Code-first)	동적·적응 가능	시각화 약함

→ Agents SDK = 코드 우선

가드레일 (Guardrails) ⭐

역할

✓ 데이터 프라이버시 (시스템 프롬프트 유출 방지)
✓ 콘텐츠 안전
✓ 브랜드 일관성

핵심:
  단일 가드레일 ❌
  → 다수 전문화 가드레일 함께
  → 인증·권한·접근 제어와 결합 필수

7가지 가드레일 유형

유형	역할
Relevance Classifier	의도 범위 내 응답 확인
Safety Classifier	탈옥·프롬프트 인젝션 탐지
PII Filter	개인정보 노출 방지
Moderation	혐오·괴롭힘·폭력 입력 플래그
Tool Safeguards	도구별 위험 등급 (저/중/고), 고위험 시 일시정지·에스컬레이션
Rules-based	차단 목록, 길이 제한, 정규식 (SQL 인젝션 방지)
Output Validation	응답 브랜드 가치 부합 확인

→ 관련: 맥킨지 Lilli AI 플랫폼 해킹 (“프롬프트 = Crown Jewel”의 교훈)

도구 위험 등급 예시

저위험: 읽기 전용 데이터 조회
중위험: 사용자 메시지 전송
고위험:
  ✗ 결제 처리
  ✗ 환불 승인
  ✗ 데이터 삭제
  → 가드레일 검사 일시 정지
  → 사람 에스컬레이션

Agents SDK의 낙관적 실행

기본 에이전트가 선제적으로 출력 생성
  ↕ 동시에
가드레일도 병렬 실행
  ↓
제약 위반 시 → 예외 트리거

→ 속도 + 안전 균형

가드레일 구축 접근법

1. 식별된 리스크부터 시작
2. 새 취약점 발견 시 계층화
3. 데이터 프라이버시 + 콘텐츠 안전 집중
4. 실제 엣지 케이스 기반 추가
5. UX와 보안 모두 최적화

사람 개입 (Human-in-the-Loop)

역할

✓ 사용자 경험 해치지 않으면서 실제 성능 개선
✓ 배포 초기 특히 중요
✓ 실패 식별·엣지 케이스 발견·평가 사이클 확립

개입 트리거 2가지

트리거	예시
실패 임계값 초과	여러 시도 후에도 고객 의도 파악 실패
고위험 행동	주문 취소, 대규모 환불, 결제 처리

신뢰도 진화

배포 초기:
  사람 감독 多
  ↓
신뢰도 축적
  ↓
점진적으로 자동화 확대

단일 에이전트 vs 다중 에이전트 결정 트리

문제 정의
  ↓
단일 에이전트로 시작
  ↓
도구 추가하며 역량 확장
  ↓
한계 도달?
  ✗ NO → 단일 에이전트 유지
  ✓ YES → 분석:
       - 로직 복잡도 (조건문 多)?
       - 도구 중복·유사성?
  ↓
다중 에이전트 패턴 선택:
  - 매니저 패턴 (하나의 에이전트가 사용자 접근)
  - 탈중앙화 (핸드오프, 직접 인계)

성공적 배포 5단계

1. 작게 시작 (단일 에이전트)
2. 실제 사용자 검증
3. 가드레일·사람 개입 추가
4. 점진적 역량 확장
5. 다중 에이전트로 진화 (필요시)

❌ "전부 아니면 전무" 접근
✅ 반복적 접근 = 성공의 핵심

vault의 다른 노트와 매핑

OpenAI 가이드 개념	관련 vault 노트
agents.md	Codex 플랫폼 (SDLC 가이드), Open SWE (사내 코딩 에이전트)
다중 에이전트	Oh My Codex & 에이전트 스웜, oh-my-claudecode & Claude 멀티에이전트
매니저 패턴	Open SWE (사내 코딩 에이전트)의 서브에이전트
가드레일	Claude 헌법 (Constitutional AI), 맥킨지 Lilli AI 플랫폼 해킹
단일→다중 전환	Superpowers (Claude 스킬 프레임워크)
MCP 도구	Serena MCP, Vibium (브라우저 자동화)
사람 개입	Human In The Loop (HITL)
워크플로 분해	gstack (Garry Tan Claude 워크플로)
로컬 에이전트	OpenClaw, ZeroClaw (Rust 초경량 AI 런타임)

핵심 인용

“에이전트는 모호성을 추론하고, 도구를 통해 행동을 취하며, 다단계 작업을 높은 자율성으로 처리하는 워크플로 자동화의 새로운 시대”

“성공적 배포는 전부 아니면 전무가 아닌, 작게 시작해 실제 사용자와 검증하고 시간이 지나며 역량을 성장시키는 반복적 접근 방식”

의의

1. 에이전트의 공식 정의
   - "워크플로 실행 제어" 기준
   - LLM 통합 ≠ 에이전트
   - 명확한 분류 체계

2. 모델·도구·지침 = 에이전트 3원칙
   - vault의 다른 노트들이 모두 이 프레임에 매핑됨
   - 사실상 표준 정립

3. 단일 → 다중 점진 진화
   - 처음부터 멀티 에이전트 ❌
   - "도구 과부하" 시 분할

4. 가드레일 = 다계층 방어
   - 7가지 유형 표준화
   - 보안과 UX의 균형

5. 사람 개입 = 핵심 안전장치
   - 자동화의 끝이 아니라 시작
   - 신뢰도 따라 점진 축소

Bigstones

Explorer