📋 목차
AI 에이전트라는 말이 워낙 자주 들리다 보니 거창한 프로그램부터 떠올리기 쉬워요. 실제 구조를 뜯어보면 언어 모델에 지시문과 도구, 작업 상태를 붙여 반복 실행하도록 만든 프로그램에 가까워요. 2026년에는 OpenAI Agents SDK나 LangChain 계열처럼 이 반복 구조를 대신 관리해 주는 개발 도구도 꽤 성숙해졌거든요. 코딩을 조금만 할 수 있다면 간단한 업무 에이전트는 생각보다 작은 코드로 시작할 수 있어요.
핵심은 AI가 말을 잘하는지가 아니라 필요한 순간에 검색하고 API를 호출하고 결과를 다시 판단하도록 설계하는 데 있어요. 예를 들어 고객 문의를 받은 뒤 주문번호를 조회하고 배송 상태를 확인해서 답변하는 흐름이라면 단순 채팅보다 에이전트 구조가 잘 맞죠. 처음부터 여러 AI를 연결할 필요도 없어요. 하나의 에이전트와 1~3개 도구로 출발하는 편이 실패 원인을 찾기도 훨씬 쉽더라고요.
AI 에이전트는 챗봇과 뭐가 다를까
일반 챗봇은 사용자가 질문을 던지면 모델이 답을 생성하는 구조가 중심이에요. 반면 에이전트는 답을 바로 만들기보다 목표를 달성하기 위해 어떤 행동이 필요한지 판단할 수 있어요. 필요한 정보가 없으면 검색 도구를 호출하고 계산이 필요하면 계산 함수를 실행하게 만들 수도 있죠. 짧게 말하면 챗봇은 대화가 중심이고 에이전트는 행동까지 포함한 구조에 가까워요.
OpenAI Agents SDK의 2026년 공식 문서를 보면 에이전트를 지시문과 도구가 설정된 언어 모델을 중심으로 설명하고 있어요. 실행 과정에서는 모델이 답을 낼지, 도구를 호출할지, 다른 에이전트에게 넘길지를 반복적으로 판단하게 돼요. 이 반복 실행을 직접 while문으로 구현할 수도 있고 SDK의 Runner 같은 기능에 맡길 수도 있거든요. 아, 이 차이를 이해하면 에이전트 개발이 갑자기 단순해져요.
예를 들어 사용자가 서울에서 부산까지 가장 저렴한 이동 방법을 찾아 달라고 했다고 해볼게요. 일반 모델은 기억하고 있는 정보와 입력된 내용으로 답을 만들 가능성이 커요. 여행 검색 에이전트라면 교통 API를 조회하고 출발 시간을 확인한 뒤 가격 조건을 비교하도록 만들 수 있죠. 실제 세계의 최신 데이터와 연결된다는 점이 꽤 큰 차이에요.
에이전트라고 해서 스스로 모든 일을 결정하게 만들어야 하는 건 아니에요. 오히려 실제 서비스에서는 허용된 도구와 행동 범위를 좁혀놓는 편이 안정적이에요. 환불 에이전트라면 주문조회와 환불 가능 여부 확인까지 자동으로 처리하고 실제 환불 버튼을 누르기 전에는 사람 승인을 받게 설계할 수 있어요. 이런 식으로 자율성과 통제를 섞는 게 현실적인 방식인 거예요.
워크플로와 에이전트를 구분하는 것도 꽤 중요해요. LangGraph 공식 문서에서는 정해진 경로를 따라가는 작업을 워크플로로, 상황에 따라 도구와 경로를 선택하는 구조를 에이전트로 설명하고 있어요. 모든 자동화를 굳이 에이전트로 만들 필요가 없다는 뜻이죠. 이메일 수신 후 PDF 저장처럼 순서가 늘 같은 업무라면 일반 자동화가 더 단순할 때도 있어요.
근데 실제로 만들다 보면 에이전트라는 이름에 욕심이 붙기 쉬워요. 검색도 넣고 메일도 보내고 파일도 수정하고 브라우저까지 조작하게 만들면 멋있어 보이잖아요. 기능 하나가 늘어날 때마다 실패 가능성과 비용, 권한 관리 지점도 함께 늘어나게 돼요. 처음에는 정말 필요한 행동이 무엇인지 한 문장으로 정의하는 게 좋아요.
좋은 목표는 측정할 수 있어야 해요. '유능한 비서 만들기'보다 '받은 메일에서 회의 요청을 찾아 일정 후보 세 개를 제안하는 에이전트'가 훨씬 낫죠. 입력과 완료 조건이 눈에 보이니까 테스트도 쉬워져요. 목표를 이렇게 좁혀본 적 있어요?
비용 관점에서도 범위를 줄이는 게 유리해요. 모델 호출 한 번이 100원이라고 가정해도 작업마다 10번 반복되면 1회 실행에 1,000원이 되는 구조잖아요. 실제 가격은 사용하는 모델과 토큰량에 따라 달라지지만 반복 횟수가 비용에 직접 연결된다는 원리는 같아요. 이 계산을 처음 해보면 생각보다 놀랄 수 있어요.
그래서 첫 에이전트는 한 번의 요청이 2~5단계 안에서 끝나는 업무가 좋아요. 정보 검색, 조건 판단, 결과 작성 정도만 있어도 에이전트의 핵심 구조를 충분히 경험할 수 있거든요. 성공률을 확인한 뒤 행동을 하나씩 붙이면 돼요. 처음부터 사람처럼 모든 업무를 맡기는 방식은 디버깅이 정말 어려워져요.
내가 생각했을 때 가장 중요한 기준은 'AI가 행동을 선택할 필요가 있는가'예요. 매번 동일한 프로그램 순서로 해결되는 문제라면 일반 코드가 더 저렴하고 예측하기 쉬워요. 상황을 읽고 검색이나 계산 같은 여러 행동 가운데 하나를 골라야 한다면 에이전트가 빛을 발하죠. 이 구분만 잘해도 필요 이상으로 복잡한 시스템을 만들 가능성이 크게 줄어요.
챗봇과 에이전트 구조 차이
| 항목 | 일반 챗봇 | AI 에이전트 |
|---|---|---|
| 주요 역할 | 답변 생성 | 판단과 행동 실행 |
| 도구 호출 | 선택적 | 핵심 기능 |
| 반복 실행 | 보통 1회 | 목표 달성까지 여러 회 |
| 대표 활용 | 상담·질문답변 | 검색·예약·업무자동화 |
에이전트 구조를 직접 보면 훨씬 빨리 감이 와요
공식 SDK에서 현재 구조를 확인해 보세요
코드부터 보기 전에 공식 개념을 확인하면 시행착오가 줄어요
OpenAI Agents SDK 공식 문서에서 Agent와 Runner 구조를 볼 수 있어요.
OpenAI Agents SDK 확인하기만들기 전에 구조부터 이렇게 잡아보자
AI 에이전트의 기본 부품은 생각보다 많지 않아요. 모델, 지시문, 도구, 상태 또는 메모리, 실행 루프 정도를 잡으면 기본 골격이 생겨요. 사용자 입력이 들어오면 모델이 상황을 판단하고 필요한 도구를 골라 호출한 뒤 결과를 다시 모델에게 전달하죠. 목표가 해결되면 실행을 멈추고 답을 사용자에게 돌려주는 흐름이에요.
모델은 말 그대로 두뇌 역할을 해요. 복잡한 판단이 필요한 업무에는 추론 능력이 높은 모델이 유리하고 단순 분류나 정보 변환에는 가벼운 모델도 충분할 수 있어요. 모든 작업에 가장 큰 모델을 쓰면 속도와 비용이 부담될 수 있거든요. 업무별로 필요한 능력을 먼저 보는 편이 좋아요.
지시문은 에이전트의 업무 설명서라고 보면 쉬워요. '친절하게 답하라' 정도로 끝내기보다 목표와 금지 행동, 도구를 사용할 조건, 종료 조건을 적는 게 훨씬 안정적이에요. 예를 들면 '주문 상태는 반드시 주문조회 도구의 결과만 사용하고 정보가 없으면 추측하지 않는다'처럼 쓰는 방식이죠. 짧아도 기준이 또렷한 지시문이 꽤 강해요.
도구는 에이전트에게 손과 발을 붙여주는 부분이에요. 검색 API, 데이터베이스 조회, 사내 시스템, 계산 함수, 캘린더, 이메일 발송 기능 등을 도구로 연결할 수 있죠. OpenAI Agents SDK 2026 문서에서도 함수 도구와 서버에서 실행되는 도구, 다른 에이전트를 도구로 쓰는 구조 등을 지원하고 있어요. 모델 자체가 할 수 없는 외부 행동을 이 계층에서 처리하게 되는 거예요.
상태는 지금 작업이 어디까지 진행됐는지를 기억하는 공간이에요. 주문번호를 이미 확인했는지, 검색 결과가 무엇이었는지, 사용자 승인이 필요한지 같은 정보를 담을 수 있죠. 작업이 한 번의 호출로 끝난다면 복잡한 상태 저장소가 필요 없어요. 장시간 이어지는 업무라면 데이터베이스나 세션 저장 구조가 필요하게 돼요.
실행 루프는 모델과 도구를 이어주는 엔진이에요. 모델이 도구 호출을 요청하면 프로그램이 도구를 실행하고 결과를 다시 모델에게 보내죠. 모델이 다른 행동이 필요하다고 판단하면 같은 과정을 반복해요. 솔직히 에이전트의 정체는 이 반복 구조에 있다고 봐도 크게 틀리지 않아요.
종료 조건도 꼭 필요해요. 모델이 계속 검색하거나 같은 도구를 반복 호출하면 비용과 시간이 끝없이 늘어날 수 있거든요. OpenAI Agents SDK에는 실행 턴 수를 제한하는 방식이 마련돼 있고 직접 구현할 때도 5회나 10회처럼 상한을 두는 게 좋아요. 무한 반복을 실제로 만나면 꽤 충격적이에요.
사람 승인을 어느 지점에 넣을지도 설계 단계에서 정해야 해요. 읽기 전용 검색은 자동으로 돌려도 괜찮은 경우가 많지만 결제, 환불, 삭제, 이메일 발송은 이야기가 달라지죠. 실행 전 승인 화면을 하나 넣는 것만으로 사고 범위를 크게 줄일 수 있어요. 돈이 움직이는 행동을 AI에게 바로 맡기면 어떨까요?
개인 프로젝트라면 서버 비용 1만원만 잡아도 한 달 1만원이고 데이터베이스와 외부 API 비용을 더하면 지출이 커질 수 있어요. 그래서 처음에는 로컬 환경과 SQLite 같은 가벼운 저장소로 검증하는 방식이 부담이 적어요. 사용자 수가 늘어난 뒤 운영형 데이터베이스와 모니터링을 붙여도 늦지 않죠. 기능보다 검증 순서가 비용을 좌우해요.
한 장으로 구조를 적는다면 '사용자 → 에이전트 → 도구 → 외부 서비스 → 결과 → 에이전트 → 사용자'면 충분해요. 복잡한 멀티 에이전트 그림부터 그리면 오히려 핵심 업무가 잘 안 보일 수 있어요. 하나의 에이전트가 제대로 일을 끝내는지 먼저 테스트하는 편이 낫죠. 이 작은 구조가 실제 서비스의 출발점이 되는 셈이에요.
💡 처음 설계할 때는 입력, 사용할 도구, 완료 조건 세 가지만 종이에 적어보세요. 예를 들어 '상품명 입력 → 쇼핑 검색 도구 → 가격 3개 반환'처럼 한 줄로 표현할 수 있으면 개발하기도 쉬워져요. 기능을 추가할 때마다 이 한 줄이 여전히 유지되는지 확인하면 구조가 덜 꼬여요. 처음부터 멀티 에이전트를 목표로 잡을 이유는 거의 없어요.
처음 만들 때 필요한 구성요소
| 구성 | 역할 | 초기 권장 수준 |
|---|---|---|
| 모델 | 판단과 답변 생성 | 1개 |
| 도구 | 검색·계산·API 호출 | 1~3개 |
| 메모리 | 대화·작업 상태 저장 | 필요할 때만 |
| 실행 제한 | 무한 반복 방지 | 5~10턴부터 테스트 |
도구를 붙이면 에이전트가 어떻게 움직일까
도구 연결부터 에이전트다운 움직임이 생겨요. 모델에게 현재 날씨를 물으면 모델의 기억만으로는 실시간 정보를 확정하기 어렵지만 날씨 API 도구를 제공하면 필요한 도시를 인자로 넣어 호출할 수 있죠. 프로그램은 API 결과를 받아 다시 모델에게 전달해요. 모델은 받은 실제 데이터를 자연스러운 답으로 바꿔 사용자에게 보여주게 돼요.
도구는 함수 하나로 시작해도 충분해요. 예를 들어 get_order_status라는 함수를 만들고 주문번호를 받도록 정의할 수 있어요. 모델은 사용자의 문장에서 주문번호를 찾고 도구가 필요하다고 판단하면 해당 함수를 호출하죠. 개발자는 함수 내부에서 실제 데이터베이스나 쇼핑몰 API를 연결하면 돼요.
Python으로 OpenAI Agents SDK를 쓴다면 함수 도구를 비교적 간단하게 붙일 수 있어요. 2026년 공식 Agents SDK 문서에서는 일반 Python 함수를 FunctionTool 형태로 노출하는 방식을 제공하고 있거든요. 함수 이름과 설명, 입력 구조가 모델의 선택에 영향을 주므로 의미가 분명하게 만드는 게 좋아요. 애매한 이름을 쓰면 엉뚱한 도구를 고르는 일이 생길 수 있어요.
from agents import Agent, Runner, function_tool
@function_tool
def get_order_status(order_id: str) -> str:
return f"{order_id} 주문은 배송 준비 중이에요."
agent = Agent(
name="주문 상담 에이전트",
instructions="주문 상태 질문에는 주문 조회 도구를 사용하고 결과를 추측하지 마세요.",
tools=[get_order_status]
)
result = Runner.run_sync(
agent,
"주문번호 A1024 배송 상태를 확인해줘"
)
print(result.final_output)이 코드에서 중요한 부분은 답변 문장이 아니라 도구를 사용할 수 있도록 모델에 권한을 줬다는 점이에요. Runner가 모델 호출과 도구 실행, 결과 전달 과정을 이어주기 때문에 개발자가 반복 루프를 하나하나 작성하지 않아도 돼요. 실제 환경에서는 get_order_status 내부에서 사내 주문 API를 호출하게 바꾸면 되죠. 코드 몇 줄인데 동작 원리를 보면 꽤 놀랍더라고요.
근데 도구에 지나치게 많은 권한을 주면 위험해져요. 사용자 조회 함수가 데이터 수정까지 할 수 있도록 만들어두면 잘못된 호출 한 번이 실제 데이터를 바꿀 수 있거든요. 읽기 도구와 쓰기 도구를 분리하고 변경 작업에는 별도 승인을 요구하는 게 좋아요. 권한 최소화는 에이전트 개발에서도 기본 원칙이에요.
외부 서비스를 여러 개 연결할 때 MCP를 검토할 수도 있어요. 2026년 7월 공개된 Model Context Protocol 사양에서는 서버가 도구와 리소스 같은 기능을 표준화된 방식으로 노출할 수 있도록 정의하고 있어요. 특정 AI 프레임워크마다 연동 코드를 전부 새로 만드는 부담을 줄이는 방향으로 볼 수 있죠. 도구가 많아지는 프로젝트에서 특히 관심을 둘 만해요.
MCP가 무조건 필요한 건 아니에요. 외부 API 한두 개를 붙이는 개인 프로젝트라면 일반 함수 호출이 더 단순할 수 있어요. 연결할 시스템이 늘거나 여러 AI 클라이언트에서 같은 도구를 쓰려는 상황이면 표준 인터페이스의 장점이 커지죠. 규모에 맞춰 선택해야 코드가 덜 복잡해져요.
도구 호출 비용도 생각해야 해요. 검색 API가 호출당 50원만 잡혀도 한 업무에서 10번 검색하면 외부 API 비용만 500원이 되는 셈이에요. 모델이 같은 검색을 반복하지 않도록 결과 캐시와 호출 제한을 두면 비용이 상당히 달라질 수 있죠. 이런 숫자를 로그에서 확인해 본 적 있어요?
도구 결과도 무조건 믿으면 안 돼요. API가 오류 메시지를 정상 데이터처럼 반환하거나 예상하지 못한 빈 값을 줄 수도 있거든요. 함수에서 데이터 타입과 필수 필드를 검사한 뒤 모델에 넘기는 방식이 안전해요. 모델 앞단에서 처리할 수 있는 검증은 코드로 처리하는 편이 훨씬 예측 가능해요.
실전에서는 검색 도구 하나와 업무 API 하나만 붙여도 꽤 쓸 만한 에이전트가 만들어져요. 시장조사라면 웹 검색과 문서 저장 기능, 고객지원이라면 주문 조회와 티켓 생성 기능 정도로 출발할 수 있죠. 도구 수를 늘리는 것보다 각 도구의 입력과 출력이 명확한지가 더 중요해요. 잘 정의된 작은 도구들이 에이전트의 품질을 크게 좌우해요.
외부 서비스 연결이 많다면 MCP 구조도 알아둘 만해요
현재 표준 사양에서 도구 연결 방식을 확인해 보세요
메모리와 데이터는 어디에 저장해야 할까
에이전트를 한 번 실행하고 끝낼 거라면 메모리가 없어도 돼요. 여러 번 대화하면서 앞선 내용을 기억해야 한다면 상태 저장이 필요해지죠. 사용자의 이름이나 직전 요청, 이미 실행한 도구 결과를 다시 사용할 수 있어야 자연스러운 흐름이 생겨요. 문제는 무엇을 얼마나 오래 저장할지예요.
가장 단순한 형태는 대화 기록을 그대로 저장하는 방식이에요. OpenAI Agents SDK 공식 문서에는 세션을 이용해 여러 실행 사이의 대화 기록을 관리하는 기능이 안내돼 있어요. SQLite 기반 세션처럼 로컬에서 시작할 수 있는 선택지도 있죠. 테스트 단계에서는 이런 구조로도 충분한 경우가 많아요.
from agents import Agent, Runner, SQLiteSession
agent = Agent(
name="개인 비서",
instructions="사용자의 앞선 대화를 참고해 짧고 정확하게 답하세요."
)
session = SQLiteSession("user_001")
result = Runner.run_sync(
agent,
"내 프로젝트 이름은 아침뉴스봇이야.",
session=session
)
result = Runner.run_sync(
agent,
"내 프로젝트 이름이 뭐였지?",
session=session
)
print(result.final_output)이 방식은 대화 맥락을 이어가기 편해요. 반대로 모든 대화 내용을 계속 쌓아두면 컨텍스트가 커지고 비용이나 개인정보 관리 문제가 생길 수 있어요. 오래된 대화를 요약하거나 필요한 정보만 별도 프로필로 저장하는 구조가 필요한 이유죠. 기억이 많다고 항상 에이전트가 똑똑해지는 건 아니에요.
업무 데이터는 대화 기록과 분리하는 편이 좋아요. 사용자의 배송 주소나 회사 고객정보를 프롬프트 속에 계속 끼워 넣기보다 필요한 순간에 데이터베이스에서 조회하도록 만들 수 있죠. 접근 권한도 사용자별로 확인해야 해요. 한 사용자의 정보가 다른 세션으로 넘어가면 심각한 문제가 될 수 있거든요.
문서 검색이 필요한 에이전트라면 RAG 구조를 함께 사용할 수도 있어요. 사내 규정이나 제품 설명서를 검색해서 관련 부분만 모델에 전달하는 방식이죠. 에이전트는 질문을 보고 문서 검색이 필요한지 판단할 수 있고 검색 결과가 부족하면 추가 질문을 하도록 만들 수도 있어요. 고정된 자료를 모델에게 전부 암기시키려는 것보다 관리하기 쉬운 경우가 많아요.
LangGraph 공식 문서에는 상태를 중심으로 노드와 전환을 구성하는 방식이 설명돼 있어요. 긴 작업이나 중간 재시작이 필요한 시스템이라면 이런 상태 기반 오케스트레이션이 편해질 수 있죠. 예를 들어 계약서 검토가 검색, 위험 문구 확인, 사람 승인, 결과 작성 단계를 거친다면 진행 상태가 꽤 중요해요. 서버가 중간에 재시작돼도 어디까지 했는지 복구해야 하니까요.
뭐, 개인 메모 에이전트 정도라면 처음부터 복잡한 벡터 데이터베이스를 도입할 필요는 없어요. 사용자 100명에 텍스트 몇 KB만 저장하는 단계라면 일반 데이터베이스도 충분히 다룰 수 있죠. 저장비 1만원만 잡아도 사용하지 않는 인프라가 여러 개 붙으면 매달 고정비가 계속 나가요. 성장하기 전에는 단순한 구조가 오히려 강점이에요.
메모리에 넣지 말아야 할 것도 정해야 해요. 비밀번호와 인증 토큰 같은 민감 정보는 모델 대화 기록에 넣지 않는 구조가 기본이에요. 카드번호나 주민등록번호처럼 보호가 필요한 데이터도 최소한으로 다뤄야 하죠. 에이전트가 기억할 수 있다고 해서 기억시키는 게 좋은 건 아니에요.
기억의 정확성도 별도 문제예요. 사용자가 예전에 '나는 서울에 살아'라고 말했다가 몇 달 뒤 이사할 수도 있잖아요. 프로필 데이터에는 생성 시각과 수정 시각을 넣고 사용자가 변경할 수 있도록 만드는 게 좋아요. 오래된 기억을 영원히 사실로 취급하면 서비스 품질이 떨어지게 돼요.
메모리 설계가 잘됐는지는 세 가지 질문으로 확인해 볼 수 있어요. 지금 작업에 꼭 필요한가, 얼마나 오래 유효한가, 사용자가 삭제를 원하면 제거할 수 있는가를 보는 거죠. 세 질문에 답이 어려운 정보라면 굳이 저장하지 않는 편이 나을 수 있어요. 단순한 원칙인데 실제 운영에서는 차이가 크게 나요.
⚠️ API 키나 서비스 비밀번호를 에이전트 프롬프트 안에 직접 적어두지 않는 게 좋아요. 서버 환경변수나 별도 비밀정보 관리 시스템에 저장하고 도구 내부에서만 사용하도록 분리하는 편이 안전해요. 모델이 볼 필요가 없는 정보는 애초에 모델 컨텍스트로 보내지 않는 방식이 낫죠. 로그에도 인증정보가 남지 않는지 확인할 필요가 있어요.
대화가 길어질수록 메모리 구조가 더 중요해져요
공식 세션 방식부터 가볍게 시작해 보세요
직접 코딩해보니 막힌 지점은 여기였어요
첫 프로젝트로는 웹 리서치 에이전트 같은 작은 업무가 좋아요. 사용자가 주제를 입력하면 검색하고 결과를 요약해 주는 정도면 모델과 도구, 반복 실행을 한 번에 경험할 수 있죠. 처음부터 캘린더와 이메일과 데이터베이스를 모두 붙이면 어디에서 문제가 생겼는지 찾기가 어려워져요. 기능 하나가 안정된 뒤 확장하는 편이 훨씬 편했어요.
개발 환경은 Python을 기준으로 잡으면 진입 장벽이 낮은 편이에요. 가상환경을 만들고 OpenAI Agents SDK를 설치한 뒤 API 키를 환경변수로 설정하면 기본 준비가 끝나요. 실제 패키지 버전과 설치 방법은 변경될 수 있으므로 설치 시점의 공식 문서를 확인하는 게 좋아요. 2026년 Agents SDK 공식 페이지도 Python과 TypeScript 경로를 제공하고 있어요.
python -m venv .venv
source .venv/bin/activate
pip install openai-agents
export OPENAI_API_KEY="본인의_API_키"Windows에서는 가상환경 활성화 명령이 달라질 수 있어요. API 키는 코드 파일에 직접 입력하기보다 환경변수로 관리하는 게 좋아요. Git 저장소에 키가 올라가는 실수가 생각보다 흔하거든요. 키가 노출되면 즉시 폐기하고 새 키를 발급하는 편이 안전해요.
처음 만들었을 때 내가 가장 당황했던 부분은 모델이 도구를 항상 내가 예상한 순간에 호출하지 않는다는 점이었어요. 검색이 필요한 질문인데도 자체 지식으로 답하려고 하거나 비슷한 도구 둘 가운데 엉뚱한 쪽을 선택하는 경우가 있었거든요. 결과가 그럴듯해서 처음에는 코드가 제대로 작동한 줄 알고 한참 로그를 들여다봤어요. 원인을 찾고 나니 도구 설명과 지시문이 너무 모호해서 허탈함이 꽤 컸어요.
직접 해본 경험 '필요하면 검색하세요'라고 적었을 때보다 '가격, 일정, 최신 뉴스 질문에는 답변 전에 검색 도구를 사용하세요'라고 조건을 명확히 적으니 동작이 훨씬 예측 가능해졌어요. 도구 이름도 search1 같은 이름보다 search_recent_news처럼 역할이 드러나게 바꾸는 게 낫더라고요. 같은 기능인데 설명을 고쳤을 뿐인데 결과 차이가 커서 꽤 놀랐어요. 프롬프트를 글쓰기 문장으로 보기보다 프로그램의 정책으로 보는 게 편했어요.
도구 실패 상황도 직접 만들어서 테스트해야 해요. API가 500 오류를 내거나 검색 결과가 0개일 때 에이전트가 무엇을 하는지 확인하는 거죠. 정상 상황만 테스트하면 데모에서는 멋지게 보이다가 운영에서 바로 흔들릴 수 있어요. 실패를 예상하고 문구와 재시도 횟수를 미리 정하면 복구하기 쉬워져요.
테스트 질문은 최소 20~30개 정도 만들어두면 좋아요. 정상 질문과 애매한 질문, 도구가 필요 없는 질문, 악의적인 요청을 섞어보는 방식이죠. 한 번 잘 답했다고 에이전트가 안정됐다고 보기는 어려워요. 동일한 목표라도 표현을 바꿨을 때 같은 행동을 하는지 확인해야 해요.
로그에는 모델 호출 횟수와 도구 이름, 실행 시간, 성공 여부를 남겨두는 편이 좋아요. 비용이 이상하게 늘었을 때 어느 도구가 반복됐는지 추적하기 쉬워져요. 요청 1건당 300원만 잡아도 하루 1,000건이면 30만원이니 작은 반복 오류도 운영 규모에서는 커질 수 있어요. 숫자를 로그로 보면 체감이 확 달라져요.
프롬프트 버전도 기록해두는 게 좋아요. 지시문 한 줄을 바꿨는데 성공률이 떨어졌다면 어떤 변경 때문인지 알아야 하잖아요. 코드처럼 prompt_v1, prompt_v2 형태로 관리하거나 Git 변경 이력에 포함할 수 있어요. 에이전트에서는 프롬프트도 프로그램의 일부라고 보는 게 자연스러워요.
여러 에이전트는 단일 에이전트가 복잡해진 뒤 고민해도 늦지 않아요. OpenAI Agents SDK에는 다른 에이전트를 도구로 사용하거나 handoff 방식으로 업무를 넘기는 패턴이 제공돼 있어요. 조사 담당과 문서 작성 담당처럼 역할이 명확히 분리될 때 유용할 수 있죠. 역할 경계가 애매한데 여러 에이전트를 붙이면 서로 호출만 반복할 수도 있어요.
복잡한 장기 작업이라면 LangGraph 같은 그래프 기반 구조가 맞을 때도 있어요. 2026년 공식 문서를 보면 상태와 노드, 연결을 중심으로 결정적인 코드 단계와 모델 판단 단계를 섞을 수 있도록 설계돼 있어요. 사람 승인이나 작업 재개가 필요한 흐름에도 유용하죠. 단순 챗봇 하나를 만들려고 처음부터 도입할 필요는 없어요.
첫 번째 완성 기준을 너무 높게 잡지 않는 것도 중요해요. 질문 30개 가운데 30개 모두 완벽해야 공개한다는 목표보다 위험한 실패를 막고 주요 업무 성공률을 측정하는 게 현실적이에요. 잘못된 답변이 나왔을 때 다시 시도하거나 사람에게 넘기는 경로도 제품 품질의 일부예요. 실패하지 않는 AI보다 실패했을 때 안전하게 멈추는 AI가 실제 운영에는 더 유용할 수 있어요.
개발 난이도별 추천 구조
| 단계 | 구조 | 권장 도구 수 | 어울리는 프로젝트 |
|---|---|---|---|
| 입문 | 단일 에이전트 | 1~3개 | 검색·요약·FAQ |
| 중급 | 에이전트+세션 | 3~6개 | 고객지원·개인비서 |
| 확장 | 그래프 워크플로 | 5개 이상 | 장기 업무·승인 흐름 |
| 고급 | 멀티 에이전트 | 역할별 분리 | 복합 조사·전문 업무 |
코드가 복잡해졌다면 그래프로 흐름을 나눌 때가 있어요
상태 기반 에이전트 구조를 공식 문서에서 확인해 보세요
장기 작업과 사람 승인 흐름이 필요하면 그래프 구조가 편할 수 있어요
LangGraph 공식 문서에서 State, Node, 실행 흐름의 개념을 볼 수 있어요.
LangGraph 공식 문서 보기배포할 때 비용과 안전장치는 어떻게 잡을까
로컬에서 잘 움직이던 에이전트를 서비스로 공개하면 신경 쓸 부분이 확 늘어요. 동시에 여러 사용자가 접속하고 예상하지 못한 입력이 들어오며 외부 API가 잠시 멈추기도 하죠. 모델 품질만 보는 단계에서 시스템 안정성을 보는 단계로 바뀌는 거예요. 운영 준비는 에이전트의 기능을 더 붙이는 일과는 성격이 달라요.
가장 먼저 호출 제한을 두는 게 좋아요. 사용자 한 명이 반복 요청을 보내거나 에이전트가 루프에 빠졌을 때 모델 비용이 급격하게 늘 수 있거든요. 요청별 최대 모델 호출 수와 최대 도구 호출 수, 실행 시간을 정해둘 수 있어요. 제한에 걸리면 안전하게 중단하고 사용자에게 재시도를 요청하면 돼요.
비용은 모델 호출과 외부 도구 호출을 따로 측정하는 편이 좋아요. 월 서버비 3만원만 잡아도 모델 사용료가 20만원이고 검색 API가 10만원이면 실제 운영비는 33만원이 되잖아요. 사용자별 평균 비용까지 계산하면 유료 서비스의 가격을 정할 때도 도움이 돼요. 트래픽이 늘기 전에 단가를 알아두는 게 꽤 중요해요.
캐시를 잘 쓰면 반복 비용을 줄일 수 있어요. 같은 뉴스 검색을 몇 초 간격으로 여러 사용자가 요청한다면 매번 외부 API를 호출할 필요가 없는 경우도 있어요. 데이터 성격에 맞춰 1분이나 10분처럼 유효기간을 정해 재사용할 수 있죠. 실시간성이 필요한 금융 거래처럼 캐시가 맞지 않는 영역도 있으니 업무 특성을 봐야 해요.
권한은 읽기와 쓰기를 확실하게 나누는 게 좋아요. 검색과 조회는 상대적으로 위험이 낮지만 계정 삭제와 송금, 게시물 공개 같은 행동은 결과를 되돌리기 어려울 수 있어요. 사람이 승인해야 실행되도록 별도 단계를 넣으면 사고 가능성을 줄일 수 있죠. 좀 번거로워 보여도 실제 서비스에서는 이런 마찰이 보호장치가 돼요.
입력과 출력 검증도 필요해요. 사용자가 도구 호출 규칙을 무시하라는 문장을 넣거나 외부 문서 안에 에이전트 지시문처럼 보이는 텍스트가 있을 수 있거든요. 모델이 읽는 데이터와 개발자가 정의한 지시를 구분하도록 설계하고 위험한 행동은 코드 레벨에서 제한해야 해요. 프롬프트 하나만으로 모든 공격을 막으려는 접근은 부담이 커요.
OpenAI Agents SDK에는 guardrails와 tracing 같은 기능이 포함돼 있어요. 공식 문서 기준으로 입력과 출력 검증을 구성하고 실행 흐름을 추적할 수 있는 구조가 제공되고 있죠. 에이전트가 어느 도구를 불렀고 어디에서 실패했는지 기록하는 건 운영 중 상당히 유용해요. 오류가 난 뒤 원인을 찾지 못하는 상황이 제일 답답하거든요.
개인정보가 들어오는 서비스라면 저장 정책도 미리 정해야 해요. 어떤 데이터를 저장하는지, 보관 기간은 얼마인지, 누가 접근할 수 있는지 문서화할 필요가 있죠. 실제 적용되는 개인정보 법규와 산업 규칙은 국가와 서비스 성격에 따라 달라질 수 있어요. 법적 영향이 큰 분야라면 관련 전문가의 검토가 필요할 수 있어요.
서비스 성공률도 측정해야 해요. '좋은 답변처럼 보였다'보다 작업 완료율, 도구 오류율, 평균 실행 시간, 사람에게 넘긴 비율처럼 숫자로 보는 게 낫죠. 예를 들어 100건 중 92건을 자동 처리하고 8건을 사람에게 넘겼다면 개선 방향이 훨씬 또렷해져요. 이런 운영 지표를 처음부터 남겨본 적 있어요?
배포 환경은 작은 API 서버 하나로 시작할 수 있어요. FastAPI나 Node.js 서버에서 사용자 요청을 받고 에이전트를 실행해 결과를 반환하는 구조면 기본 서비스가 만들어져요. 작업 시간이 길다면 큐와 비동기 실행 구조가 필요해질 수 있죠. 트래픽이 생긴 뒤 실제 병목을 보고 확장하는 편이 비용을 줄이기 좋아요.
운영 중에는 모델이나 SDK 버전이 바뀔 가능성도 고려해야 해요. 모델 이름을 코드 곳곳에 직접 적기보다 환경설정 한 곳에서 바꿀 수 있도록 만드는 편이 편하죠. 새 모델을 적용하기 전에 기존 테스트 세트를 다시 돌려 행동 변화를 확인할 수 있어요. AI 서비스도 일반 소프트웨어처럼 변경 관리가 필요한 거예요.
운영 전에 확인할 핵심 지표
| 지표 | 확인 이유 | 초기 예시 기준 |
|---|---|---|
| 작업 완료율 | 실제 업무 성공 여부 | 100건 단위 측정 |
| 평균 도구 호출 | 불필요한 반복 확인 | 요청당 1~5회부터 확인 |
| 실행 시간 | 사용자 체감 속도 | 업무별 별도 측정 |
| 요청당 비용 | 운영비 예측 | 모델·API 각각 기록 |
| 사람 승인 비율 | 자동화 범위 판단 | 위험 작업은 승인 유지 |
💡 첫 배포에서는 로그 화면 하나를 꼭 만들어두는 게 좋아요. 사용자 입력 전체를 무조건 저장하라는 뜻이 아니라 요청 ID와 사용한 도구, 처리시간, 오류 코드처럼 문제를 추적할 수 있는 정보를 남기는 방식이에요. 실패율이 갑자기 늘었을 때 원인을 찾는 시간이 크게 줄어요. 민감 데이터는 로그에서 제거하거나 마스킹하는 편이 안전해요.
에이전트는 만들기보다 운영에서 차이가 벌어져요
도구 호출과 실행 흐름을 추적할 방법을 준비해 두세요
Runner와 실행 루프를 이해하면 비용과 오류를 관리하기 쉬워져요
OpenAI 공식 Running agents 문서에서 실행 흐름과 턴 제한 방식을 확인할 수 있어요.
실행 구조 확인하기처음 시작한다면 이 순서가 가장 편해요
완전 입문자라면 에이전트를 공부하는 순서를 단순하게 잡는 게 좋아요. Python 기본 문법을 익히고 API 호출 방식을 이해한 뒤 모델 API를 한 번 호출해 보는 정도면 출발할 수 있어요. 그 후 함수 도구 하나를 붙이면 에이전트의 핵심 구조를 몸으로 이해하게 되죠. 이 단계에서 이미 작은 자동화 프로그램을 만들 수 있어요.
처음 프로젝트는 계산기 에이전트도 괜찮아요. 사용자가 계산을 요청하면 모델이 직접 암산하지 않고 계산 함수를 호출하게 만드는 거죠. 구조는 단순하지만 도구 선택과 함수 입력, 실행 결과 반환 과정을 전부 경험할 수 있어요. 성공하면 검색 API나 사내 데이터 조회로 확장하기 쉬워져요.
그다음에는 실제로 내가 반복하는 업무 하나를 골라보세요. 매일 뉴스를 찾고 세 줄로 요약한다거나 여러 상품의 가격을 표로 만드는 일도 괜찮아요. 반복 빈도가 높은 업무일수록 에이전트의 가치가 눈에 잘 보여요. 일주일에 30분만 절약해도 한 달이면 2시간 정도가 되잖아요.
검색 에이전트가 안정되면 세션을 붙여볼 수 있어요. 사용자가 앞서 말한 조건을 기억하고 다음 요청에 활용하도록 만드는 거죠. 예를 들어 '예산은 50만원'이라고 말한 뒤 다음 대화에서 제품을 추천할 때 같은 조건을 사용할 수 있어요. 이때부터 단순 도구 호출보다 서비스다운 느낌이 강해져요.
그 후에 사람 승인을 붙여보면 좋아요. 에이전트가 이메일 초안을 만들되 실제 발송은 사용자가 승인한 뒤 실행하도록 설계할 수 있어요. AI가 실수해도 행동이 바로 외부로 전달되지 않기 때문에 훨씬 안전하죠. 자동화와 통제 사이의 균형을 경험하기 좋은 단계예요.
프레임워크는 프로젝트 요구에 맞춰 고르면 돼요. OpenAI 모델과 도구 중심으로 빠르게 시작한다면 Agents SDK가 간결한 선택이 될 수 있고 상태가 긴 그래프형 업무는 LangGraph 같은 도구를 검토할 수 있어요. 외부 시스템과 표준화된 연결을 늘리고 싶다면 MCP를 함께 볼 수 있죠. 이름보다 내가 해결하려는 업무가 먼저예요.
노코드 자동화 도구를 활용하는 방법도 있어요. API와 웹훅 개념을 익히면 코드를 많이 쓰지 않고도 AI 호출과 업무 도구를 연결할 수 있죠. 다만 복잡한 조건과 세밀한 권한 제어가 필요해지면 코드 기반 개발이 편해지는 순간이 와요. 시작 방법은 달라도 기본 원리는 모델, 도구, 상태, 실행 흐름으로 비슷해요.
공부할 때 유튜브 영상만 계속 보는 것보다 작은 프로그램 하나를 끝내는 편이 기억에 오래 남아요. 오류가 나고 API 키가 안 읽히고 도구 호출이 예상대로 되지 않는 과정에서 구조를 이해하게 되거든요. 나도 처음에는 문서만 읽을 때보다 직접 실패한 뒤 개념이 훨씬 또렷해졌어요. 작은 실패가 오히려 빠른 학습이 되는 경우가 있어요.
처음 한 달 계획을 잡는다면 1주차에는 API 호출, 2주차에는 함수 도구, 3주차에는 메모리와 데이터베이스, 4주차에는 간단한 웹 서비스 배포 정도로 잡아볼 수 있어요. 하루 1시간만 잡아도 한 달 약 30시간을 투자하는 셈이에요. 개인차는 크지만 최소 하나의 작동하는 프로젝트를 목표로 삼으면 방향을 잃기 덜해요. 공부만 오래 하고 배포를 미루는 패턴을 피하기도 좋죠.
결국 AI 에이전트 만드는 법은 모델을 직접 학습시키는 기술보다 프로그램의 흐름을 설계하는 기술에 가까워요. 목표를 좁히고 필요한 도구를 연결하고 결과를 검증한 뒤 실패하면 안전하게 멈추도록 만드는 과정이 핵심이에요. 하나가 제대로 돌아가면 그때 검색과 메모리, 여러 전문 에이전트를 붙이면 돼요. 처음 한 개를 작게 완성해 보는 게 가장 빠른 출발이에요.
첫 프로젝트는 작을수록 완성 가능성이 높아요
에이전트 하나와 도구 하나부터 직접 실행해 보세요
자주 묻는 질문
Q1. AI 에이전트를 만들려면 코딩을 꼭 해야 하나요?
A1. 코딩 없이도 간단한 에이전트형 자동화를 만들 수 있지만 복잡한 도구 연결과 권한 제어에는 코딩이 유리해요. Python 기본 문법과 API 호출 정도를 익히면 입문용 프로젝트를 시작할 수 있어요.
Q2. 챗GPT와 AI 에이전트의 가장 큰 차이는 뭔가요?
A2. AI 에이전트는 답변 생성뿐 아니라 필요한 도구를 선택하고 여러 단계를 반복 실행할 수 있다는 점이 핵심이에요. 검색, 데이터베이스 조회, API 호출 같은 행동을 목표 달성 과정에 포함할 수 있어요.
Q3. 초보자가 사용하기 쉬운 언어는 뭔가요?
A3. Python이 입문용으로 많이 쓰이고 관련 AI 라이브러리와 예제가 풍부한 편이에요. 웹 개발 경험이 있다면 TypeScript 기반 Agents SDK를 선택해도 괜찮아요.
Q4. OpenAI Agents SDK와 LangGraph 중 무엇을 써야 하나요?
A4. 작은 단일 에이전트를 빠르게 만들고 싶다면 Agents SDK처럼 추상화가 간결한 도구가 편할 수 있어요. 상태가 오래 유지되고 분기와 승인 단계가 많은 작업은 그래프 기반 구조를 검토할 만해요.
Q5. MCP는 꼭 배워야 하나요?
A5. 작은 프로젝트를 만드는 데 MCP가 필수는 아니에요. 여러 외부 시스템과 AI 애플리케이션이 같은 도구와 데이터를 공유해야 할 때 표준화된 연결 방식이 유용해질 수 있어요.
Q6. AI 에이전트 제작 비용은 얼마나 들어가나요?
A6. 비용은 모델 사용량과 검색 API, 데이터베이스, 서버 규모에 따라 크게 달라져요. 개인 테스트는 로컬 환경에서 시작하고 요청당 모델 호출 횟수와 외부 API 비용을 기록하면서 예상 운영비를 계산하는 방식이 좋아요.
Q7. AI 에이전트가 알아서 인터넷 검색도 할 수 있나요?
A7. 검색 기능을 도구로 연결하면 에이전트가 필요하다고 판단한 순간 검색을 실행하도록 만들 수 있어요. 검색 권한이나 API를 연결하지 않은 모델이 자동으로 모든 인터넷 정보를 확인한다고 가정하면 안 돼요.
Q8. 여러 AI 에이전트를 연결하면 더 좋아지나요?
A8. 역할이 명확하게 나뉠 때는 멀티 에이전트가 유용할 수 있지만 무조건 품질이 높아지는 건 아니에요. 호출 횟수와 비용, 오류 지점이 늘어나므로 단일 에이전트로 해결하기 어려운 이유가 생겼을 때 확장하는 편이 좋아요.
Q9. 가장 먼저 만들어볼 만한 AI 에이전트는 뭔가요?
A9. 계산기, 문서 검색, 뉴스 조사, 상품 정보 조회처럼 도구가 1~3개인 프로젝트가 입문용으로 좋아요. 목표와 완료 조건을 명확하게 정할 수 있어 디버깅도 비교적 쉬운 편이에요.
Q10. AI 에이전트를 실제 서비스에 바로 써도 괜찮나요?
A10. 실제 서비스에서는 테스트와 권한 제한, 로그, 호출 횟수 제한, 사람 승인 같은 안전장치를 먼저 마련하는 게 좋아요. 결제와 삭제, 의료·법률·금융처럼 영향이 큰 행동은 특히 자동 실행 범위를 신중하게 정해야 해요.