- Knowledge
AI 에이전트를 직접 만든다면 어떤 코드가 필요할까?
간단한 주문 조회 에이전트 코드를 통해 모델 호출, 도구 스키마, 인자 검증, 실행 반복, 종료 조건과 실제 운영 한계를 연결합니다.
시리즈15편 중 15편AI 에이전트는 어떻게 일할까
- 01AI는 어떻게 대답만 하다가 실제로 일을 처리하게 될까?
- 02AI 에이전트는 왜 같은 작업을 계속 반복할까?
- 03AI는 방금 읽은 파일을 왜 다시 찾아볼까?
- 04AI에게 도구를 많이 연결하면 왜 오히려 일을 못할까?
- 05AI에게 문서를 검색하게 해도 왜 틀린 답을 할까?
- 06AI가 코드를 고쳤다면 바로 실행해도 될까?
- 07AI가 응답하지 않아 다시 실행했는데, 왜 작업이 두 번 처리될까?
- 08AI 여러 명을 동시에 투입하면 개발이 더 빨라질까?
- 09AI가 이상한 행동을 했을 때 어디부터 디버깅해야 할까?
- 10AI와 대화할 때 실제로 어떤 데이터가 오갈까?
- 11AI는 왜 대화가 길어질수록 비용이 많이 들까?
- 12AI 에이전트를 여러 개 만드는 진짜 이유는 무엇일까?
- 13AI가 작업하는 도중 상황이 바뀌면 어떻게 알까?
- 14AI 에이전트에 새로운 능력을 추가하는 방법은?
- 15AI 에이전트를 직접 만든다면 어떤 코드가 필요할까?읽는 중
에이전트를 만들려면 모델 호출부터 도구 실행, 결과 전달, 종료 조건까지 연결해야 합니다. 주문 상태를 조회하는 작은 예제로 이 과정이 어떻게 이어지는지 살펴보겠습니다.
이 예제는 모델의 도구 요청을 받아 샘플 데이터를 조회하고, 그 결과를 모델에 돌려줍니다.
만들 프로그램의 범위를 먼저 정하자
사용자가 “A-102 주문은 어디까지 진행됐어?”라고 질문하면, 모델은 lookup_order 도구를 요청합니다. 프로그램은 준비된 샘플 주문 데이터를 조회하고, 모델은 조회 결과를 읽어 답합니다.
실제 쇼핑몰 API를 호출하거나 결제·환불·주소 변경을 수행하지 않습니다. 읽기 전용 도구 하나만 제공하는 이유는 동작 원리를 먼저 확인하기 위해서예요.
구성 요소는 모델을 부르는 함수, 조회 도구 설명, 도구 실제 구현, 반복 실행, 종료 조건입니다. 이 가운데 어느 하나가 빠지면 ‘AI가 행동하는 과정’을 확인하기 어려워집니다.
도구 이름만 적어 주면 실행될까?
아니요. 모델에 보여 줄 설명과 실제 함수를 둘 다 작성해야 합니다. 모델은 ‘이런 함수를 요청할 수 있다’는 사실을 알지만, 애플리케이션의 코드를 직접 실행하지는 않습니다.
다음 코드는 Python용 OpenAI SDK의 Responses API를 사용하는 설명용 소형 예제입니다. pip install openai로 SDK를 설치하고 OPENAI_API_KEY 환경 변수를 설정한 뒤 실행할 수 있습니다. OPENAI_MODEL 환경 변수로 사용 가능한 도구 호출 지원 모델을 지정할 수 있어요. 계정과 모델 접근 권한, 과금 설정은 별도로 필요합니다.
import json
import os
from openai import OpenAI
client = OpenAI()
MODEL = os.getenv("OPENAI_MODEL", "gpt-5.5")
ORDERS = {
"A-102": "배송 준비 중",
"A-103": "배송 완료",
}
TOOLS = [{
"type": "function",
"name": "lookup_order",
"description": "샘플 주문 ID의 상태를 조회한다. 결제나 변경은 하지 않는다.",
"parameters": {
"type": "object",
"properties": {
"order_id": {"type": "string"}
},
"required": ["order_id"],
"additionalProperties": False,
},
"strict": True,
}]
def execute_tool(name, arguments):
if name != "lookup_order":
return {"error": "unknown_tool"}
try:
args = json.loads(arguments)
except json.JSONDecodeError:
return {"error": "invalid_arguments"}
if not isinstance(args, dict):
return {"error": "invalid_arguments"}
order_id = args.get("order_id")
if not isinstance(order_id, str) or len(order_id) > 32:
return {"error": "invalid_order_id"}
status = ORDERS.get(order_id)
return {"order_id": order_id, "status": status or "조회 결과 없음"}
def run_agent(question):
history = [{"role": "user", "content": question}]
for _ in range(5):
response = client.responses.create(
model=MODEL,
instructions="샘플 주문 조회만 도와주세요. 추측하지 마세요.",
tools=TOOLS,
input=history,
store=False,
)
if response.status != "completed":
raise RuntimeError(f"model status: {response.status}")
# 도구 호출뿐 아니라 추론 등 모든 출력 항목을 보존한다.
history.extend(item.model_dump(exclude_none=True)
for item in response.output)
calls = [item for item in response.output
if item.type == "function_call"]
if not calls:
if not response.output_text:
raise RuntimeError("no final answer")
return response.output_text
for call in calls:
result = execute_tool(call.name, call.arguments)
history.append({
"type": "function_call_output",
"call_id": call.call_id,
"output": json.dumps(result, ensure_ascii=False),
})
raise RuntimeError("too many agent steps")
print(run_agent("A-102 주문은 지금 어떤 상태야?"))모델의 실제 응답 문구는 달라질 수 있습니다. 또한 API와 SDK는 변경될 수 있으므로 실행 환경에서 지원되는 모델명·파라미터를 확인해야 합니다.
코드 안에서 실제로 벌어지는 일
첫 요청에는 사용자 질문과 도구 설명이 들어갑니다. 모델은 답을 바로 만들 수도 있고, lookup_order라는 함수 호출을 요청할 수도 있어요.
함수 호출이 왔다면 call.arguments의 JSON 문자열을 파싱합니다. 하지만 모델이 보냈다는 이유만으로 인자를 믿지는 않습니다. 도구 이름과 주문 ID 형식을 검사한 뒤 샘플 딕셔너리에서 값을 읽습니다.
그 결과는 function_call_output 항목이 되어 다시 모델 입력에 포함됩니다. 여기에는 이전에 모델이 요청한 특정 호출과 결과를 연결하는 call_id가 들어갑니다. 여러 도구가 동시에 호출될 때 특히 중요해요.
for문이 있으면 자동으로 에이전트일까?
반복문만으로는 부족합니다. 종료 사유를 판단하고, 사용할 수 있는 도구를 제한하고, 결과를 다시 전달하며, 실행 횟수의 상한을 정해야 합니다.
예제는 최대 다섯 번의 모델 호출을 허용합니다. 도구 요청이 없고 최종 답변이 있을 때 종료하고, 다섯 차례 안에 끝나지 않으면 오류를 발생시켜요. 실제 제품이라면 시간 제한과 토큰 예산, 취소 요청도 함께 다뤄야 합니다.
또한 이 샘플은 하나의 요청 안에서만 대화 기록을 보관합니다. 프로그램을 다시 실행해 다른 질문을 던지면 이전 대화가 자동으로 이어지지 않습니다. 긴 세션이 필요하다면 상태 저장과 요약·검색 같은 기능을 별도로 추가해야 하죠.
실제 서비스라면 어떤 부분이 더 필요할까?
첫 번째는 인증과 권한입니다. 주문 조회 도구를 실제 데이터베이스에 연결한다면 사용자의 로그인 정보와 주문 소유권을 확인해야 합니다. 모델이 제공한 주문 ID만으로 다른 사람의 정보를 공개해서는 안 됩니다.
두 번째는 오류 처리입니다. 네트워크 오류, 속도 제한, 일시적 장애를 구분해야 하고, 재시도에 따른 중복 효과가 생기는 작업은 특히 주의해야 합니다.
세 번째는 관측과 평가입니다. 모델이 어떤 도구를 요청했는지, 인자 검사가 통과했는지, 조회 결과와 최종 답변이 일치하는지 확인할 수 있어야 해요. 실제 로그에는 주문 번호나 개인 정보를 가능한 범위에서 마스킹해야 합니다.
네 번째는 도구 결과의 신뢰 경계입니다. 실서비스에서 받은 설명문이나 외부 데이터는 모델의 상위 규칙이 아닙니다. 사용자 입력과 도구 출력이 서로 다른 출처라는 구분을 유지해야 합니다.
단순한 예제가 가르쳐 주는 한 가지
규모가 커져도 기본 질문은 변하지 않습니다. 모델이 무엇을 요청했는가? 프로그램은 어떤 근거로 그 요청을 실행했는가? 실제로 무슨 결과가 나왔는가?
작은 주문 조회 예제는 그 세 질문을 확인하기에 충분합니다. 여기에 권한 검사, 상태 저장, 캐싱, 작업 위임, 재시도, 추적 기능을 더하면 훨씬 복잡한 시스템을 만들 수 있지만, 각 기능은 여전히 구체적인 실패를 막기 위해 존재합니다.
실제 서비스로 확장할 때는 모델이 고른 도구와 인자를 어디까지 허용할지, 실행 결과를 어떻게 검증할지부터 정해야 합니다.
갑자기 추워진 날, 진주에서
진주에서 하루종일 돌아다녔다

내 단점을 커버하는 동료와 함께.
새로운 프로젝트를 함께 준비하는 친구와의 저녁. 미운 점도 고마운 점도 있지만, 결국 같이 잘됐으면 좋겠다는 마음.

순천과 여수 여행3
마지막 하루. 공부랑 런닝으로 끝내기


댓글 0
이 글에 대한 생각을 자유롭게 남겨주세요.
댓글을 불러오는 중…