OpenAI Agents SDK로 첫 번째 개발자 에이전트 구축하기

개발자 에이전트 (Developer Agent)는 코드를 작성하는 것부터 시작해서는 안 됩니다. 이상하게 들릴 수도 있지만, 실제 엔지니어링 작업을 위한 에이전트를 구축한다면 첫 번째 버전은 신중해야 합니다. 에이전트는 이슈를 읽고, 코드베이스를 조사하며, 계획을 세우고, 테스트를 제안하고, 풀 리퀘스트 (Pull Request) 요약을 생성해야 합니다. 파일을 수정하는 것은 그 이후의 일이어야 합니다. 그것이 신뢰를 구축하는 방법입니다.

이 글에서는 OpenAI Agents SDK를 사용하여 작은 개발자 에이전트를 구축해 보겠습니다. 목표는 완전히 자율적인 엔지니어를 만드는 것이 아닙니다. 도구 (Tools), 안전 규칙 (Safety Rules), 그리고 승인 게이트 (Approval Gates)를 갖춘 유용한 워크플로 실행기 (Workflow Executor)를 구축하는 것이 목표입니다.

에이전트는 GitHub 이슈를 읽고, 로컬 코드베이스를 검색하며, 관련 파일을 조사하고, 구현 계획을 세우고, 테스트를 실행하며, 풀 리퀘스트 요약을 생성하고, 위험한 작업을 수행하기 전에 멈출 수 있습니다.

OpenAI Agents SDK가 Python 패키지를 제공하기 때문에 예제는 Python을 사용합니다. 코드는 학습용 템플릿으로 유지하며, 바로 실무에 투입 가능한 프로덕션용 시스템으로 간주하지 마십시오.

우리가 구축하는 것

워크플로는 다음과 같습니다:

GitHub Issue
    |
Read issue details
...

이는 의도적으로 보수적인 설계입니다. 첫 번째 개발자 에이전트는 자문 역할을 해야 합니다. 코드를 건드리기 전에 사용자가 이해하고 계획을 세울 수 있도록 도와야 합니다.

SDK 설치

새로운 Python 프로젝트를 생성합니다:

mkdir developer-agent-demo
cd developer-agent-demo

...

API 키를 설정합니다:

export OPENAI_API_KEY="your-api-key"

간단한 프로젝트 구조:

developer-agent-demo/
  agent.py
  tools.py
...

튜토리얼에서 target-repo/는 에이전트가 조사할 저장소 (Repository)입니다.

도구 경계 정의하기

도구 (Tools)는 에이전트의 가장 중요한 부분입니다. 모델에게 무제한적인 셸 (Shell) 액세스 권한을 주어서는 안 됩니다. 대신 특정 도구들을 제공해야 합니다.

tools.py를 생성합니다:

from pathlib import Path
import subprocess
from typing import List
...

이 파일은 핵심적인 보안 아이디어를 보여줍니다:

에이전트는 당신의 도구(tools)가 허용하는 작업만 수행할 수 있습니다.

에이전트는 검색, 읽기, 그리고 승인된 테스트 명령어를 실행할 수 있습니다. 하지만 파일을 삭제하거나, 커밋을 푸시(push)하거나, 배포(deploy)할 수는 없습니다.

작은 GitHub Issue Reader 만들기

실제 GitHub 연동을 위해서는 GitHub REST API를 호출하거나 SDK를 사용해야 합니다. 이 튜토리얼에서는 단순하게 유지하겠습니다.

github_client.py를 생성합니다:

from dataclasses import dataclass

@dataclass
...

이를 통해 에이전트에게 현실적인 이슈(issue)를 제공할 수 있습니다.

에이전트 구축하기

이제 agent.py를 생성합니다. 정확한 API 형태는 시간이 지남에 따라 변할 수 있으므로, 이를 실무적인 학습 예제로 취급하십시오. 중요한 개념들은 안정적입니다: 지침(instructions) 정의, 도구(tools) 노출, 에이전트 실행, 그리고 결과 검사입니다.

from agents import Agent, Runner, function_tool

from github_client import read_issue
...

이 에이전트는 의도적으로 파일 쓰기가 허용되지 않도록 설정되었습니다. 그것이 올바른 첫 번째 단계입니다.

에이전트에게 더 나은 작업 부여하기

에이전트에게 전달하는 프롬프트(prompt)가 중요합니다.

취약한 작업:

#123 이슈를 수정하세요.

더 나은 작업:

GitHub #123 이슈를 분석하세요.

단계:
...

이렇게 하면 워크플로(workflow)를 안전하게 유지할 수 있습니다.

에이전트 출력 예시

좋은 출력은 다음과 같을 수 있습니다:

## 이슈 요약

#123 이슈는 중복된 인보이스(invoice) 리마인더 이메일 문제를 보고합니다. 설명에 따르면
...

이는 코드가 생성되기 전에 매우 유용합니다.

승인 게이트(Approval Gates) 추가하기

이제 간단한 승인 게이트를 정의해 보겠습니다. safety.py를 생성합니다:

from dataclasses import dataclass

@dataclass
...

나중에 파일 쓰기 도구를 추가한다면, 다음과 같이 감싸주세요(wrap):

from agents import function_tool
from pathlib import Path

...

이것이 유용한 자동화와 위험한 자동화 사이의 경계선입니다. 에이전트(Agent)는 쓰기(write) 작업을 제안할 수 있습니다. 그 작업이 허용될지 여부는 여러분의 소프트웨어가 결정합니다.

위험 기반 규칙 추가하기 (Add Risk-Based Rules)

어떤 파일들은 항상 승인을 필요로 해야 합니다. 예를 들어:

HIGH_RISK_PATTERNS = [
    "database/migrations/",
    "app/Auth/",
...

그런 다음 쓰기 작업 전에 이를 사용합니다:

@function_tool
def write_repo_file(path: str, content: str, reason: str) -> str:
    risk_level = classify_file_risk(path)
...

이는 간단하지만 매우 실용적입니다. 나중에 이를 정책 규칙(policy rules)으로 발전시킬 수 있습니다.

풀 리퀘스트 요약 생성하기 (Generate A Pull Request Summary)

개발자 에이전트(Developer agent)가 유용하기 위해 반드시 직접 PR(Pull Request)을 생성할 필요는 없습니다. 요약본을 생성할 수도 있습니다.

프롬프트(Prompt):

구현 계획과 테스트 결과에 기반하여, 풀 리퀘스트(pull request) 요약을 생성하세요.

포함할 내용:
...

요약 예시:

## 문제 (Problem)

인보이스 리마인더 이메일이 예약된 리마인더에 의해 발송될 수 있으며
...

이는 리뷰어의 시간을 절약해 줍니다. 또한 에이전트가 동작의 영향(behavior impact)을 설명하도록 강제합니다.

안전하게 테스트 실행하기 (Running Tests Safely)

앞서 살펴본 run_tests 도구는 지정된 명령만 허용합니다. 이는 셸(shell)만큼 유연하지는 않지만, 더 안전합니다.

다음과 같이 확장할 수 있습니다:

ALLOWED_TEST_TARGETS = {
    "billing": ["vendor/bin/phpunit", "tests/Feature/Billing"],
    "unit": ["vendor/bin/phpunit", "tests/Unit"],
...

그런 다음 run_test_target을 도구로 노출합니다. 모델은 "billing" 또는 "unit"을 선택할 수 있지만, 다음과 같은 임의의 명령을 실행할 수는 없습니다:

rm -rf /

그것이 바로 핵심입니다.

트레이싱 및 로그 추가하기 (Add Tracing And Logs)

개발자 에이전트는 감사(auditable) 가능해야 합니다. 최소한 이슈 번호, 호출된 도구, 읽은 파일, 실행된 테스트, 요청된 승인, 최종 출력 및 에러를 로그(log)로 남겨야 합니다.

간단한 예시:

import json
from datetime import datetime

...

도구 내부에서 이를 사용하세요:

def search_codebase(query: str, max_results: int = 20) -> list[str]:
    log_agent_event("search_codebase", {"query": query})

...

로그(Logs)는 에이전트의 동작을 미스터리한 영역에서 검사 가능한 워크플로 (workflow)로 바꿔줍니다.

버전 1에서 피해야 할 사항

첫 번째 개발자 에이전트에게 광범위한 셸 (shell) 액세스 권한을 주지 마세요. 승인 없이 브랜치 (branch)를 푸시하게 하지 마세요. 풀 리퀘스트 (pull request)를 머지 (merge)하게 하지 마세요. 사람의 체크포인트 (checkpoint) 없이 마이그레이션 (migration), 인증 (auth), 결제 (payment) 또는 보안 (security) 파일을 편집하게 하지 마세요. 프로덕션 (production) 비밀 값에 접근하게 하지 마세요. 자신의 작업이 안전한지 스스로 결정하게 하지 마세요.

자문 (advisory) 동작부터 시작하세요:

읽기 -> 분석 -> 계획 -> 테스트 제안 -> 요약

그다음 천천히 추가하세요:

저위험 파일 편집 -> 테스트 실행 -> 초안 PR 생성

그다음에는 아마도:

사람의 승인을 거쳐 PR 오픈

이러한 단계적 진행이 훨씬 더 안전합니다.

더 나은 프로덕션 아키텍처 (Production Architecture)

실제 내부용 개발자 에이전트를 위해서는 결국 다음과 같은 구조를 갖게 될 수도 있습니다:

프론트엔드 UI (Frontend UI)
  |
에이전트 서비스 (Agent service)
...

또한 목적에 따라 책임을 나눌 수도 있습니다: 이슈 분류 (issue triage) 에이전트, 코드베이스 검색 (codebase search) 에이전트, 테스트 계획 (test planning) 에이전트, PR 요약 (PR summary) 에이전트, 그리고 문서 업데이트 (documentation update) 에이전트입니다.

거대한 단일 에이전트는 제어하기가 더 어렵습니다. 명확한 도구 (tools)를 가진 작은 에이전트들이 신뢰하기 더 쉽습니다.

마치며

여러분의 첫 번째 개발자 에이전트가 자율적 (autonomous)일 필요는 없습니다. 유용해야 합니다. 유용한 첫 번째 버전은 이슈를 읽고, 코드를 검사하고, 예상되는 동작을 설명하고, 테스트를 제안하며, 안전한 구현 계획을 세우고, 좋은 PR 요약을 작성할 수 있습니다. 그것만으로도 실제 시간을 절약할 수 있습니다.

가장 중요한 원칙은 간단합니다:

에이전트에게 도구를 주되, 경계 (boundaries)는 유지하라.

에이전트는 행동할 수 있을 때 강력해집니다. 에이전트는 여러분의 소프트웨어가 그들의 행동 방식을 제어할 때 안전해집니다. 작게 시작하세요. 모든 것을 로그로 남기세요. 승인 게이트 (approval gates)를 추가하세요. 에이전트를 마법 같은 개발자가 아니라 워크플로 실행기 (workflow executor)로 취급하세요.

그것이 바로 여러분의 팀이 실제로 사용할 수 있는 무언가를 구축하는 방법입니다.

원래 게시된 곳: nazarboyko.com.