하나는 OpenAI-Hugging Face 사건이며, 다른 하나는 차기 모델인 Astra가 Preparedness Framework에서 정의한 Critical Cybersecurity Capability 임계 수준에 도달할 가능성이 있다는 초기 평가 결과다. 이러한 변화로 인해 OpenAI는 모델 학습 전 과정에서 모니터링, 정렬, 보안 격리를 강화할 필요성이 커졌다고 설명한다.

1. 모델 개발 속도를 일시적으로 늦추다

모델 성능이 높아질수록 내부에서 모델을 개발하고 테스트하는 과정 자체의 위험도 커진다. OpenAI는 안전 기준을 충족하기 위해 최신 배포 예정 모델의 강화학습(RL)을 약 2주 동안 중단했다. 이 기간 연구 환경의 보안을 강화하고 레드팀 테스트를 수행했으며 모니터링 범위를 확대했다.

가장 큰 규모로 계획된 프런티어 강화 학습은 현재도 보류 상태다. 대신 소규모 학습과 평가를 통해 모델 행동, 안전장치, 정렬 수준을 먼저 확인하고 있다.

2. 세 가지 핵심 안전장치

OpenAI는 고성능 모델 개발에 세 가지 안전 계층을 적용하고 있다.

• Monitoring: 위험하거나 비정상적인 행동을 탐지하고 대응한다.
• Alignment: 모델이 유해하거나 승인되지 않은 행동을 할 가능성을 낮춘다.
• Security: 모델이 접근하거나 영향을 줄 수 있는 시스템 범위를 제한한다.

OpenAI는 장기적으로 AI 모델이 다른 AI 모델을 방어하는 작업을 포함해 상당수의 보안 작업을 직접 수행하게 될 것으로 예상한다.

3. 연구 환경의 보안 강화

프런티어 모델의 사이버 보안 능력이 향상되면서 학습과 평가 환경에 대한 보안 요구도 높아지고 있다. OpenAI는 다음 세 가지를 강화하고 있다.

• Workload isolation: 모델이 생성한 코드나 신뢰할 수 없는 코드를 실행하는 작업을 더 강력한 샌드박스 환경에서 수행한다.

• Network isolation: 위험도가 높은 워크로드가 인터넷이나 내부 네트워크에 자유롭게 접근하지 못하도록 제한한다.

• Continuous security testing: 불필요한 공유 서비스를 제거하고 상시 권한을 줄이며, 로그 수집과 보안 경계 검증을 강화한다. AI 모델을 이용해 이러한 보안 경계를 지속적으로 공격 테스트하는 자동화도 진행하고 있다.

현재 애스트라(Astra)와 사이버 보안 관련 모델에는 가장 강한 수준의 보안 기준이 적용되고 있다.

4. Chain-of-Thought 모니터링 확대

OpenAI는 모델 내부 행동에 대한 모니터링도 크게 확대했다. 새로운 시스템은 여러 단계로 구성된다. 모델 내부 활동을 검사하는 activation classifier가 샘플링되는 각 토큰에서 동작하며, 문제가 의심되는 경우 더 많은 연산 자원을 사용하는 자동 조사 시스템으로 전달한다.

이 시스템은 모델의 도구 사용, 이용 가능한 사고 과정, 전체 행동 흐름을 분석해 다음과 같은 행동을 탐지한다.

• 승인되지 않은 시스템 접근
• 데이터 탈취
• 파괴적 행동
• 안전장치 우회 시도

위험 행동이 탐지되면 OpenAI는 약 30분 이내에 경고를 발생시키는 것을 목표로 하고 있다. 심각한 보안 경계 위반 가능성이 있을 경우 안전, 보안, 연구팀이 함께 검토하며 명확한 오탐으로 판단되지 않으면 해당 작업을 중단한다.

이 모니터링에는 상당한 연산 비용도 필요하다. OpenAI는 현재 모니터링 비용을 감시 대상 추론 연산량의 약 20% 수준으로 추정하고 있다.

5. Alignment 연구도 강화한다

모델의 능력이 커질수록 단순한 보안 격리만으로는 충분하지 않다. 특히, 강화학습에서는 reward hacking 문제가 중요하다. 모델이 실제 목표를 달성하지 않고도 평가기, 보상 함수, 도구의 허점을 이용해 높은 보상을 받는 행동을 학습할 수 있기 때문이다.

OpenAI는 이를 줄이기 위해 보상 모델을 개선하고, 모델이 자신의 행동과 능력, 한계를 더 정직하게 표현하도록 학습하며, 평가 시스템이나 도구의 취약점을 악용하는 행동을 억제하고 있다.

6. 앞으로의 방향

OpenAI는 기존 Preparedness Framework를 확장해 모델 자체의 능력뿐만 아니라 학습 환경과 배포 환경까지 함께 고려하는 방향으로 발전시킬 계획이다.

프런티어 모델의 성능 향상 속도보다 모델을 이해하고 정렬하고 보호하는 기술의 발전 속도가 뒤처져서는 안 된다는 것이다. 개발자 관점에서도 의미가 크다. 앞으로 AI 시스템 개발에서는 모델 성능뿐 아니라 Sandbox, Network Isolation, Least Privilege, Agent Monitoring, Alignment Evaluation, Security Logging 등과 같은 요소가 더욱 중요해질 것이다.

AI 에이전트가 실제 코드, 네트워크, 클라우드 시스템과 연결되기 시작하면서 AI 안전성은 더 이상 모델 연구만의 문제가 아니다. 점점 시스템 아키텍처와 보안 엔지니어링의 문제가 되고 있다.

• 출처: OpenAI, Pacing model development in an era of cyber-critical capabilities

OpenAI가 오늘부터 ChatGPT for Teens를 전 세계의 대상 청소년 계정에 순차적으로 도입하기 시작했다. 핵심은 별도의 “청소년용 저성능 ChatGPT”를 만드는 것이 아니라, 기존 ChatGPT 능력을 유지하면서 18세 미만 사용자에게 학습 기능과 안전장치를 추가하는 것이다.

주요 내용을 정리하면 다음과 같다.

• 18세 미만 계정에 자동 적용된다. 계정에 등록된 나이, 연령 인증 또는 OpenAI의 연령 추정 시스템을 통해 18세 미만으로 판단되면 사용자가 별도로 켜지 않아도 ChatGPT for Teens가 활성화된다.
• 학습 기능이 강화된다. Study Mode를 이용해 정답만 바로 제시하기보다 힌트, 단계별 설명, 후속 질문, 이해도 확인 등을 제공할 수 있다. 숙제와 관련된 질문에는 Study Mode 사용을 권할 수도 있으며 퀴즈 같은 학습 도구도 지원한다.
• 스터디 시간을 설정할 수 있다. 청소년 본인 또는 연결된 부모·보호자가 특정 시간대에 새 대화를 자동으로 Study Mode에서 시작하도록 설정할 수 있다. 이것은 ChatGPT 사용 자체를 차단하는 기능과는 다르다.
• 과도한 사용을 줄이기 위한 장치도 들어간다. 일정 상황에서 휴식을 권하는 메시지를 보여주고, ChatGPT가 사람이나 교사가 아니라 AI 도구라는 점을 다시 알려주는 알림이 제공될 수 있다. 이미지 업로드 전에는 개인정보나 민감한 정보가 포함돼 있지 않은지 확인하라는 안내도 표시될 수 있다.
• 청소년에게 부적절하거나 위험할 수 있는 콘텐츠에 대한 보호 장치가 강화된다. 즉 일반 계정보다 연령에 맞춘 안전 정책이 추가 적용된다.

그리고 부모 통제 기능에서 꽤 중요한 부분이 하나 있다. 부모나 보호자가 계정을 연결해 일부 설정, 스터디 시간, 사용 시간 제한 등을 관리할 수 있지만, 부모가 청소년의 ChatGPT 대화 내용을 직접 읽거나 감시할 수는 없다. 제한적인 안전 알림 상황에서도 OpenAI는 청소년의 안전을 지원하는 데 필요한 정보만 제공한다고 설명한다.

또한 사용 시간 제한을 사용하면 지정된 시간 동안 ChatGPT 접근 자체를 제한할 수 있다. 반면 공부 시간은 접근을 막는 것이 아니라 새 대화를 학습 중심 모드로 시작하도록 하는 기능이다. 18세가 되면 ChatGPT가 사용자를 성인으로 확인한 뒤 청소년 보호 설정을 해제하고 일반 ChatGPT 환경으로 전환할 수 있으며, 연결된 부모 통제 관계도 종료될 수 있다. 다만 일부 보호 기능은 이후 다시 설정할 수 있다.

특히 흥미로운 변화는 OpenAI가 청소년용 ChatGPT를 단순한 콘텐츠 필터링 제품으로 만들기보다, Study Mode → Study Hours → Quiz → Break reminder → Parental Controls 처럼 AI 튜터의 사용 방식 자체를 설계하려 한다는 점이다. 현재 기능은 지역별로 차이가 있으며, OpenAI는 향후 몇 주 동안 제공 범위를 확대할 예정이라고 밝혔다

첫째, Agentic AI 시대에는 모델 서빙의 최적화 단위가 “한 번의 LLM 추론”이 아니라 “전체 Agent control loop”가 된다.

둘째, 프로덕션 LLM 플랫폼은 단순 GPU inference server가 아니라 API → orchestration → resource management → distributed serving → inference → optimization으로 분리된 계층형 시스템이어야 한다.

셋째, Bedrock과 직접 구축 중 어느 것이 더 좋은지는 고정된 답이 없으며, E2E/TTFT/ITL과 RPS/TPS, 비용, 트래픽 패턴을 측정하면서 필요에 따라 스펙트럼상의 위치를 이동하는 것이 가장 현실적인 전략이다.

             Agentic Application
                     │
        한 요청에서 여러 호출 발생
                     │
                     ▼
       Serving Complexity 증가
                     │
                     ▼
     Enterprise Layered Architecture
                     │
          ┌──────────┴───────────┐
          │                      │
     Cloud Managed            Build
       Bedrock            K8s/Ray/vLLM
          │                      │
          └──────────┬───────────┘
                     │
            어느 쪽이 더 좋은가?
                     │
                     ▼
             Performance 측정
                     │
          ┌──────────┴─────────┐
          │                    │
      Latency              Throughput
 E2E / TTFT / ITL         RPS / TPS
          │                    │
          └──────────┬─────────┘
                     │
                     ▼
            Cost / SLO 판단
                     │
                     ▼
          Build ↔ Cloud 위치 조정

1. 에이전트 Agentic 워크플로우가 등장하면서 모델 서빙 요구사항은 어떻게 달라지는가?

모델 서빙의 단위가 “한 번의 추론”에서 “하나의 작업을 끝내기 위한 반복적인 제어 루프”로 바뀐다는 것이다. 전통적인 LLM 서비스는 대체로 다음과 같다.

User
↓
LLM
↓
Response

요청 한 번에 모델을 한 번 호출하고 응답하면 끝난다. 에이전틱 시스템에서는 구조가 달라집니다.

User
↓
Agent
↓
Planning ──→ LLM
↓
Retrieval ─→ Embedding / Vector DB
↓
Reasoning ─→ LLM
↓
Tool Call ─→ API / DB / Search
↓
Result
↓
LLM
↓
필요하면 다시 반복
↓
Final Answer

즉, > 1 User Request ≠ 1 Model Request가 된다. Knowledge Agent 실습이 좋은 예이다. 사용자가 단 한 번 질문했지만 내부적으로는

Planner LLM      1회
Query Embedding  1회
Summary LLM      1회
Analysis LLM     1회
----------------------
총 API 호출 4회

가 발생했다.

1-1. 서빙 시스템에 생기는 5가지 변화

• 토큰 사용량 증가: Planner, RAG context, tool result, intermediate result가 다음 LLM 호출에 계속 들어가므로 요청당 토큰 소비량이 급격히 증가한다.

• 지연 시간 증폭(Latency amplification): Agent workflow가 직렬로 연결되어 있다면,

Total Agent Latency
≈ L1 + L2 + L3 + ... + Ln

처럼 각 단계의 E2E latency가 누적된다. 예를 들어,

Planning       0.7s
RAG            0.3s
Summary        1.4s
Analysis       2.0s
------------------
Agent E2E      4.4s

가 될 수 있다. 특히 다음 단계가 이전 단계의 전체 결과를 필요로 한다면 TTFT가 아무리 빨라도 전체 작업은 빨라지지 않는다.

• 동적인 트래픽 패턴: 단순 질문은 LLM 한 번으로 끝날 수도 있지만 복잡한 질문은 5회, 10회, 20회 호출할 수도 있다. 따라서, User RPS = 10 이라고 해서 Model RPS = 10인 것이 아니다. 평균적으로 한 요청이 LLM을 6번 호출한다면 실질적으로는 10 user RPS × 6 calls ≈ 60 model RPS가 된다.

• 여러 모델을 동시에 서빙해야 하는 문제: 현대 에이전트는 보통 하나의 모델만 쓰지 않는다.

Planner    → Small/Reasoning LLM
Generation → Large LLM
Embedding → Embedding Model
Vision → VLM
Speech → ASR/TTS
Reranker → Ranking Model

그래서 모델 선택과 오케스트레이션(orchestration)이 코어 추론(Core Inference)만큼 중요해진다.

• 상태와 메모리 관리: 이전 호출의 결과, tool result, conversation history, RAG context, KV cache 등을 다음 호출에서 재사용해야 한다. 그래서 에이전틱 서빙(Agentic Serving)에서는 다음 기술의 중요성이 크게 올라간다.

KV Cache
Prompt Cache
CAG
Cache-aware Routing
Continuous Batching
Scheduler
Model Routing
Tool Orchestration
Observability

1-2. RAG와 CAG의 의미도 달라진다

RAG는 매 요청마다 외부 지식(nowledge)을 검색한다.

Query
    → Embedding
    → Vector Search
    → Retrieved Context
    → LLM

장점은 최신성과 동적 지식이다. 반면 문맥 증강 생성(CAG,Context-Augmented Generation)는 자주 재사용하는 지식을 미리 문맥과 KV 캐시에 올려 놓는다.

Knowledge
    → Prefill once
    → KV Cache
        ↓
Query → reuse

따라서 반복적인 에이전틱 워크로드에서는 RAG와 CAG를 경쟁 관계라기보다

RAG = 지식 검색 최적화 CAG = 반복 추론 실행 최적화

로 볼 수 있다.

2. 엔터프라이즈 LLM 서빙 플랫폼의 계층형 아키텍처는 어떻게 구성되며 Kubernetes/Ray Serve에서는 어떻게 구현하는가?

엔터프라이즈급 플랫폼에서 중요한 생각은

“LLM을 GPU에서 실행하는 것”과 “LLM 서비스를 운영하는 것”은 완전히 다른 문제다.

전체 구조를 단순화하면 다음과 같다.

             Client / Agent
                    │
                    ▼
┌──────────────────────────────────┐
│ 1. Public API                    │
│ Auth / Rate Limit / Billing      │
└──────────────────────────────────┘
                    │
                    ▼
┌──────────────────────────────────┐
│ 2. Model Selection              │
│ Routing / Cost / Quality / SLA   │
└──────────────────────────────────┘
                    │
                    ▼
┌──────────────────────────────────┐
│ 3. Resource Management          │
│ GPU / CPU / Memory / Scheduling  │
└──────────────────────────────────┘
                    │
                    ▼
┌──────────────────────────────────┐
│ 4. Distributed Serving          │
│ Multi-GPU / Cache / Multi-node   │
└──────────────────────────────────┘
                    │
                    ▼
┌──────────────────────────────────┐
│ 5. Core Inference               │
│ vLLM / TRT-LLM / SGLang          │
└──────────────────────────────────┘
                    │
                    ▼
┌──────────────────────────────────┐
│ 6. Model Optimization           │
│ Quant / Spec Decode / Kernels    │
└──────────────────────────────────┘
                    │
                    ▼
┌──────────────────────────────────┐
│ 7. Models                        │
│ Base / FT / Adapter / Version    │
└──────────────────────────────────┘

2.1 Layer 1 - 공인 API

역할은 외부 트래픽을 안전하게 받아들이는 것이다.

Authentication
Authorization
Tenant
Quota
Rate Limit
Billing
Routing
DDoS protection

Open Source에서는 보통

FastAPI
+
Kubernetes Service
+
Ingress / Gateway
+
Redis
+
JWT / API Key

등으로 구현할 수 있다. 예를 들어 두 단계의 요청 제한(rate limiting)이 가능하다.

Ingress
→ global rate limit

FastAPI
→ tenant-specific quota

이는 심층 방어(defense-in-depth) 구조이다.

2-2. Layer 2 - 모델 선택과 오케스트레이션

모든 요청에 가장 큰 모델을 쓰는 것은 비효율적이다.

Simple Request
↓
Small Model

Complex Reasoning
↓
Large Model

이 레이어에서 최적화하는 품질(Quality), 지연시간(latency) 비용 등 세 가지가 있다. 또한 모델 라우팅(Model routing), 카나리 배포(Canary deployment), 테넌트 지정 모델(Tenant-specific model), 추측 디코딩(Speculative decoding), 대체 경로(Fallback), 로드 밸런싱(Load Balancing) 등도 수행한다.

예를 들어:

if long_generation:
    speculative_decode()
else:
    normal_model()

처럼 모델 실행 전략 자체를 바꿀 수도 있다.

2-3. Layer 3 - 리소스 관리

레이어3는 모델보다 GPU라는 희소 자원이 중심이다. 질문은 이런 것이다.

누가 GPU를 사용할 것인가?
몇 GPU를 할당할 것인가?
H100과 L40S 중 무엇을 사용할 것인가?
GPU utilization은 얼마인가?
Priority workload는 무엇인가?

Kubernetes에서는 이를 포드(Pod), 스케줄러, GPU 오퍼레이터, 디바이스 플러그인(Device Plugin), 노드 셀렉터(Node Selector), 노드 배제 설정과 파드 허용 규칙(Taint/Toleration), HPA, 큐(Kueue), 카펜터(Karpenter) 등으로 관리할 수 있다.

Ray에서는

ray_actor_options={
    "num_gpus": 1
}

같은 식으로 애플리케이션이 필요한 리소스를 선언할 수 있다.

2.4 Layer 4 - 분산 서빙

모델이 하나의 GPU에 들어가지 않을 때 필요하다. 예를 들어, Model Weight = 160 GB, GPU VRAM = 80 GB 라면 최소 2 GPU가 필요합니다. 대표 기술은

Tensor Parallel
Pipeline Parallel
Data Parallel
Prefill/Decode Disaggregation
Distributed KV Cache
Prompt Cache
Cache-aware Routing

이다. 예를 들어,

Node 1: GPU × 8 → TP=8
Node 2: GPU × 8 → TP=8
Inter-Node (노드 간) → PP=2

처럼 구성할 수 있다.

2.4 Layer 5 - 코어 추론(Core Inference)

여기가 실제 토큰 계산이 일어나는 부분이다. 대표 추론 엔진은 vLLM, TensorRT-LLM, SGLang, Triton 등이다. 그리고 아래쪽에는

FlashAttention
PagedAttention
GEMM
CUDA kernels

같은 최적화가 존재한다. 구조적으로는

Ray Serve
↓
vLLM
↓
PyTorch / CUDA
↓
GPU

이다. Ray Serve와 vLLM의 역할을 혼동하면 안 됩된다.

Ray Serve = 서비스 오케스트레이션 / 스케일링 vLLM = LLM 추론 엔진

이다.

2.5 Layer 6 - 모델 최적화(Model Optimization)

모델 최적화는 모델을 새로 학습하지 않고 추론 효율을 높인다.

대표 기술로는 다음과 같다.

FP8
INT8
INT4
AWQ
GPTQ
Speculative Decoding
KV Cache optimization
Kernel fusion
Continuous batching

모든 최적화가 같은 지표를 좋아지게 하는 것은 아니다. 예를 들어 처리량(throughput)을 극대화하기 위해 배치를 크게 하면 TTFT는 악화될 수 있다.

2.6 Kubernetes + KubeRay + Ray Serve + vLLM로 합치면

제 4 장 오픈소스 구현을 가장 간결하게 나타내면:

                Internet
                     │
                Ingress/Gateway
                     │
                  FastAPI
                     │
               Model Router
                     │
               Ray Serve
                     │
          ┌──────────┴─────────┐
          │                    │
     LLMServer             LLMServer
          │                    │
        vLLM                  vLLM
          │                    │
        GPU 0                 GPU 1

────────────────────────────────────

Kubernetes
├─ Networking
├─ Pod lifecycle
├─ GPU allocation
├─ Scaling
└─ Monitoring

KubeRay
└─ Ray lifecycle

Ray Serve
├─ Deployment
├─ Replica
├─ Routing
├─ Autoscaling
└─ Multiplexing

vLLM
├─ PagedAttention
├─ KV cache
├─ Continuous batching
└─ Token generation

특히 프로덕션 서빙에서는 RayCluster보다 RayService가 자연스럽다.

RayCluster = Ray Computing Cluster Management
RayService = RayCluster
    + Ray Serve Application
    + Health Check
    + Rolling Update
    + HA

그래서 KubeRay 기반 LLM serving의 전형적인 구조는

Kubernetes
↓
KubeRay Operator
↓
RayService
↓
Ray Serve
↓
vLLM
↓
GPU

가 된다.

3. Build vs Cloud는 어떤 기준으로 선택하며, 무엇을 측정해야 하는가?

가장 중요한 결론부터 말하면:

Build vs Buy가 아니라 Control Spectrum이다.

즉 다음 두 극단 사이에서 움직이는 문제이다.

    Managed                                      DIY

Bedrock
↓
JumpStart
↓
BYO Model
↓
BYO Code
↓
BYO Container
↓
EKS + Ray Serve + vLLM

왼쪽으로 갈수록

Ease of Use ↑
Operation burden ↓
Control ↓

오른쪽으로 갈수록

Control ↑
Optimization freedom ↑
Operation burden ↑

이다.

3-1. AWS 6단계로 보면

3.1 선택 기준 1 - 시장 출시(Time to Market)

PoC 단계라면 Bedrock 같은 관리형 API가 매우 유리한다. 모델 서빙 플랫폼 구축에 몇 주를 쓰는 대신 바로 애플리케이션 검증이 가능하다.

3.2 선택 기준 2 - 맞춤화(Customization)

다음과 같은 요구가 생기면 오른쪽으로 이동한다.

Custom batching
Custom routing
Quantization
Speculative decoding
Custom CUDA kernel
Custom vLLM version
GPU sharing
KV cache routing
Prefill/decode separation

이런 요구는 관리형 API에서 구현하기 어렵다.

3.2 선택 기준 3 - 트래픽 볼륨(Traffic Volume)

트래픽이 작거나 불규칙하면 서버리스가 유리하다.

Low / burst traffic → Bedrock

반대로 항상 높은 부하가 유지된다면

High sustained traffic → Dedicated GPU

가 비용 면에서 유리할 수 있다. 따라서 중요한 질문은

“얼마나 많은 요청이 들어오느냐?”보다 “얼마나 많은 토큰을 얼마나 지속적으로 처리하느냐?”

이다.

3.3 선택 기준 4 - 비용(Cost)

관리형 API는 보통 $/token이고 직접 호스팅은 $/GPU-hour 이다. 따라서 어느 지점에서는 손익분기점이 생긴다. 개념적으로 API cost / sec = Tokens/sec × Price/token 과 GPU cost / sec를 비교하면 된다.

트래픽이 충분히 크고 일정하면 전용 GPU가 유리해질 가능성이 커진다. 반면 utilization이 5~10% 수준이라면 비싼 GPU를 24시간 유지하는 것보다 관리형 API가 더 저렴할 수 있다.

그래서 반드시 성능을 측정해야 한다. Build vs Cloud 판단은 느낌으로 하는 것이 아니라 SLO + 비용 + 성능 지표로 해야 한다. 가장 중요한 지표는 크게 지연시간과 처리량 두 종류이다.

4 지연시간(Latency)

4.1 E2E Latency

Request
│
├─ Queue
├─ Routing
├─ Prefill
├─ Decode
├─ Network
↓
Response Complete

전체 시간이다. 에이전틱 워크플로에서는 중요하다. 왜냐하면,

Agent E2E ≈ Step1 E2E
    + Step2 E2E
    + Step3 E2E
    + ...

가 되기 때문이다.

4.2 TTFT - Time To First Token

Request
↓
Prefill
↓
First Token

첫 토큰이 나올 때까지의 시간이다. 사용자가 느끼는 **“응답이 시작되는 속도”**이다. 그래서 Chat UI에서는 매우 중요하다.

4.3 ITL / TPOT

첫 토큰 이후 토큰 사이의 간격이다. Token1 ──40ms── Token2 ──40ms── Token3 라면 `ITL ≈ 40 ms’ 이다. 출력이 길수록 중요하다.

4.4 이들의 관계

출력 토큰이 N이고 ITL이 일정하다고 단순화하면:

E2E ≈ TTFT + ITL × (N - 1)

예:

TTFT = 0.5 sec
ITL = 0.04 sec
N = 101
E2E
= 0.5 + 0.04 × 100
= 4.5 sec

이다.

5. 처리량(Throughput)

5.1 RPS

Requests / Second

예: 1177 requests / 300 sec ≈ 3.92 RPS

앞서 Ray Serve 실습 결과와 같다. 하지만 LLM에서는 RPS만 보면 위험하다.

Request A
10 input → 10 output

Request B
8000 input → 2000 output

둘을 똑같이 “1 request”로 계산하기 때문이다.

5-2. TPS

Generated Tokens / Second

LLM에서는 RPS보다 모델 처리 능력을 더 잘 보여준다. 하지만 이것도 조건을 명시해야 한다.

Input length
Output length
Concurrency
Batch size
Model
Precision
GPU
Context length

가 달라지면 TPS가 크게 달라진다. 그래서

Model A = 10,000 TPS
Model B = 8,000 TPS

라는 숫자만으로 A가 더 빠르다고 말해서는 안 된다.

중요: 이 프로젝트는 WSL Ubuntu 터미널을 사용하지 않는다. 개발 작업은 Windows 파일 시스템과 파워셀(PowerShell)에서 수행한다. Docker Desktop의 내부 리눅스 컨테이너 실행 방식은 사용자의 Docker Desktop 설정에 따라 달라질 수 있다.

1. 학습목표

전체 워크삽의 학습 목표를 완료하면 다음을 할 수 있다.

1. Windows Native Python 가상환경에서 Agents SDK 앱을 실행한다.
2. Agent와 Runner의 역할을 설명한다.
3. Python 함수를 function_tool로 Agent Tool에 연결한다.
4. Handoff를 이용해 사용자 요청을 전문 Agent로 전달한다.
5. Agents SDK 앱을 FastAPI REST API로 감싼다.
6. Windows에서 Linux Docker image를 빌드한다.
7. API Key를 Docker image에 넣지 않고 런타임에 전달한다.
8. 동일 이미지를 Public Cloud와 On-Premises로 이동하는 원리를 설명한다.

2. 전체 목차

• [실습] OpenAI 에이전트 도커 워크삽 (2)-환경설정
• [실습] OpenAI 에이전트 도커 워크삽 (3)-agents 분석
• [실습] OpenAI 에이전트 도커 워크삽 (4)-main 소스분석
• [실습] OpenAI 에이전트 도커 워크삽 (5)-FastAPI 서비스
• [실습] OpenAI 에이전트 도커 워크삽 (6)-Dockerfile 과 docker-compose
• [실습] OpenAI 에이전트 도커 워크삽 (7)-리눅스 이미지 빌드
• [실습] OpenAI 에이전트 도커 워크삽 (8)-도커 컨테이너

1. 실습 11 - 도커 허브 또는 사설 레지스트리로 이동

예를 들어 Docker Hub를 사용할 경우:

docker login

docker tag openai-agents-workshop:1.0 `
  YOUR_DOCKER_ID/openai-agents-workshop:1.0

docker push YOUR_DOCKER_ID/openai-agents-workshop:1.0

Public Cloud/On-Premises Linux 서버에서는:

docker pull YOUR_DOCKER_ID/openai-agents-workshop:1.0

docker run -d \
  --name openai-agents-workshop \
  -p 8000:8000 \
  -e OPENAI_API_KEY="$OPENAI_API_KEY" \
  -e OPENAI_DEFAULT_MODEL="gpt-5.6-luna" \
  YOUR_DOCKER_ID/openai-agents-workshop:1.0

같은 이미지를 사용하므로 애플리케이션 코드와 파이썬 종속성(Python dependency)를 서버마다 다시 설치할 필요가 없다.

2. 실습 12 - 퍼블릭 클라우드 및 온-프레미시스 배포 개념

                  Container Registry
                         │
              openai-agents-workshop
                         │
          ┌──────────────┼──────────────┐
          │              │              │
          ▼              ▼              ▼
       AWS/Azure        GCP          On-Prem
          │              │              │
    Docker / K8s   Docker / K8s   Docker / K8s
          └──────────────┼──────────────┘
                         │
                         ▼
                     OpenAI API

배포 환경에서 달라지는 것은 주로 다음이다.

• API Key / Secret 관리 방식
• 네트워크와 Proxy/Firewall
• TLS/Ingress
• 로그 수집
• Auto Scaling
• Container Registry
• Kubernetes resource 설정

애플리케이션 이미 자체는 동일하게 유지할 수 있다.

실습 13 - ARM64까지 지원하는 멀티 플랫폼 이미지

AMD64 서버와 ARM64 서버를 동시에 지원하려면 Buildx를 사용할 수 있다.

docker buildx build `
  --platform linux/amd64,linux/arm64 `
  -t YOUR_DOCKER_ID/openai-agents-workshop:1.0 `
  --push .

레지스트리에는 여러 아키텍처 매니페스트(architecture manifest)가 하나의 이미지 태그(image tag) 아래와 같이 저장된다.

openai-agents-workshop:1.0
        │
        ├─ linux/amd64
        └─ linux/arm64

각 서버는 자신의 CPU 아키텍처에 맞는 변종(variant)를 자동으로 pull할 수 있다.

1. 실습 11 - 도커 허브 또는 사설 레지스트리로 이동

예를 들어 Docker Hub를 사용할 경우:

docker login

docker tag openai-agents-workshop:1.0 `
  YOUR_DOCKER_ID/openai-agents-workshop:1.0

docker push YOUR_DOCKER_ID/openai-agents-workshop:1.0

Public Cloud/On-Premises Linux 서버에서는:

docker pull YOUR_DOCKER_ID/openai-agents-workshop:1.0

docker run -d \
  --name openai-agents-workshop \
  -p 8000:8000 \
  -e OPENAI_API_KEY="$OPENAI_API_KEY" \
  -e OPENAI_DEFAULT_MODEL="gpt-5.6-luna" \
  YOUR_DOCKER_ID/openai-agents-workshop:1.0

같은 이미지를 사용하므로 애플리케이션 코드와 파이썬 종속성(Python dependency)를 서버마다 다시 설치할 필요가 없다.

2. 실습 12 - 퍼블릭 클라우드 및 온-프레미시스 배포 개념

                  Container Registry
                         │
              openai-agents-workshop
                         │
          ┌──────────────┼──────────────┐
          │              │              │
          ▼              ▼              ▼
       AWS/Azure        GCP          On-Prem
          │              │              │
    Docker / K8s   Docker / K8s   Docker / K8s
          └──────────────┼──────────────┘
                         │
                         ▼
                     OpenAI API

배포 환경에서 달라지는 것은 주로 다음이다.

• API Key / Secret 관리 방식
• 네트워크와 Proxy/Firewall
• TLS/Ingress
• 로그 수집
• Auto Scaling
• Container Registry
• Kubernetes resource 설정

애플리케이션 이미 자체는 동일하게 유지할 수 있다.

실습 13 - ARM64까지 지원하는 멀티 플랫폼 이미지

AMD64 서버와 ARM64 서버를 동시에 지원하려면 Buildx를 사용할 수 있다.

docker buildx build `
  --platform linux/amd64,linux/arm64 `
  -t YOUR_DOCKER_ID/openai-agents-workshop:1.0 `
  --push .

레지스트리에는 여러 아키텍처 매니페스트(architecture manifest)가 하나의 이미지 태그(image tag) 아래와 같이 저장된다.

openai-agents-workshop:1.0
        │
        ├─ linux/amd64
        └─ linux/arm64

각 서버는 자신의 CPU 아키텍처에 맞는 변종(variant)를 자동으로 pull할 수 있다.

1. 준비 사항

• Windows 11
• Visual Studio Code
• Python 3.10 이상 (권장: Python 3.12)
• Docker Desktop
• OpenAI API Key
• PowerShell 7 권장

Docker Desktop에서 Linux containers를 사용할 수 있어야 한다.

확인:

docker version
docker info --format ''

두 번째 명령 결과가 다음이면 된다.

linux

2. 전체 아키텍처

Windows 11 Native - Operating System 
  ├─ VS Code
  ├─ PowerShell
  ├─ Python 3.12 + .venv
  └─ Docker Desktop
         │
         │ docker build --platform linux/amd64
         ▼
   Linux Docker Image
   openai-agents-workshop:1.0
         │
         ├─ Docker Desktop
         ├─ Linux Docker Engine
         ├─ AWS / Azure / GCP
         └─ On-Premises / Kubernetes
                │
                ▼
             OpenAI API

그리고 프로젝트 구조는 다음과 같다.

openai-agents-docker-workshop/
├─ app/
│  ├─ __init__.py
│  ├─ agents_app.py
│  └─ main.py
├─ scripts/
│  ├─ setup.ps1
│  ├─ run-native.ps1
│  ├─ build-image.ps1
│  ├─ run-container.ps1
│  ├─ test-api.ps1
│  └─ verify-image.ps1
├─ .dockerignore
├─ .env.example
├─ .gitignore
├─ docker-compose.yml
├─ Dockerfile
├─ requirements.txt
└─ README.md

3. Visual Studio Code 에서 프로젝트 열기

• Github 주소에서 소스들을 다운로드 받아서 PowerShell에서 프로젝트 폴더로 이동한다.

cd C:\Projects\openai-agents-docker-workshop
git clone https://github.com/synabreu/openai-agents-docker-workshop.git
code .

VS Code Terminal이 PowerShell인지 확인한다. 확인하는 방법은 아래의 그림과 같다.

4. 실습 1- Windows 11 운영체제 상에서 Python 환경 만들기

• 실습 환경을 자동 설정하려면 다음과 같이 하면 된다.

Set-ExecutionPolicy -Scope Process Bypass
.\scripts\setup.ps1

• 만일 그렇지 않고 수동으로 한다면 다음과 같다.

python -m venv .venv
.\.venv\Scripts\Activate.ps1
python -m pip install --upgrade pip
pip install -r requirements.txt

• 둘 다 모두 설치 확인하려면 다음과 같다.

pip show openai-agents

• Agents SDK의 핵심 실행 흐름은 다음과 같다.

사용자 입력
   ↓
Agent
   ↓
Runner
   ↓
Model / Tool / Handoff
   ↓
RunResult.final_output

5. Setup.ps1 파워셀 소스 분석

$ErrorActionPreference = "Stop"

Write-Host "[1/4] Creating Python virtual environment..."
python -m venv .venv

Write-Host "[2/4] Activating virtual environment..."
& .\.venv\Scripts\Activate.ps1

Write-Host "[3/4] Upgrading pip..."
python -m pip install --upgrade pip

Write-Host "[4/4] Installing dependencies..."
pip install -r requirements.txt

Write-Host "Done. Next: `$env:OPENAI_API_KEY='YOUR_KEY'"

• $ErrorActionPreference = "Stop" : 스크립트 실행 중 오류가 발생하면 무시하지 말고 즉시 중단하라. 파워셀의 기본값은 continue 이다.
• `Write-Host’ : PowerShell 콘솔 화면에 문자열 출력

1. 실습 2 - OpenAI Key 설정

현재 파워셀 세션에서만 환경변수를 설정한다.

$env:OPENAI_API_KEY="YOUR_OPENAI_API_KEY"
$env:OPENAI_DEFAULT_MODEL="gpt-5.6-luna"

일반 실습에서는 비용을 낮추기 위해 gpt-5.6-luna를 기본값으로 사용한다. 필요하면 gpt-5.6-terra 또는 gpt-5.6-sol로 바꿀 수 있다.

확인할 때 API Key 전체를 출력하지 않는 편이 안전하다.

if ($env:OPENAI_API_KEY) { "OPENAI_API_KEY is set" }

보안을 위해 .env, Dockerfile, Git repository에 실제 API Key를 넣지 않는다.

2. 실습 3 - Simple Agent 분석

app/agents_app.py의 첫 번째 에어전트는 다음 구조다.

simple_agent = Agent(
    name="Simple Assistant",
    model=MODEL,
    instructions="You are a beginner-friendly assistant...",
)

실행은 다음 코드가 담당한다.

result = await Runner.run(AGENTS[agent_name], message)

Runner.run()은 비동기 환경에서 에이전트(Agent loop)를 수행하고 최종 결과를 반환한다.

3. 실습 4 - Function Tool 작성

파이썬 함수를 에어전트가 호출할 수 있는 도구(Tool)로 만든다.

@function_tool
def calculate_total(price: float, quantity: int) -> str:
    total = price * quantity
    return f"total={total:.2f}"

그리고 Agent 클래스에 등록한다. tool_agent 안에 tools 변수에 `calculate_total’ 함수명을 넣는다.

tool_agent = Agent(
    name="Shopping Assistant",
    model=MODEL,
    tools=[calculate_total],
)

전체 핵심 흐름은 아래의 예와 같다.

"12,500원 상품 3개 총액"
          ↓
       Agent
          ↓
  calculate_total Tool 호출
          ↓
       37,500
          ↓
      최종 응답

4. 실습 5 - Handoff / 멀티 에이전트 작성

두 전문 Agent를 만든다.

Deployment Triage Agent
        │
        ├── Public Cloud 질문 → Cloud Specialist
        │
        └── On-Prem 질문     → On-Prem Specialist

코드에서는 다음처럼 연결한다.

triage_agent = Agent(
    name="Deployment Triage Agent",
    model=MODEL,
    instructions="...",
    handoffs=[cloud_agent, onprem_agent],
)

Handoff는 단순 함수 호출과 다르다. 전문 Agent가 현재 turn의 active agent가 되어 응답을 이어갈 수 있다. 다시 말해, handoff는 현재 에이전트가 사용자의 요청을 더 적합한 전문 에이전트에게 넘기고, 그 에이전트가 이후 실행의 주체가 되도록 하는 기능입니다. 위의 설정은 다음과 같이 동작합니다.

• Runner가 먼저 triage_agent를 실행함.
• cloud_agent와 onprem_agent로 전환할 수 있는 handoff 도구를 모델에 제공함.
• triage_agent는 사용자 요청과 instructions를 바탕으로 적절한 에이전트를 선택함
• 선택된 에이전트로 실행 제어권과 대화 문맥이 전달됨
• Runner는 새 에이전트를 계속 실행하고 그 결과를 최종 출력으로 반환함

예를 들면:

흐름으로 표현하면 다음과 같다.

사용자 요청
    ↓
Deployment Triage Agent
    ├─ 클라우드 배포 요청 → cloud_agent
    └─ 사내 서버 배포 요청 → onprem_agent
                              ↓
                     전문 에이전트가 응답
                              ↓
                  RunResult.final_output

중요한 점은 handoffs=[...]에 등록했다고 해서 두 에이전트가 모두 실행되는 것은 아니라는 것이다. 모델이 요청에 맞는 에이전트를 선택했을 때만 handoff가 발생하며, 발생하지 않으면 triage_agent가 직접 응답할 수도 있다.

또한 handoff는 단순히 하위 작업을 부탁하고 결과를 돌려받는 것이 아니라, 대화의 주도권 자체를 대상 에이전트로 넘기는 방식이다. OpenAI 공식 예제에서도 triage 에이전트가 요청 언어를 판별해 적절한 언어 전문 에이전트로 전환한다.

5. 전체 소스

5.1 agents_app.py 파일 전체 분석

import os # 운영체제의 환경변수를 읽기 위한 Python 표준 라이브러리

# Agent:
# 모델, 지침, 도구, handoff 등을 구성하는 에이전트 클래스
#
# Runner:
# Agent를 실행하고 모델 호출, 도구 실행, handoff 과정을 관리하는 실행기
#
# function_tool:
# 일반 Python 함수를 Agent가 호출할 수 있는 Function Tool로 변환하는 데코레이터
from agents import Agent, Runner, function_tool


# OPENAI_DEFAULT_MODEL 환경변수의 값을 가져옴
# 환경변수가 없으면 기본값으로 "gpt-5.6-luna"를 사용함
MODEL = os.getenv("OPENAI_DEFAULT_MODEL", "gpt-5.6-luna")


# 이 데코레이터(@)는 calculate_total()을 Agent가 호출할 수 있는 Function Tool로 변환
@function_tool
def calculate_total(price: float, quantity: int) -> str:
    """
    상품 가격과 수량을 곱하여 총액을 계산함.

    Args:
        price: 상품 하나의 가격
        quantity: 상품 수량

    Returns:
        계산된 총액을 문자열로 반환
    """

    # 가격과 수량을 곱하여 총액 계산
    total = price * quantity

    # 소수점 둘째 자리까지 표시한 문자열 반환
    return f"total={total:.2f}"


# 일반적인 질문에 답변하는 기본 에이전트 객체
simple_agent = Agent(
    # Agent를 식별하는 이름
    name="simple_assistant",

    # Agent가 사용할 모델
    model=MODEL,

    # Agent의 역할과 응답 방식을 정의하는 지침
    instructions=(
        "You are a beginner-friendly assistant. "
        "Answer clearly and briefly."
    ),
)


# 상품 가격 계산을 지원하는 에이전트 객체
tool_agent = Agent(
    name="shopping_assistant",
    model=MODEL,

    # 가격과 수량의 곱셈이 필요한 경우 calculate_total 도구를 사용하도록 지시함
    instructions=(
        "You help users with simple shopping calculations. "
        "Use the calculate_total tool whenever multiplication "
        "of price and quantity is needed."
    ),

    # 이 Agent가 사용할 수 있는 Function Tool 목록
    tools=[calculate_total],
)


# AWS, Azure, GCP 등 퍼블릭 클라우드 배포를 담당하는 전문 에이전트
cloud_agent = Agent(
    name="cloud_specialist",
    model=MODEL,
    instructions=(
        "You are a cloud deployment specialist. "
        "Explain container deployment concepts for AWS, Azure, "
        "and GCP in beginner-friendly Korean."
    ),
)


# 사내 서버와 데이터센터 배포를 담당하는 전문 에이전트
onprem_agent = Agent(
    name="on_prem_specialist",
    model=MODEL,
    instructions=(
        "You are an on-premises container deployment specialist. "
        "Explain Docker and Kubernetes deployment concepts "
        "in beginner-friendly Korean."
    ),
)


# 사용자의 배포 질문을 분류하는 Triage 에이전트
triage_agent = Agent(
    name="deployment_triage_agent",
    model=MODEL,

    # 사용자 요청을 분석하여 적절한 전문 Agent를 선택하도록 지시함
    instructions=(
        "Classify the user's deployment question. "
        "If it is mainly about a public cloud, "
        "hand off to Cloud Specialist. "
        "If it is mainly about an on-premises environment, "
        "hand off to On-Prem Specialist. "
        "If neither is needed, answer directly."
    ),

    # Triage Agent가 실행 제어권을 넘길 수 있는 Agent 목록
    #
    # 클라우드 질문이면 cloud_agent,
    # 사내 환경 질문이면 onprem_agent로 handoff할 수 있음
    handoffs=[cloud_agent, onprem_agent],
)


# 외부에서 전달받은 문자열 이름을 실제 Agent 객체와 연결하는 딕셔너리
#
# 예:
# "simple" → simple_agent
# "tool"   → tool_agent
# "triage" → triage_agent
AGENTS = {
    "simple": simple_agent,
    "tool": tool_agent,
    "triage": triage_agent,
}


# 선택된 Agent를 비동기로 실행하는 애플리케이션 함수
async def run_agent(agent_name: str, message: str) -> dict:
    """
    Agent 이름과 사용자 메시지를 받아 해당 Agent를 실행합니다.

    Args:
        agent_name: 실행할 Agent 이름
        message: 사용자가 입력한 메시지

    Returns:
        최초 Agent 이름, 마지막으로 응답한 Agent 이름,
        최종 응답을 포함한 딕셔너리
    """

    # 등록되지 않은 Agent 이름이 전달되면 실행을 중단합니다.
    if agent_name not in AGENTS:
        raise ValueError(f"Unknown agent: {agent_name}")

    # 선택된 Agent와 사용자 메시지를 Runner에 전달함
    #
    # Runner는 다음 과정을 관리함
    # 1. 모델 호출
    # 2. Function Tool 실행
    # 3. Agent handoff
    # 4. 최종 응답 생성
    result = await Runner.run(
        AGENTS[agent_name],
        message,
    )

    # API에서 사용하기 편한 딕셔너리 형식으로 결과를 반환함
    return {
        # 사용자가 처음 선택한 에이전트
        "agent": agent_name,

        # handoff를 포함한 전체 실행에서 마지막으로 동작한 에이전트
        "last_agent": (
            result.last_agent.name
            if result.last_agent
            else None
        ),

        # 사용자에게 전달할 최종 응답
        "response": result.final_output,
    }

6. 참고 자료

OpenAI Developer Quickstart

1. main.py 파일 소스 분석

# FastAPI는 웹 API 애플리케이션을 생성하는 클래스
# HTTPException은 클라이언트에 HTTP 오류 응답을 반환하는 예외 클래스
from fastapi import FastAPI, HTTPException

# BaseModel은 요청과 응답 데이터의 구조를 정의하는 Pydantic 기본 클래스
# Field는 필드의 유효성 검사 조건과 문서 예시를 설정하는 함수
from pydantic import BaseModel, Field

# 지정한 Agent를 실행하고 결과를 반환하는 함수를 가져온다.
from app.agents_app import run_agent


# FastAPI 애플리케이션 객체를 생성하고, 설정한 정보는 Swagger UI와 OpenAPI 문서에 표시된다.
app = FastAPI(
    # API 문서에 표시되는 애플리케이션 이름
    title="OpenAI Agents SDK Docker Workshop",

    # API 버전 정보
    version="1.0.0",

    # 애플리케이션의 목적과 실행 환경
    description=(
        "Windows Native development -> "
        "Linux Docker image hands-on workshop"
    ),
)


# Agent API가 전달받을 요청 본문의 데이터 구조를 정의함
class ChatRequest(BaseModel):
    # 사용자가 Agent에게 보낼 메시지이며, 최소 한 글자 이상 입력하도록 검사한다.
    # examples는 Swagger UI에 표시할 요청 예시이다.
    message: str = Field(
        min_length=1,
        examples=["안녕하세요. 이 앱을 설명해줘."],
    )


# HTTP GET 방식의 루트 경로를 등록함
@app.get("/")
async def root():
    """
    애플리케이션의 기본 정보와 주요 API 경로를 반환한다.
    """

    return {
        # 애플리케이션 이름 반환
        "name": "OpenAI Agents SDK Docker Workshop",

        # Swagger API 문서의 경로 반환
        "docs": "/docs",

        # 서버 상태 확인 경로 반환
        "health": "/health",

        # 실행할 수 있는 에이전트 이름 반환
        "agents": ["simple", "tool", "triage"],
    }


# HTTP GET 방식의 서버 상태 확인 경로를 등록
@app.get("/health")
async def health():
    """
    애플리케이션이 정상적으로 실행 중인지 확인한다.
    """

    return {"status": "ok"}


# HTTP GET 방식으로 특정 에이전트를 실행하는 경로를 등록함
# {agent_name}에는 simple, tool, triage 등의 Agent 이름이 들어간다.
@app.get("/agents/{agent_name}")
async def chat(agent_name: str, request: ChatRequest):
    """
    URL에서 Agent 이름을 받고 요청 본문에서 메시지를 받아 Agent를 실행한다.
    """

    try:
        # 지정된 Agent를 비동기로 실행하고 결과를 반환함
        return await run_agent(
            agent_name,
            request.message,
        )

    except ValueError as exc:
        # 존재하지 않는 Agent 이름이 전달되면 404 오류를 반환함
        raise HTTPException(
            status_code=404,
            detail=str(exc),
        ) from exc

    except Exception as exc:
        # Agent 실행 중 예상하지 못한 오류가 발생하면 500 오류를 반환함
        raise HTTPException(
            status_code=500,
            detail=f"Agent execution failed: {exc}",
        ) from exc


# HTTP POST 방식으로 특정 Agent를 실행하는 경로를 등록한다.
@app.post("/agents/{agent_name}")
async def chat(agent_name: str, request: ChatRequest):
    """
    URL에서 Agent 이름을 받고 JSON 요청 본문에서 메시지를 받아 Agent를 실행한다.
    """

    try:
        # 지정된 Agent를 비동기로 실행하고 결과를 반환함
        return await run_agent(
            agent_name,
            request.message,
        )

    except ValueError as exc:
        # 존재하지 않는 Agent 이름이 전달되면 404 오류를 반환함
        raise HTTPException(
            status_code=404,
            detail=str(exc),
        ) from exc

    except Exception as exc:
        # Agent 실행 중 예상하지 못한 오류가 발생하면 500 오류를 반환함
        raise HTTPException(
            status_code=500,
            detail=f"Agent execution failed: {exc}",
        ) from exc

2. get/post 함수

GET과 POST 함수 이름이 모두 chat으로 동일하다. FastAPI 경로는 데코레이터가 등록하므로 실행될 수 있지만, 코드 가독성과 API 문서의 작업 식별을 위해 다음처럼 서로 다른 이름을 사용하는 것이 좋다.

@app.get("/agents/{agent_name}")
async def chat_get(agent_name: str, request: ChatRequest):
    ...


@app.post("/agents/{agent_name}")
async def chat_post(agent_name: str, request: ChatRequest):
    ...

또한 요청 본문을 전달하는 API는 일반적으로 GET보다 POST 방식을 사용한다. 따라서 실제 서비스에서는 POST 경로만 제공하는 구성이 더 자연스럽다.

1. 실습 6 - FastAPI로 서비스화

app/main.py는 Agents SDK를 HTTP API로 노출한다.

주요 엔드포인트:

Windows 11 운영체제 환경에서 실행한다.

.\scripts\run-native.ps1

웹 브라우저:

http://localhost:8010/docs

다른 파워셀 창에서 테스트한다.

.\scripts\test-api.ps1

여기까지는 Docker를 사용하지 않은 Windows 네이티브 개발 및 디버깅이다.

6-1. run-native.ps1 분석

$ErrorActionPreference = "Stop"

if (-not $env:OPENAI_API_KEY) {
    throw "OPENAI_API_KEY is not set. Example: `$env:OPENAI_API_KEY='sk-...'"
}

if (-not $env:OPENAI_DEFAULT_MODEL) {
    $env:OPENAI_DEFAULT_MODEL = "gpt-5.6-luna"
}

& .\.venv\Scripts\Activate.ps1
uvicorn app.main:app --host 127.0.0.1 --port 8010 --reload

위의 소스는 윈도우 11 환경으로 FastAPI 기반 OpenAI Agents SDK 애플리케이션을 실행하는 역할을 한다. OpenAI API Key 존재 여부 확인과 gpt-5.6-luna를 기본 모델 지정한다. 여기서 OpenAI API Key 를 보안 관계상 직접 입력하지 말고 파워쉘의 environment 변수를 통해 입력한다.

실행 흐름은 다음과 같다.

Uvicorn 실행
    ↓
app/main.py 모듈 불러오기
    ↓
main.py의 app 객체 찾기
    ↓
127.0.0.1:8010에서 서버 실행
    ↓
코드 변경 시 자동 재시작

실행 후 Swagger 문서는 다음 주소로 접속한다.

http://localhost:8010/docs

127.0.0.1은 외부 컴퓨터나 Docker 컨테이너 밖에서 접근하기 어렵다. Docker 컨테이너에서 실행한다면 일반적으로 다음처럼 0.0.0.0을 사용한다.

uvicorn app.main:app --host 0.0.0.0 --port 8010

–reload는 개발 편의 기능이므로 운영 환경에서는 일반적으로 사용하지 않는다.

6-2. test-api.ps1 소스 분석

# PowerShell 명령 실행 중 오류가 발생하면 스크립트를 즉시 중단한다.
$ErrorActionPreference = "Stop"


# ------------------------------------------------------------
# 1. Health Check API 테스트
# ------------------------------------------------------------

# 현재 실행할 테스트의 이름을 화면에 출력한다.
Write-Host "Health check"

# FastAPI 서버의 상태 확인 API를 GET 방식으로 호출한다.
# 서버가 정상적으로 실행 중이면 {"status": "ok"} 응답을 받는다.
Invoke-RestMethod `
    -Uri "http://localhost:8010/health" `
    -Method Get


# ------------------------------------------------------------
# 2. Simple Agent 테스트
# ------------------------------------------------------------

# `n은 줄바꿈을 의미한다.
# 한 줄을 띄운 후 테스트 이름을 화면에 출력한다.
Write-Host "`nSimple Agent"

# Agent에게 전달할 사용자 메시지를 PowerShell 해시 테이블로 작성한다.
# ConvertTo-Json은 해시 테이블을 JSON 문자열로 변환한다.
$body = @{
    message = "Docker image가 무엇인지 초보자에게 한 문장으로 설명해줘."
} | ConvertTo-Json

# simple Agent API를 POST 방식으로 호출한다.
#
# -Uri는 요청을 보낼 API 주소이다.
# -Method Post는 HTTP POST 방식을 사용한다.
# -ContentType은 요청 본문의 형식이 JSON임을 나타낸다.
# -Body는 앞에서 만든 JSON 메시지를 전달한다.
Invoke-RestMethod `
    -Uri "http://localhost:8010/agents/simple" `
    -Method Post `
    -ContentType "application/json" `
    -Body $body


# ------------------------------------------------------------
# 3. Function Tool Agent 테스트
# ------------------------------------------------------------

# 한 줄을 띄운 후 Tool Agent 테스트 이름을 출력한다.
Write-Host "`nTool Agent"

# 상품 가격과 수량 계산을 요청하는 메시지를 JSON으로 변환한다.
$body = @{
    message = "가격이 12500원인 상품 3개의 총액을 계산해줘."
} | ConvertTo-Json

# tool Agent API를 호출한다.
# tool Agent는 계산이 필요하다고 판단하면 calculate_total 도구를 호출한다.
Invoke-RestMethod `
    -Uri "http://localhost:8010/agents/tool" `
    -Method Post `
    -ContentType "application/json" `
    -Body $body


# ------------------------------------------------------------
# 4. Triage 및 Handoff Agent 테스트
# ------------------------------------------------------------

# 한 줄을 띄운 후 Triage/Handoff Agent 테스트 이름을 출력한다.
Write-Host "`nTriage/Handoff Agent"

# 사내 Kubernetes 배포에 관한 사용자 메시지를 JSON으로 변환한다.
$body = @{
    message = "이 컨테이너를 사내 Kubernetes에 배포하려면 무엇을 준비해야 하나?"
} | ConvertTo-Json

# triage Agent API를 호출한다.
#
# triage Agent는 요청 내용을 분석한다.
# 이 요청은 사내 환경에 관한 질문이므로 on_prem_specialist로
# handoff할 가능성이 높다.
Invoke-RestMethod `
    -Uri "http://localhost:8010/agents/triage" `
    -Method Post `
    -ContentType "application/json" `
    -Body $body