DeepSeek로 나의 첫 실제 AI Agent를 만든 방법 — 부트캠프 졸업생을 위한 가이드

자, 이런 일이 일어났습니다: DeepSeek로 나의 첫 실제 AI Agent를 만든 방법 — 2026년을 위한 부트캠프 졸업생 가이드

처음 AI Agent에 대해 들었을 때, 제가 무엇에 뛰어들게 될지 전혀 몰랐습니다. 진심으로, 6개월 전만 해도 저는 ChatGPT가 그저... 질문에 답하는 것이라고 생각했습니다. 그게 전부였죠. 프롬프트(Prompt) 하나를 넣으면, 응답 하나가 나오고, 끝나는 것 말입니다. 그러다 제 부트캠프의 누군가가 AI가 스스로 항공권을 예약하고, 캘린더를 확인하고, 이메일을 보내는 데모를 보여주었습니다. 저는 충격을 받았습니다. LLM(대규모 언어 모델)이 할 수 있는 일에 대한 저의 모든 정신적 모델이 산산조각 났습니다.

그래서 저는 깊이 파고들기 시작했습니다. 블로그 포스트를 읽고, 너무 많은 YouTube 튜토리얼을 시청했습니다. 그리고 마침내 Global API를 통해 DeepSeek의 모델들을 사용하여 저만의 작동하는 Agent를 구축했습니다. 이것은 저처럼 아직 이 분야를 파악해 나가고 있는 사람들을 위해 작성된, 제가 그 과정에서 배운 모든 것입니다.

잠깐, AI Agent란 대체 무엇인가요?

좋습니다, 제가 설명할 수 있는 가장 간단한 방법은 이렇습니다: 일반적인 챗봇(Chatbot)은 아주 똑똑한 친구에게 단 하나의 질문을 던지는 것과 같습니다. 반면 AI Agent는 그 친구에게 목표를 주고, 그 목표를 단계별로 어떻게 달성할지 스스로 알아내는 과정을 지켜보는 것과 같습니다.

제가 마침내 이해하게 된 비교는 다음과 같습니다:

일반 챗봇	AI Agent
질문 하나를 하면, 답변 하나를 받음	목표를 주면, 그곳에 도달하기 위한 여러 단계를 계획함
...

제 정신을 혼미하게 만들었던 실제 사례: 단순히 "지금 베이징 날씨가 어때요?"라고 묻고 텍스트 답변을 받는 대신, Agent는 실제로 날씨 API를 호출해야 한다는 것을 파악하고, 호출을 수행하고, 응답을 읽은 다음, 그 데이터를 사람이 실제로 듣고 싶어 하는 정보로 변환합니다.

DeepSeek의 모델들 — 구체적으로 deepseek-v4-flash와 deepseek-reasoner — 는 함수 호출 (Function Calling)이라고 불리는 것을 통해 이러한 작업들을 기본적으로 처리합니다. 이것이 바로 핵심 비결(Secret Sauce)입니다.

설정하기 (제가 항상 건너뛰고 나서 후회하는 부분)

멋진 것을 만들기 전에, API 키가 필요합니다. 저는 Global API에서 제 키를 가져왔습니다. 그냥 32자리의 16진수 문자열일 뿐이며, 특별할 건 없습니다. 만약 제 코드를 따라 해보시려면, 여러분도 키가 필요할 것입니다.

Python 사용자라면:

pip install openai httpx

그리고 이것은 제가 현재 말 그대로 모든 것에 사용하는 기본적인 클라이언트 설정입니다:

from openai import OpenAI

# 이것을 Global API의 프록시 엔드포인트로 지정하세요
...

만약 JavaScript 사용자에 더 가깝다면, Node에서의 동일한 설정은 다음과 같습니다:

// my_first_agent/client.js
import OpenAI from 'openai';

...

솔직히 말해서, 이 부분만으로도 저는 몇 시간의 디버깅 시간을 아꼈습니다. Global API의 베이스 URL (base URL)을 사용하면 지역적 라우팅 (regional routing)이나 이상한 인증 문제 (authentication quirks)를 걱정할 필요가 없습니다. 그냥 작동하니까요.

함수 호출 (Function Calling): 진짜 마법 같은 부분

이 부분은 제가 화면을 뚫어지게 쳐다보며 "잠깐, 얘가 어떻게 그걸 하는지 아는 거지?"라고 생각하며 가장 많은 시간을 보낸 지점입니다. 함수 호출 (Function calling)은 기본적으로 모델이 단순히 텍스트를 내뱉는 대신, "이봐, 이 특정 인자 (arguments)들을 가지고 이 특정 함수를 실행해 줬으면 좋겠어"라고 말하는 방식입니다.

쉬운 영어로 설명한 흐름은 다음과 같습니다:

1. 사용자가 "지금 비트코인 가격이 얼마야?"와 같은 질문을 합니다.
2. 모델은 사용 가능한 도구 (tools)들을 살펴보고 "get_bitcoin_price 도구가 필요해"라고 결정합니다.
3. 모델은 정확히 어떤 도구를 호출해야 하는지, 그리고 무엇을 전달해야 하는지를 명시하는 구조화된 JSON 응답을 반환합니다.
4. 여러분의 코드가 해당 도구(아마도 API 호출일 것입니다)를 실행합니다.
5. 여러분은 그 결과를 모델에게 다시 전달합니다.
6. 모델은 그 가공되지 않은 데이터 (raw data)를 인간이 이해하기 쉬운 답변으로 변환합니다.

이것이 작동하는 것을 처음 봤을 때, 저는 실제로 "와"라고 소리 내어 말했습니다. 그러니까, 모델이 단순히 가격을 환각 (hallucinating) 하는 것이 아니라, 제 코드에 실제 가격을 가져오라고 요청하고 있었던 것입니다. 그것이 챗봇 (chatbot)과 에이전트 (agent)의 차이점입니다.

에이전트를 루프 (Loop) 내에서 실행하기

자, 이제 상황이 흥미진진해지는 부분입니다. 에이전트의 진정한 힘은 단일 함수 호출이 아니라, 그것들을 서로 연결(chaining)하는 데 있습니다. 모델은 다음과 같은 능력을 갖춰야 합니다:

• 지금까지의 대화 내용을 살펴보기
• 추가 정보가 필요한지 결정하기
• 필요하다면 적절한 도구(tool) 선택하기
• 결과 평가하기
• 원래 목표가 해결될 때까지 계속하기

이것이 사람들이 흔히 말하는 "에이전트 루프 (agent loop)"이며, 솔직히 말해서 이를 처음부터 직접 작성했을 때 마치 마법사가 된 것 같은 기분이 들었습니다. 수많은 시행착오 끝에 제가 완성한 Python 버전은 다음과 같습니다:

# my_first_agent/agent_loop.py
from openai import OpenAI
import json
...

제가 파악하는 데 영원히 걸렸던 사실이 무엇인지 아십니까? 도구(tool)의 결과값을 일치하는 tool_call_id와 함께 tool 역할(role) 메시지로 모델에 다시 전달해야 한다는 점입니다. 이를 놓치면 아무것도 작동하지 않고 난해한 에러가 발생합니다. 저는 이 문제 때문에 토요일 하루를 통째로 날렸습니다.

아무도 경고해주지 않은 비용 문제

자, 솔직히 말씀드릴게요. 가격 책정을 파악하기 전까지 부트캠프 크레딧을 너무 많이 써버렸습니다. 그러니 여러분은 번거로운 일을 겪지 않도록 제가 미리 알려드리겠습니다.

DeepSeek 모델들의 상황은 다음과 같습니다 (네, 이것은 Global API의 실제 수치입니다):

• deepseek-v4-flash는 저렴한 모델입니다. 정말 저렴합니다. 입력 토큰 100만 개당 약 $0.14, 출력 토큰 100만 개당 약 $0.28 수준입니다.
• deepseek-reasoner는 더 똑똑한 모델입니다. 답변하기 전에 실제로 생각을 하는데, 이를 지켜보는 것은 정말 놀랍습니다. 하지만 비용은 더 높습니다. 입력 토큰 100만 개당 약 $0.55, 출력 토큰 100만 개당 약 $2.19 정도입니다.

첫 번째 에이전트를 실행하고 비용을 계산했을 때 저는 충격을 받았습니다. deepseek-reasoner를 약 20번 사용한 복잡한 다단계 작업의 비용이 커피 한 잔 값보다 적게 들었습니다. 단 몇 센트 수준이었죠. 입력 100만 개당 $5.00, 출력 100만 개당 $10.00인 GPT-4o와 비교해 보면 제가 왜 사실상 다른 것은 사용하지 않게 되었는지 이해하실 겁니다.

하지만 중요한 점은 항상 똑똑한 모델이 필요한 것은 아니라는 것입니다. 단순한 도구 호출(tool calls)이나 라우팅 결정에는 deepseek-v4-flash로도 충분히 훌륭하며 훨씬 저렴합니다. 저의 현재 패턴은 이렇습니다: 루프 로직에는 저렴한 모델을 사용하고, 어려운 문제를 다룰 때만 reasoner로 격상(escalate)시키는 것입니다.

Global API의 라우팅(Routing)이 중요한 이유 (내가 시작할 때 있었으면 좋았을 섹션)

Global API가 수행하는 기능 중 제가 처음에는 제대로 인식하지 못했던 것 중 하나가 바로 "GA Fusion 라우팅 (GA Fusion routing)"입니다. 이름만 들으면 마케팅용 헛소리처럼 들릴 수도 있다는 것을 압니다. 하지만 이것이 해커톤(hackathon) 동안 저를 위기에서 구해냈습니다.

기본적으로, Global API의 엔드포인트(endpoint)를 통해 요청을 보내면, DeepSeek의 서버에 도달할 수 있는 가장 빠르고 저렴한 경로를 찾아냅니다. 때로는 서로 다른 리전(region)을 통해 라우팅하거나, 동일한 쿼리가 최근에 요청된 경우 캐시된 응답(cached responses)을 사용하는 것을 의미합니다.

실제로는 다음과 같은 효과가 있습니다:

• DeepSeek의 서버 상태가 좋지 않을 때 타임아웃 (timeout) 발생 감소
• 평소라면 2초를 기다려야 했을 상황에서 때로는 200ms 미만으로 응답을 받음
• 동일한 요청에 대해 항상 전체 추론 (inference) 비용을 지불하지 않아도 되므로 비용 절감

저는 100개의 동시 요청으로 제 에이전트(agent)를 스트레스 테스트 (stress-testing)할 때 이를 체감했습니다. 제 친구들의 설정 절반은 과부하로 멈췄지만, 제 것은 멀쩡했습니다. 그것만으로도 충분했습니다.

실제로 유용한 기능을 수행하는 실제 사례

제가 부트캠프(bootcamp) 최종 프로젝트로 만든 것을 보여드리겠습니다. 이것은 주제를 입력받아 검색하고, 찾은 내용을 요약하며, 짧은 보고서를 작성하는 리서치 에이전트 (research agent)입니다. 이 에이전트는 검색 기능과 노트 작성 기능이라는 두 가지 도구(tool)를 사용합니다.

# research_agent/agent.py
from openai import OpenAI
import json
...

이것이 작동하는 모습을 지켜보는 것은 진심으로 매혹적입니다. 모델이 검색을 하고, 사실을 저장하고, 더 구체적인 쿼리로 다시 검색하고, 또 다른 사실을 저장하며, 충분한 자료가 모일 때까지 과정을 반복합니다. 마치 누군가가 실제로 연구를 수행하는 것을 지켜보는 것 같은 기분이 듭니다.

여러분이 겪지 않도록 제가 저지른 실수들

이 글은 제가 누군가에게 들었으면 좋았을 내용들을 다루는 것이므로, 저를 괴롭혔던 일들을 빠르게 나열해 보겠습니다:

1. 대화 기록 (conversation history)에 어시스턴트 메시지 (assistant message)를 추가하는 것을 잊는 것. 모델은 자신이 마지막으로 무엇을 말했는지 확인해야 하며, 그렇지 않으면 혼란을 겪습니다.

2. 실제로 "required"를 의도했을 때 tool_choice="auto"를 사용하는 것. "auto"는 모델이 도구 (tool)를 사용할지 여부를 스스로 결정하게 합니다. 때로는 도구 사용을 강제해야 할 때가 있습니다.

3. 최대 단계 제한 (max step limit)을 설정하지 않는 것. 제한이 없으면 혼란에 빠진 에이전트 (agent)가 무한 루프에 빠져 비용을 계속 발생시킬 수 있습니다. 항상 제한을 두어야 합니다.

4. tool_call_id를 혼동하는 것. 모든 도구 호출 (tool call)은 고유한 ID를 가지며, 응답 시 올바른 ID를 사용해야 합니다. 불일치가 발생하면 침묵 속에서 실패 (silent failure)하게 됩니다.

5. 함수 호출 (function calling) API를 제대로 사용하는 대신, 일반 텍스트 응답에서 JSON을 파싱하려고 시도하는 것. 그러지 마세요. 구조화된 도구 (structured tools)를 사용하세요.

더 깊이 파고들고 싶다면 다음에 할 일

기본적인 에이전트 루프 (agent loop)가 작동하기 시작하면, 세상이 열리는 기분이 들 것입니다. 제가 현재 탐구하고 있는 것들은 다음과 같습니다:

• 한 에이전트가 다른 에이전트에게 업무를 위임하는 멀티 에이전트 시스템 (Multi-agent systems)
• 대화 전반에 걸쳐 유지되는 메모리 레이어 (Memory layers)
• 사용자가 에이전트가 완료될 때까지 기다리지 않도록 하는 스트리밍 응답 (Streaming responses)
• 에이전트가 위험한 도구를 호출하는 것을 방지하는 안전 가드레일 (Safety guardrails)

하지만 솔직히 말씀드리면, 여러분이 몇 달 전의 저와 같은 단계에 있다면 — 일단 하나의 도구, 하나의 루프, 하나의 목표로 시작하세요. 그것부터 작동하게 만드세요. 그다음 복잡성을 추가하는 겁니다. 그것이 제가 배운 방식이며, 제가 아는 다른 모든 부트캠프 졸업생들이 배운 방식이기도 합니다.

마치며

보세요, 제가 지금 AI 전문가인 척하지는 않겠습니다. 저는 전문가가 아닙니다. 하지만 저는 "LLM이 뭐지?"라는 상태에서 "나를 대신해 조사를 수행하는 에이전트를 만들었다"라는 상태까지 약 6주 만에 도달했습니다. 도구들은 이미 준비되어 있습니다. 가격은 믿기지 않을 정도로 저렴합니다 (특히 Global API를 이용한다면요). 여러분과 작동하는 에이전트 사이를 가로막는 유일한 장애물은 실제로 자리에 앉아 코드를 작성하는 것뿐입니다.

만약 여러분이 직접 이것을 가지고 놀아보고 싶다면, 저는 Global API를 사용했으며 이를 확인해 보시길 추천합니다. 가입 절차가 매우 간단하고, DeepSeek 모델들이 별도의 설정 없이 바로 작동하며, 그들의 라우팅 (routing) 설정 덕분에 신뢰성 (reliability)에 대해 걱정할 필요가 없습니다. 그게 전부입니다. 이것이 핵심입니다. 가서 뭔가 기발한 것을 만들어 보세요.