최근 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 애플리케이션은 대체로 다음 부품들로 생각하면 정리하기 쉽다고 느꼈습니다.

저라면 우선 "1개의 Agent", "1개의 Tool", "1개의 입력", "1개의 출력 형식" 정도부터 시작하겠습니다. 그래야 무엇이 일어나고 있는지 추적하기 쉽습니다.

이번에는 입구로서 이 두 가지를 살펴봅니다.

OpenAI의 AgentKit은 Agent Builder, Connector Registry, ChatKit, Evals 등을 포함하는 Agent 개발·운용을 위한 제품군입니다. 로컬에서 코드를 작성하여 Agent를 만든다면, 우선 OpenAI Agents SDK를 접해보는 것이 이해하기 쉽다고 느꼈습니다.

Google ADK는 Agent를 코드로 정의하고, 로컬에서 실행·확인하며, 향후 Google Cloud나 Agent Platform 방면으로 확장하기 쉬운 개발 키트라는 이해입니다.

수중에서는 다음과 같은 환경을 상정하고 진행합니다.

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, 그리고 기타 컨테이너 실행 환경이 소개되어 있습니다.

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 순으로 생각하겠습니다.

공개 전에 조금 엄격하게 재검토한 포인트도 남겨둡니다.

첫 번째 Agent는 작게 만드는 것이 중요합니다. SRE나 인프라 엔지니어라면 다음과 같은 테마가 적합합니다.

처음부터 운영 환경을 조작하게 할 필요는 없다고 생각합니다. 우선은 읽기 전용(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의 최소 구성을 만들어 보고 싶습니다.