서진호

3 분 소요

이 블로그는 윈도우11 운영체제 환경에서 Powershell을 포함한 Visual Studio Code를 이용해 OpenAI Agents SDK 앱을 개발하고, 최종 결과물을 리눅스 도커 이미지(Linux Docker image)로 빌드하여 Windows용 Docker Desktop, Public Cloud, On-Premises Linux/Kubernetes에서 재사용하는 전체 흐름을 익히는 핸즈온 워크삽이다.

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

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

  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로 이동하는 원리를 설명한다.

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
파일명 역할
app/__init__.py app 디렉터리를 Python 패키지로 인식시키는 초기화 파일
app/agents_app.py OpenAI Agents SDK를 이용한 에이전트 생성, 실행 및 응답 처리 로직
app/main.py FastAPI 애플리케이션 진입점과 API 엔드포인트 정의
scripts/setup.ps1 가상환경 생성과 Python 패키지 설치 등 초기 개발환경 구성
scripts/run-native.ps1 애플리케이션을 로컬 Python 환경에서 직접 실행
scripts/build-image.ps1 Dockerfile을 기반으로 Docker 이미지 빌드
scripts/run-container.ps1 빌드된 이미지를 사용하여 Docker 컨테이너 실행
scripts/test-api.ps1 실행 중인 애플리케이션의 API 요청 및 응답 테스트
scripts/verify-image.ps1 Docker 이미지가 정상적으로 생성되고 실행 가능한지 검증
.dockerignore Docker 빌드 컨텍스트에서 제외할 파일과 디렉터리 지정
.env.example 필요한 환경변수 형식을 보여주는 예제 파일. 실제 비밀값은 포함하지 않음
.gitignore Git이 추적하지 않을 환경설정, 가상환경, 캐시, 보안 파일 등을 지정
docker-compose.yml 애플리케이션 컨테이너의 실행 환경, 포트 및 환경변수 구성
Dockerfile 애플리케이션 Docker 이미지의 빌드 단계와 실행 명령 정의
requirements.txt 프로젝트 실행에 필요한 Python 패키지와 버전 정의
README.md 프로젝트 개요, 설치 방법, 실행 절차 및 API 사용법 안내

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인지 확인한다. 확인하는 방법은 아래의 그림과 같다.

실습 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
단계 이름 설명
User Input 사용자가 질문이나 작업 요청을 입력함. 이 입력이 에이전트 실행의 시작점
Agent 지침, 모델, 도구, 핸드오프 등의 설정을 바탕으로 입력을 해석하고 수행할 작업을 결정함
Runner 에이전트의 실행 루프를 관리함. 모델 호출, 도구 실행, 핸드오프 처리 등을 반복하며 최종 결과를 생성함
Model 사용자 입력과 에이전트 지침을 분석해 응답하거나 다음에 실행할 도구 또는 핸드오프를 결정함
Tool 함수 호출, 데이터 조회, 계산 등 모델만으로 처리하기 어려운 외부 작업을 수행함. 실행 결과는 다시 에이전트에 전달됨
Handoff 현재 에이전트가 다른 전문 에이전트에 작업 제어권을 넘김. 복수 에이전트 협업에 사용됨.
RunResult 전체 에이전트 실행 과정에서 생성된 최종 출력과 관련 실행 정보를 담는 결과 객체임
RunResult.final_output 실행이 완료된 후 사용자에게 반환되는 최종 응답. 일반 텍스트뿐 아니라 지정된 구조화 데이터일 수도 있음

댓글남기기