2 - Python 환경에서 Agents SDK 설치 및 기본 설정하기

 

– FastAPI와 함께 쓰기 위한 준비 단계

안녕하세요, OpenAI Agents SDK 실전 가이드 두 번째 편입니다.

지난 1편에서는 Agents SDK가 무엇이고, 왜 중요한지를 살펴보았습니다. 이제 본격적으로 Python 환경에서 SDK를 설치하고, 기본적인 실행까지 직접 해보는 실습에 들어가겠습니다.
이 글을 끝까지 따라 하시면 Agents SDK 기반 프로젝트의 초기 세팅을 완성하실 수 있습니다.

---

🧰 1. 개발 환경 준비하기

✅ 1-1. Python 가상환경 만들기

먼저 새로운 Python 프로젝트 디렉토리를 만들고, 가상환경을 구성합니다:

mkdir agents-practice
cd agents-practice
python -m venv venv
source venv/bin/activate  # Windows는 venv\Scripts\activate

✅ 1-2. 필수 패키지 설치

OpenAI Agents SDK는 PyPI를 통해 설치할 수 있습니다. 다음 명령어를 실행하세요:

pip install openai-agents

추가로 FastAPI와 Uvicorn도 함께 설치하겠습니다:

pip install fastapi uvicorn

🚧 참고: Python 3.9 이상을 권장합니다.

---

🔐 2. OpenAI API Key 설정

Agents SDK는 내부적으로 GPT 모델을 호출하기 때문에, OpenAI API 키가 필요합니다.
아직 키가 없다면 OpenAI 계정에서 새 키를 발급받으세요.

✅ 2-1. 환경 변수로 설정

가장 간단한 방법은 터미널에서 다음과 같이 환경 변수를 설정하는 것입니다:

Linux / macOS

export OPENAI_API_KEY="sk-xxxx"

Windows (CMD)

set OPENAI_API_KEY=sk-xxxx

Windows (PowerShell)

$env:OPENAI_API_KEY="sk-xxxx"

✅ 2-2. .env 파일을 사용하는 방법 (선택)

.env 파일을 만들어 API 키를 저장하고, Python에서 불러올 수도 있습니다.

.env

OPENAI_API_KEY=sk-xxxx

Python 코드에서는 다음과 같이 불러올 수 있습니다:

from dotenv import load_dotenv
load_dotenv()

이 방법은 프로젝트 배포 시 보안에 유리하며, 여러 환경에서 공통적으로 사용할 수 있어 권장됩니다.

---

🧪 3. 첫 번째 에이전트 실행해보기

환경 설정이 완료되었다면, 실제로 Agents SDK를 사용해 간단한 에이전트를 실행해보겠습니다.

# hello_agent.py
from agents import Agent, Runner

agent = Agent(
    name="간단한도우미",
    instructions="당신은 친절하고 도움이 되는 AI 비서입니다."
)

result = Runner.run_sync(agent, "오늘 하루 어떻게 보내면 좋을까요?")
print(result.final_output)

이 파일을 실행하면, GPT 기반 에이전트가 친절하게 하루 계획을 제안해줄 것입니다:

python hello_agent.py

출력 예시:

오늘은 아침에 산책으로 상쾌하게 시작해보세요. 중요한 일은 오전에 집중하고, 오후엔 가벼운 독서나 취미 시간을 가지면 좋겠습니다!

---

🌐 4. FastAPI와의 기본 연동

FastAPI를 통해 API 서버 형태로 에이전트를 노출할 수도 있습니다.

# main.py
from fastapi import FastAPI
from pydantic import BaseModel
from agents import Agent, Runner

app = FastAPI()

agent = Agent(
    name="FastAPI Agent",
    instructions="당신은 사용자의 요청에 성실히 응답하는 도우미입니다."
)

class Query(BaseModel):
    question: str

@app.post("/ask")
async def ask(query: Query):
    result = await Runner.run(agent, input=query.question)
    return {"answer": result.final_output}

실행:

uvicorn main:app --reload

이제 http://localhost:8000/docs 에 접속하면 Swagger UI로 테스트할 수 있습니다.

예:
요청 JSON

{
  "question": "에이전트를 API로 어떻게 사용할 수 있나요?"
}

응답:

{
  "answer": "Agents SDK를 통해 FastAPI API 서버에서 쉽게 에이전트를 활용할 수 있습니다."
}

---

🧭 5. 프로젝트 구조 추천

초기 개발 시에는 다음과 같은 구조로 프로젝트를 구성하는 것을 추천드립니다:

agents-practice/
├── agents/
│   └── tools.py         # 도구 함수들
│   └── agents.py        # 에이전트 정의
├── api/
│   └── main.py          # FastAPI 엔드포인트
├── .env
├── requirements.txt
└── README.md

• 유지보수와 확장성을 고려한 도메인 분리
• 도구와 에이전트 로직을 분리해 재사용성 향상
• .env를 통해 키 관리

---

✅ 마무리하며

이번 글에서는 OpenAI Agents SDK를 Python에서 설치하고, 간단한 에이전트를 실행하는 방법, 그리고 FastAPI와 연동하는 초기 설정까지 모두 정리해보았습니다.

이제 개발 환경은 준비되었고, 다음 글부터는 Agents SDK의 핵심 개념들을 심도 있게 다룰 예정입니다.

다음 글: 3 - Agents SDK의 핵심 개념 완전 정복 – Agent, Tool, Function Calling, Guardrail