OpenAI Agents SDK와 Google ADK로 Agent 개발을 시작하는 메모 (Mac/Windows)
요약
OpenAI Agents SDK와 Google ADK를 활용한 AI 에이전트 개발 입문 가이드입니다. 에이전트의 개념 정의부터 로컬 환경(Mac/Windows) 구축, 그리고 향후 SRE 및 인프라 운영 자동화로의 확장 가능성을 다룹니다.
핵심 포인트
- OpenAI Agents SDK는 코드 중심의 OSS 지향 개발에 적합함
- Google ADK는 Gemini 및 Google Cloud 생태계 연계에 유리함
- 에이전트는 모델, 도구, 추론 과정을 결합한 애플리케이션임
- 초기 도입 시 읽기 중심 및 결과 확인이 가능한 태스크부터 시작 권장
최근 AI Agent 관련 정보를 추적하다 보면, OpenAI AgentKit, OpenAI Agents SDK, Google ADK, Agent Platform 등 비슷한 이름들이 한꺼번에 등장하여 조금 혼란스러웠습니다.
제 이해로는, OpenAI 측은 AgentKit이라는 큰 프레임워크가 있으며, 코드를 작성하여 Agent를 만든다면 OpenAI Agents SDK부터 시작하는 것이 이해하기 쉽습니다. 반면, Google Cloud나 Gemini를 중심으로 생각한다면 Google Agent Development Kit, 즉 ADK가 입구가 됩니다.
※ 본 기사는 2026년 5월 31일 시점의 공식 문서를 보며 정리하고 있습니다. Agent 관련 도구는 업데이트 속도가 상당히 빠르므로, 실제로 다룰 때는 공식 문서도 확인해 두시기 바랍니다.
이 기사에서는 먼저 Agent 개발의 기초 용어를 대략적으로 정리하고, 그 후 Mac과 Windows 양쪽 모두에서 OpenAI Agents SDK와 Google ADK를 구동하는 것까지 시도해 봅니다. 주축은 로컬 개발이지만, 마지막에는 Cloud Run, Agent Runtime on Agent Platform, GKE 등 배포할 때의 선택지도 메모해 두겠습니다.
이 기사는 Agent 개발 시리즈의 Part 1로서 작성되었습니다. 다음 회차부터는 SRE나 인프라 엔지니어의 업무를 소재로 하여, Runbook 조사 Agent, 인증서 갱신 체크 Agent, Kubernetes 장애 조사 Agent와 같은 작은 Agent를 만들어 볼 예정입니다.
Agent는 단순히 AI에게 질문만 하는 메커니즘이 아니라고 생각합니다.
대략적으로 파악하자면, Agent는 "모델에게 생각하게 하고, 필요에 따라 도구(Tool)를 사용하게 하며, 결과를 확인하면서 태스크를 진행하는 애플리케이션" 정도의 이해가 적절했습니다.
이것이 주목받는 이유는 개발 및 운영 현장에 있는 반복 작업과 궁합이 좋기 때문이라고 생각합니다.
- 로그를 보고, 흔히 발생하는 장애 패턴에 대입하기
- Runbook을 찾아, 절차를 요약하기
- Kubernetes 상태를 확인하여, 의심스러운 Pod나 Event를 가려내기
- 인증서 만료일이나 WAF/CDN/FW 설정 변경을 확인하기
- GitHub Issue나 Pull Request로부터 작업 계획 세우기
이것들은 매번 제로 베이스에서 생각하기보다, 정보를 수집하고, 판단하고, 정해진 형태로 보고하는 작업입니다. 이러한 작업에는 Agent가 투입되기 쉽다고 느꼈습니다.
물론 무엇이든 Agent로 만들면 좋은 것은 아닙니다. 처음에는 "읽기 중심", "실패해도 영향이 적음", "결과를 인간이 확인 가능"한 태스크부터 시작하는 것이 현실적이라고 느꼈습니다.
공식 문서와 몇 가지 샘플을 살펴보니, Agent 애플리케이션은 대체로 다음 부품들로 생각하면 정리하기 쉽다고 느꼈습니다.
| 부품 | 역할 |
|---|---|
| Model | 문장 이해, 추론, 도구 선택을 수행하는 핵심 |
| ... | |
| 처음 만든다면 구성은 더 작아도 괜찮습니다. |
저라면 우선 "1개의 Agent", "1개의 Tool", "1개의 입력", "1개의 출력 형식" 정도부터 시작하겠습니다. 그래야 무엇이 일어나고 있는지 추적하기 쉽습니다.
이번에는 입구로서 이 두 가지를 살펴봅니다.
| 선택지 | 적합한 케이스 |
|---|---|
| OpenAI Agents SDK | OSS 지향, 코드 퍼스트(Code-first), OpenAI 모델로 Agent를 만들고 싶을 때 |
| Google ADK | Gemini나 Google Cloud 연계를 고려하여 Agent를 만들고 싶을 때 |
OpenAI의 AgentKit은 Agent Builder, Connector Registry, ChatKit, Evals 등을 포함하는 Agent 개발·운용을 위한 제품군입니다. 로컬에서 코드를 작성하여 Agent를 만든다면, 우선 OpenAI Agents SDK를 접해보는 것이 이해하기 쉽다고 느꼈습니다.
Google ADK는 Agent를 코드로 정의하고, 로컬에서 실행·확인하며, 향후 Google Cloud나 Agent Platform 방면으로 확장하기 쉬운 개발 키트라는 이해입니다.
수중에서는 다음과 같은 환경을 상정하고 진행합니다.
| 항목 | 권장 |
|---|---|
| OS | macOS 또는 Windows 10/11 |
| ... | |
| API 키는 환경 변수로 취급합니다. 기사나 Git 리포지토리에는 작성하지 않는다는 전제로 진행합니다. |
Mac에서는 Homebrew를 사용한다면 다음과 같이 준비할 수 있습니다.
brew install git python node
python3 --version
node --version
...
작업용 디렉토리도 만들어 둡니다.
mkdir -p ~/dev/agent-playground
cd ~/dev/agent-playground
Windows에서는 PowerShell을 열고 winget으로 필요한 도구를 설치합니다.
winget install Git.Git
winget install Python.Python.3.12
winget install OpenJS.NodeJS.LTS
새로운 PowerShell을 다시 열어 확인합니다.
python --version
node --version
git --version
이쪽도 작업용 디렉토리를 만들어 둡니다.
mkdir $HOME\dev\agent-playground
cd $HOME\dev\agent-playground
Mac:
mkdir openai-agent-basic
cd openai-agent-basic
python3 -m venv .venv
...
Windows:
mkdir openai-agent-basic
cd openai-agent-basic
python -m venv .venv
...
PowerShell에서 가상 환경 (Virtual Environment) 활성화가 차단되는 경우에는 현재 사용자에게만 실행 정책 (Execution Policy)을 설정합니다.
Set-ExecutionPolicy -Scope CurrentUser RemoteSigned
pip install openai-agents
Windows에서도 가상 환경을 활성화한 PowerShell에서 동일한 명령어를 실행합니다.
pip install openai-agents
Mac:
export OPENAI_API_KEY="sk-..."
Windows:
$env:OPENAI_API_KEY="sk-..."
영구적으로 설정하려면 OS의 환경 변수 (Environment Variable) 설정이나 1Password CLI 등을 사용하는 것을 추천합니다. .env 파일에 저장하는 경우에도 잊지 말고 .gitignore에 넣어주세요.
main.py를 생성합니다.
from agents import Agent, Runner
agent = Agent(
name="sre_study_agent",
...
실행합니다.
python main.py
Windows:
python .\main.py
여기까지 하면 OpenAI Agents SDK 측의 최소 구성은 동작할 것입니다.
Mac:
cd ~/dev/agent-playground
mkdir google-adk-basic
cd google-adk-basic
...
Windows:
cd $HOME\dev\agent-playground
mkdir google-adk-basic
cd google-adk-basic
...
pip install google-adk
Windows:
pip install google-adk
Google AI Studio의 API 키를 사용하는 경우에는 먼저 현재 터미널에서 동작 확인용으로 환경 변수를 설정해 둡니다.
Mac:
export GOOGLE_API_KEY="..."
Windows:
$env:GOOGLE_API_KEY="..."
Google Cloud / Agent Platform을 사용하는 경우에는 프로젝트나 인증 (Authentication) 설정이 별도로 필요합니다. 처음에는 Google AI Studio의 API 키로 로컬 동작을 확인하고, 나중에 Google Cloud 연동으로 넘어가는 흐름이 편했습니다.
ADK에서는 adk create로 Agent 프로젝트의 템플릿을 만들 수 있습니다. 이 부분은 공식 Quickstart 흐름을 따릅니다.
Mac:
adk create sre_helper
Windows:
adk create sre_helper
생성 후 구성은 대략 다음과 같습니다.
sre_helper/
agent.py
.env
...
ADK Quickstart에서는 생성된 Agent 프로젝트의 .env 파일에 API 키를 작성합니다. 여기서는 sre_helper/.env에 설정해 보겠습니다.
Mac:
echo 'GOOGLE_API_KEY="YOUR_API_KEY"' > sre_helper/.env
Windows PowerShell:
echo 'GOOGLE_API_KEY="YOUR_API_KEY"' > sre_helper/.env
다음으로, sre_helper/agent.py를 편집합니다. 우선은 도구(Tool)가 없는, 정말 작은 Agent로 만들어 두겠습니다.
from google.adk.agents.llm_agent import Agent
root_agent = Agent(
name="sre_helper",
...
ADK Web UI를 사용하는 경우, Agent 폴더의 상위 디렉토리에서 실행합니다.
adk web --port 8000
Windows:
adk web --port 8000
브라우저에 표시되는 로컬 URL을 열고, sre_helper Agent를 선택하여 질문합니다.
ADK Web은 개발 및 디버깅용입니다. 프로덕션(Production) 공개용 UI가 아니므로, 팀이나 CI에서 이용할 경우에는 후술할 Cloud Run이나 Agent Runtime 등으로 API로서 배포하는 구성을 고려해야 합니다.
CLI로 실행할 경우:
adk run sre_helper
Windows:
adk run sre_helper
예를 들어 다음과 같이 질문해 봅니다.
Kubernetes 운영에서 SLO를 결정할 때, 가장 먼저 확인해야 할 메트릭(Metrics)을 소개해 주세요.
로컬에서 Agent를 만든 후, 누군가에게 사용하게 하거나, CI에서 호출하거나, 업무 흐름(Workflow)에 포함시키는 단계가 되면 배포처를 고민해야 합니다.
ADK 공식 문서를 보면 주요 배포처로 Agent Runtime on Agent Platform, Cloud Run, GKE, 그리고 기타 컨테이너 실행 환경이 소개되어 있습니다.
| 선택지 | 적합한 케이스 | 주의사항 |
|---|---|---|
| 로컬 실행 | 개인 개발, 검증, 프롬프트 조정 | 다른 멤버나 CI에서 사용하기 어려움 |
| ... |
Python ADK Agent는 adk deploy cloud_run 명령으로 Cloud Run에 배포할 수 있습니다. 공식 문서에서는 Python의 경우 이 명령을 안내하고 있습니다.
export GOOGLE_CLOUD_PROJECT="your-gcp-project-id"
export GOOGLE_CLOUD_LOCATION="us-central1"
export AGENT_PATH="./sre_helper"
...
Cloud Run으로 공개할 경우, 처음에는 인증(Authentication)을 필수로 설정합니다. CI나 사내 도구에서 호출할 때도 공개 URL을 누구나 호출할 수 있는 상태로 두기보다는, Workload Identity Federation이나 서비스 계정(Service Account)을 사용하여 인증을 거쳐 호출하는 구성으로 만들고 싶습니다.
또한, API 키는 환경 변수에 직접 작성하지 않고 Secret Manager를 통해 전달하는 구성으로 합니다.
예를 들어 Pull Request의 차이점(Diff)을 Agent에게 전달하여 SRE 관점, 보안 관점, 운영 관점의 리뷰 코멘트를 생성하게 하고 싶다면, 다음과 같은 구성이 다루기 쉽습니다.
GitHub Pull Request
-> GitHub Actions
-> Cloud Run 위의 ADK Agent API
...
이렇게 구성하면 GitHub Actions 측에 Agent의 의존성이나 API 키를 대량으로 보유하지 않고, Agent의 실행 환경을 Cloud Run 측에 격리할 수 있습니다.
초기 설계에서는 Agent에게 리포지토리 쓰기 권한을 주지 않고, 리뷰 결과만 반환하도록 하고 싶습니다. PR 코멘트를 작성하는 경우에도 GitHub Actions 측에서 내용을 확인한 후 게시하는 형태로 만들면 책임(Responsibility)이 분리됩니다.
Agent Runtime on Agent Platform은 ADK 등으로 만든 Agent를 Google Cloud 상에서 관리하고 스케일링(Scaling)하고 싶을 때의 선택지입니다.
Cloud Run보다 Agent 운용에 특화된 매니지드(Managed) 선택지이므로, 세션, 운용, Google Cloud 연동을 중시한다면 이쪽을 검토합니다. 반면, 단순히 HTTP API로서 CI에서 호출하고 싶을 뿐이라면 우선 Cloud Run으로도 충분한 경우가 많습니다.
이미 Kubernetes 기반이 있고, NetworkPolicy, Service Mesh, 독자적인 모니터링, 폐쇄망 연결(Closed Network Connection) 등을 세밀하게 제어하고 싶다면 GKE가 후보가 됩니다.
ADK 공식 문서에서는 GKE 배포도 안내하고 있습니다. 다만, 처음에 선택하기에는 조금 무거운 편입니다. 저라면 처음에는 로컬, 그다음은 Cloud Run, 본격적인 운용이 필요해지면 GKE 순으로 생각하겠습니다.
공개 전에 조금 엄격하게 재검토한 포인트도 남겨둡니다.
| 신경 쓰인 점 | 수정한 내용 |
|---|---|
| ADK의 Python 요구사항이 모호함 | 공식 Quickstart에 맞춰 Python 3.10 이상, 본문에서는 3.11 이상 권장으로 수정 |
| ADK 작성 절차가 독자적인 방식처럼 보임 | adk create, root_agent, .env, adk run, adk web의 공식 절차에 맞춤 |
adk web이 운영 환경에서 사용 가능한 것처럼 보임 | 개발·디버깅용이며, 운영 환경에서는 Cloud Run 등을 사용한다는 내용 추가 |
| 로컬 개발 이후의 경로가 없음 | Cloud Run, Agent Runtime on Agent Platform, GKE, 기타 컨테이너 기반의 비교를 추가 |
| CI 리뷰 Agent의 운용 모습이 없음 | GitHub Actions에서 Cloud Run의 Agent API를 호출하는 구성 추가 |
| 비밀 정보(Secret) 취급이 미흡함 | Cloud Run에서는 Secret Manager 사용을 권장한다는 설명 추가 |
첫 번째 Agent는 작게 만드는 것이 중요합니다. SRE나 인프라 엔지니어라면 다음과 같은 테마가 적합합니다.
| 테마 | 첫 입력 | 첫 출력 |
|---|---|---|
| Runbook 검색 Agent | 장애 내용, 서비스명 | 관련 Runbook 후보와 확인 절차 |
| Kubernetes 조사 Agent | kubectl get events 결과 | 의심스러운 Event와 다음에 실행할 명령어 |
| 인증서 만료 체크 Agent | 인증서 목록 CSV | 만료가 임박한 인증서와 갱신 우선순위 |
| WAF/CDN 변경 리뷰 Agent | 변경 요청문 | 리스크, 확인 항목, 승인 전 체크 사항 |
| SLO 설계 보조 Agent | 서비스 개요 | 후보 SLI, 측정 방법, 주의사항 |
처음부터 운영 환경을 조작하게 할 필요는 없다고 생각합니다. 우선은 읽기 전용(Read-only) 정보를 전달하여, 판단과 요약만 맡기는 것부터 시작하고 싶습니다.
Agent 개발에서 무서운 것은 의도하지 않은 조작입니다.
처음에는 CLI나 API를 사용하는 Tool도 읽기 전용으로 만들고 싶습니다. 업데이트 계열의 조작을 넣는 경우에는 인간의 승인 단계(Human-in-the-loop)를 거칠 생각입니다.
출력이 매번 제각각이면 리뷰도 자동화도 어려워집니다.
예를 들어, 장애 조사 Agent라면 다음과 같은 형식으로 고정해 두면 다루기 쉽습니다.
## 가능성이 높은 원인
## 근거
## 다음에 확인할 명령어
...
Agent는 "작동했다"에서 끝내버리면 금방 품질을 파악하기 어려워집니다.
처음부터 입력, 기대하는 출력, 실제 출력, 평가 메모를 남겨두면 개선하기 쉽습니다. OpenAI AgentKit의 Evals나 ADK 주변의 평가 기능으로 연결하기 위한 전 단계로서도 유용합니다.
가상 환경이 활성화되지 않았을 가능성이 있습니다.
Mac:
source .venv/bin/activate
pip list
Windows:
.\.venv\Scripts\Activate.ps1
pip list
동일한 터미널에서 환경 변수를 설정했는지 확인합니다.
Mac:
echo $OPENAI_API_KEY
echo $GOOGLE_API_KEY
Windows:
echo $env:OPENAI_API_KEY
echo $env:GOOGLE_API_KEY
PowerShell의 실행 정책(Execution Policy)에 의해 차단되었을 가능성이 있습니다.
Set-ExecutionPolicy -Scope CurrentUser RemoteSigned
회사 PC인 경우, 사내 정책을 따르시기 바랍니다.
이번에는 Agent 개발의 기초 용어와 OpenAI Agents SDK / Google ADK의 환경 구축을 정리해 보았습니다.
제 개인적으로는 우선 다음의 3가지로 이해했습니다.
- Agent는 모델 (Model), 지시 (Instruction), 도구 (Tool), 루프 (Loop), 안전장치 (Safeguard), 관측성 (Observability)으로 생각하면 정리하기 쉽다
- OpenAI 측은 AgentKit 전체를 의식하면서, 코드 퍼스트 (Code-first) 방식이라면 Agents SDK부터 시작하는 것이 이해하기 쉽다
- Google Cloud 측은 ADK로 로컬 실행을 하고, 나중에 Cloud Run / Agent Runtime / GKE로 확장할 수 있다
다음에는 SRE나 인프라 엔지니어를 대상으로, Runbook 조사 Agent 또는 Kubernetes 장애 조사 Agent의 최소 구성을 만들어 보고 싶습니다.
AI 자동 생성 콘텐츠
본 콘텐츠는 Qiita AI의 원문을 AI가 자동으로 요약·번역·분석한 것입니다. 원 저작권은 원저작자에게 있으며, 정확한 내용은 반드시 원문을 확인해 주세요.
원문 바로가기