에이전트라는 말이 너무 커져서 뭘 만들어야 하는지 감이 안 올 때가 많다. 실체는 단순하다. 모델이 "이 툴을 이 인자로 불러 달라"고 요청하면, 내 코드가 그 함수를 실행하고 결과를 다시 모델에 돌려주는 루프다. 이 글에서는 오픈AI Responses API의 툴 호출로 디스크 용량과 현재 시각을 조회하는 에이전트를 파이썬으로 끝까지 만든다.
프레임워크는 쓰지 않는다. SDK 함수 두 개와 while 루프만 있으면 동작하고, 그 구조를 한 번 손으로 짜 두면 나중에 어떤 도구를 붙이든 같은 자리에 코드를 끼워 넣으면 된다.

30초 요약
| 항목 | 내용 |
|---|---|
| 에이전트의 실체 | 모델의 툴 호출 요청 → 내 코드 실행 → 결과 반환을 반복하는 루프 |
| 준비물 | 파이썬 3.10 이상, pip install openai, OPENAI_API_KEY 환경변수 |
| 툴 정의 | JSON 스키마 + strict: True (additionalProperties: False, 모든 필드 required) |
| 루프 순서 | 요청 → function_call 수신 → 실행 → function_call_output(같은 call_id) 전송 → 최종 답 |
| 인자 처리 | call.arguments는 dict가 아니라 JSON 문자열이라 json.loads가 필요하다 |
| 병렬 호출 | 한 턴에 여러 툴이 올 수 있으니 for로 전부 처리한다 |
| 툴 개수 | 한 턴에 20개 미만 권장. 툴 정의도 입력 토큰으로 과금된다 |
| 근거 문서 | Function calling · openai-python |
목차
- AI 에이전트 만들기 전에 — 챗봇과 갈라지는 지점
- 준비물 — 파이썬 3.10과 API 키
- 툴 정의 — 모델에게 주는 계약서
- 에이전트 루프 — 70줄 전체 코드
- 실행해 보기 — 실제 터미널 출력
- 툴 늘리기 — 병렬 호출과 tool_choice
- 에이전트가 자주 틀리는 곳 — 루프·인자·권한
- 내가 막혔던 곳
AI 에이전트 만들기 전에 — 챗봇과 갈라지는 지점
챗봇은 한 번 묻고 한 번 답한다. 에이전트는 답을 만들기 전에 자기 손을 한 번 더 쓴다. "내 맥 디스크 얼마나 남았어?"라는 질문에 챗봇은 "확인할 수 없습니다"라고 답하지만, 에이전트는 디스크를 읽는 함수를 호출해서 실제 숫자를 가져온다.
공식 문서가 정리한 툴 호출 흐름은 다섯 단계다. 툴 목록과 함께 요청을 보내고, 모델에게서 툴 호출을 받고, 내 코드가 그 인자로 함수를 실행하고, 결과를 다시 보내고, 최종 답이나 다음 툴 호출을 받는다(Function calling — The tool calling flow). 이 다섯 단계를 감싸는 게 while 루프 하나다.
용어부터 정리하고 가면 편하다. 개념 편은 AI 에이전트란에 따로 적어 뒀고, 여기서는 만드는 쪽만 다룬다.
준비물 — 파이썬 3.10과 API 키
python3 -V # Python 3.10 이상이어야 한다
pip install openai
export OPENAI_API_KEY="sk-..."
openai 파이썬 SDK는 3.10 이상을 요구한다(openai-python README). SDK는 OPENAI_API_KEY 환경변수를 자동으로 읽으므로 코드에 키를 쓰지 않아도 된다.
SDK의 주력 API는 Responses API이고, 예전 Chat Completions도 계속 지원된다. 툴 호출 예제는 대부분 Responses 기준으로 바뀌었으니, 검색해서 나온 옛 코드와 함수 이름이 다르면 client.responses.create 쪽을 보면 된다. API 키 발급과 첫 호출은 OpenAI API 사용법에 정리해 뒀다.
툴 정의 — 모델에게 주는 계약서
툴은 "이런 이름의 함수가 있고, 인자는 이런 타입이다"를 JSON 스키마로 알려 주는 것이다. 모델은 이 스키마를 보고 인자를 채운다. 스키마가 엉성하면 엉뚱한 인자가 온다.
import datetime
import json
import shutil
from zoneinfo import ZoneInfo
from openai import OpenAI
client = OpenAI()
MODEL = "gpt-6.2-astra"
TOOLS = [
{
"type": "function",
"name": "get_disk_usage",
"strict": True,
"description": "지정한 경로가 올라가 있는 디스크의 전체/사용/여유 용량을 GB와 퍼센트로 돌려준다. "
"사용자가 '디스크', '저장 공간', '용량'을 물으면 이 함수를 쓴다.",
"parameters": {
"type": "object",
"properties": {
"path": {"type": "string", "description": "확인할 경로. 기본값은 /"},
},
"required": ["path"],
"additionalProperties": False,
},
},
{
"type": "function",
"name": "get_current_time",
"strict": True,
"description": "지정한 타임존의 현재 시각을 ISO 8601 문자열로 돌려준다.",
"parameters": {
"type": "object",
"properties": {
"tz": {"type": "string", "description": "IANA 타임존 이름. 예: Asia/Seoul"},
},
"required": ["tz"],
"additionalProperties": False,
},
},
]
strict: True를 켜면 모델이 스키마를 어기는 호출을 하지 못한다. 대신 조건이 붙는다. 모든 객체에 additionalProperties: False를 넣고, properties의 모든 필드를 required에 넣어야 한다. 선택 인자를 만들고 싶으면 required에서 빼는 게 아니라 타입에 null을 허용한다(Strict mode). 나는 처음에 "required": []로 두고 선택 인자를 만들려다 요청이 거부됐다.
설명 문구도 성능에 영향을 준다. 문서는 함수 이름과 인자 설명을 구체적으로 쓰고, 언제 쓰고 언제 쓰지 말지를 시스템 프롬프트에 적으라고 권한다. 또 처음에 노출하는 툴은 20개 미만으로 유지하라고 안내한다. 툴 정의는 시스템 메시지에 주입되어 컨텍스트를 차지하고 입력 토큰으로 과금되기 때문이다(Token usage).
에이전트 루프 — 70줄 전체 코드
아래가 이 글의 전부다. 스키마를 뺀 실행 부분만 보면 40줄이 안 된다.
def get_disk_usage(path="/"):
u = shutil.disk_usage(path)
gb = 1024 ** 3
return {
"path": path,
"total_gb": round(u.total / gb, 1),
"free_gb": round(u.free / gb, 1),
"used_percent": round(u.used / u.total * 100, 1),
}
def get_current_time(tz="Asia/Seoul"):
now = datetime.datetime.now(ZoneInfo(tz))
return {"iso": now.isoformat(timespec="seconds"), "tz": tz}
FUNCS = {"get_disk_usage": get_disk_usage, "get_current_time": get_current_time}
def run_agent(question, max_steps=6):
input_list = [{"role": "user", "content": question}]
for step in range(max_steps):
response = client.responses.create(model=MODEL, tools=TOOLS, input=input_list)
input_list += response.output # 모델 출력을 대화 기록에 그대로 붙인다
calls = [item for item in response.output if item.type == "function_call"]
if not calls:
return response.output_text
for call in calls:
args = json.loads(call.arguments) # arguments는 JSON 문자열이다
result = FUNCS[call.name](**args)
input_list.append(
{
"type": "function_call_output",
"call_id": call.call_id,
"output": json.dumps(result, ensure_ascii=False),
}
)
print(f"[step {step}] {call.name}({args}) -> {result}")
return "단계 한도를 넘었다. 질문을 더 좁혀 보자."
if __name__ == "__main__":
print(run_agent("내 맥 디스크 얼마나 남았는지 알려줘. 지금 몇 시인지도."))
핵심은 세 줄이다.
input_list += response.output— 모델이 낸function_call항목을 다음 요청의 입력에 넣어야 한다. 이걸 빼먹으면 결과만 보내게 되고, 서버는 어떤 호출에 대한 답인지 찾지 못한다.call_id— 결과를 원래 호출과 짝지어 주는 열쇠다.call.arguments가 아니라 반드시call.call_id를 쓴다.max_steps— 모델이 같은 툴을 계속 부르는 경우를 막는 안전장치다. 없으면 루프가 끝나지 않는다.
실행해 보기 — 실제 터미널 출력
내 맥에서 돌린 결과다. 툴이 두 개 다 불렸고, 모델이 결과를 합쳐 한 문장으로 답했다.
[step 0] get_disk_usage({'path': '/'}) -> {'path': '/', 'total_gb': 233.5, 'free_gb': 167.4, 'used_percent': 28.3}
[step 0] get_current_time({'tz': 'Asia/Seoul'}) -> {'iso': '2026-11-22T09:00:03+09:00', 'tz': 'Asia/Seoul'}
디스크는 전체 233.5GB 중 167.4GB가 남아 있고(사용률 28.3%), 현재 시각은 2026년 11월 22일 09시 00분 03초(서울)입니다.
[step 0]이 두 번 찍힌 것에 주목하자. 모델이 한 번의 응답에서 두 툴을 동시에 요청했다. 문서 기준으로 GPT-5 계열 이후 모델은 병렬 툴 호출을 지원하므로, 응답의 output 배열에는 function_call 항목이 여러 개 들어올 수 있다(Parallel function calling). if item.type == "function_call"을 하나만 처리하는 코드를 짜면 두 번째 호출이 사라진다.
shutil.disk_usage는 경로가 올라가 있는 파일시스템의 전체·사용·여유 바이트를 named tuple로 돌려준다(Python 문서). 그래서 GB로 나눠 쓰는 변환이 필요하다.
툴 늘리기 — 병렬 호출과 tool_choice
툴을 붙일 때 자주 만지는 파라미터는 두 개다.
| 파라미터 | 값 | 쓰는 상황 |
|---|---|---|
tool_choice | "auto" (기본) | 모델이 알아서 0개 이상 고른다 |
tool_choice | "required" | 무조건 툴을 부르게 하고 싶을 때 |
tool_choice | {"type": "function", "name": "get_disk_usage"} | 특정 함수 하나만 강제 |
tool_choice | "none" | 툴 없이 답하게 하고 싶을 때 |
parallel_tool_calls | False | 한 턴에 정확히 0~1개만 부르게 제한 |
tool_choice에는 allowed_tools로 후보를 좁히는 모드도 있다. 툴 목록은 그대로 두고 이번 턴에서 쓸 수 있는 것만 제한하고 싶을 때 쓴다. 프롬프트 캐싱 이점을 유지하려는 용도다(Tool choice).
툴을 추가하는 절차는 늘 같다. 함수를 쓰고, TOOLS에 스키마를 넣고, FUNCS에 이름을 등록한다. 이 세 곳만 고치면 루프는 손대지 않아도 된다.
에이전트가 자주 틀리는 곳 — 루프·인자·권한
루프가 안 끝난다
같은 툴을 반복 호출하는 경우다. 원인은 대개 툴 설명이 모호해서다. "디스크 정보를 가져온다"만 적어 두면 모델이 결과를 못 믿고 다시 부른다. 어떤 값을 어떤 단위로 돌려주는지, 이 결과로 질문이 해결된다는 점까지 설명에 적으면 반복이 줄어든다. 그래도 남으면 max_steps로 자른다.
인자가 이상하게 온다
call.arguments는 문자열이라 json.loads를 거쳐야 한다. 여기서 타입이 안 맞으면 TypeError가 나고, 그 순간 루프 전체가 죽는다. 실행부를 try/except로 감싸고 예외 메시지를 output에 담아 돌려주면 모델이 인자를 고쳐서 다시 시도한다. 에러 문구를 그대로 주는 게 핵심이다. JSONDecodeError의 위치 정보를 읽는 법은 JSON 파싱 방법에 정리해 뒀다.
권한을 너무 많이 준다
셸 실행이나 파일 삭제를 툴로 열어 두면, 모델의 판단 한 번으로 되돌릴 수 없는 일이 벌어진다. 읽기 전용 툴부터 시작하고, 쓰기 툴은 인자를 코드에서 검증한 뒤 실행하는 편이 안전하다. 외부 서비스라면 MCP 서버로 분리해서 권한 범위를 좁히는 방법도 있다(Claude MCP 설정 방법).

내가 막혔던 곳
첫 번째는 파이썬 버전이었다. 이 맥의 기본 파이썬은 3.9.6이고, openai SDK는 3.10 이상을 요구한다. 3.9 환경에서는 최신 SDK를 쓸 수 없으니, 처음부터 3.10 이상으로 가상환경을 만들고 그 안에서 설치하는 편이 확실하다. venv 만드는 법은 Python 가상환경 venv 만들기에 있다.
두 번째는 response.output을 안 붙인 일이다. 결과만 function_call_output으로 보냈더니 서버가 짝이 되는 호출을 찾지 못해 요청이 거부됐다. 문서 예제의 input_list += response.output 한 줄이 장식이 아니었다. 지금은 루프를 짤 때 이 줄을 가장 먼저 쓰고 시작한다.
세 번째는 툴 설명을 대충 쓴 것이다. "시간 가져오기"라고만 적었더니 모델이 tz에 "KST"를 넣어 왔다. IANA 이름이 필요하다는 걸 설명에 예시로 적고 나서 사라졌다. 문서가 말한 "인턴에게 설명하듯 쓰라"는 조언이 과장이 아니었다.
참고 자료
- OpenAI — Function calling 가이드
- OpenAI — Strict mode와 스키마 요구사항
- openai-python README (GitHub)
- OpenAI — Models
- Python 문서 — shutil.disk_usage
- Python 문서 — zoneinfo
관련 글: AI 에이전트란 · OpenAI API 사용법 (Python) · Claude MCP 설정 방법
최소한의 AI 상식, 글로만 보기 아쉬우면
유튜브 AI 뉴스·개념을 10분 안에 정리해 영상으로 올립니다. 구독하면 새 영상 알림이 갑니다. 뉴스레터 매주 한 통, 블로그에 안 쓴 AI 소식과 실무 팁을 메일로 보내드립니다. 구독은 여기서.광고가 아닌 제가 운영하는 채널입니다.
'IT' 카테고리의 다른 글
| JSON 파싱 방법 — json.loads 오류 메시지별 해결까지 (0) | 2026.11.21 |
|---|---|
| OpenAI API 사용법 — 파이썬 첫 호출부터 요금·에러까지 (0) | 2026.11.20 |
| 어사이드 vs 에고 라이트 vs 핸들러스 — 내 브라우저를 AI에게 맡기는 3가지 방법 (0) | 2026.11.20 |
| 에고 라이트(ego lite) 사용법 — 클로드코드가 내 로그인 브라우저를 쓴다 (0) | 2026.11.20 |
| 핸들러스(Handlus) MCP 사용법 — 클로드코드가 내 브라우저를 직접 조작한다 (0) | 2026.11.20 |

















