agent 강의 다 봤는데 실행이 안 된다고요? Key 하나로 예제를 돌려보세요

X에 이런 글을 올린 사람이 있습니다: AI Agent 강의에 500달러를 쓴 사람들은 이제 무료로 볼 수 있다고요. 원글: https://x.com/deanwperkins/status/2116911546282733623 (작성자 Dean W. Perkins, @deanwperkins). 아래 논의의 공통된 의견은 강의 자체는 희귀하지 않고, 희귀한 것은 강의 내용을 실제로 실행하는 일이라는 것입니다.

정확한 지적입니다. 대부분이 막히는 지점은 agent 루프를 이해하지 못하는 것이 아니라 첫 단계부터 움직이지 못하는 것입니다: 예제 코드가 쓰는 모델 Key가 없고, 다른 모델로 바꾸면 프로토콜이 맞지 않아 실행이 안 되니 검증할 방법도 없습니다.

이 글은 최소 실행 구성에 대해 다루며, agent 이론은 다루지 않습니다.

최소 agent는 세 가지뿐

프레임워크와 추상화를 걷어내면, 실제로 일하는 agent는 세 가지 컴포넌트입니다:

1. 도구를 호출할 수 있는 모델
2. 도구 정의 세트 (이름, 파라미터, 설명)
3. 루프: 모델이 어떤 도구를 호출할지 결정하고, 당신이 실행해서 결과를 모델에 돌려주고, 모델이 끝났다고 말할 때까지 반복

강의에서 다루는 멀티 에이전트, 메모리, 계획은 모두 이 세 가지 위에 무언가를 더한 것입니다. 먼저 이 세 가지를 실행해 보세요.

1단계: Key 준비하기

대부분 강의의 첫 과제는 '어떤 모델의 API Key를 신청하라'입니다. 이 단계의 이탈률이 낮지 않습니다: 가입, 카드 등록, 심사 대기, 어떤 곳은 한도 신청까지 필요합니다.

통합 진입점을 쓰면 이 과정을 건너뛸 수 있습니다. HiAPI의 Key는 하나의 인증으로 Claude, GPT, Kimi, Grok, DeepSeek 등 텍스트 모델을 커버하며, 표준 Chat Completions 프로토콜을 따릅니다.

Key를 받은 후 먼저 연결이 되는지 확인하세요:

curl -s https://api.hiapi.ai/v1/chat/completions \
  -H "Authorization: Bearer YOUR_HIAPI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-6.1-sol",
    "messages": [{"role": "user", "content": "한마디 인사해 줘"}]
  }'

내용이 반환되면 Key는 문제없습니다.

2단계: 도구 정의하기

도구 정의는 모델에게 주는 설명서입니다. 어떤 도구가 있고, 각 도구에 어떤 파라미터가 필요한지 알아야 합니다.

tools = [{
    "type": "function",
    "function": {
        "name": "get_weather",
        "description": "지정한 도시의 현재 날씨 조회",
        "parameters": {
            "type": "object",
            "properties": {
                "city": {"type": "string", "description": "도시 이름, 예: 베이징"}
            },
            "required": ["city"]
        }
    }
}]

작성할 설명은 한 줄입니다: 모델은 description을 보고 언제 이 도구를 써야 할지 판단합니다. 더 명확하게 쓸수록 잘못 호출할 확률이 낮아집니다.

3단계: 루프 작성하기

import json, requests

API = "https://api.hiapi.ai/v1/chat/completions"
KEY = "YOUR_HIAPI_API_KEY"
HEADERS = {"Authorization": f"Bearer {KEY}", "Content-Type": "application/json"}

def run_weather(city):
    return {"city": city, "temp": 18, "condition": "맑음"}  # 예시 구현

messages = [{"role": "user", "content": "베이징 오늘 몇 도야?"}]

for _ in range(5):  # 무한 루프 방지
    resp = requests.post(API, headers=HEADERS, json={
        "model": "gpt-6.1-sol",
        "messages": messages,
        "tools": tools,
    }).json()

    msg = resp["choices"][0]["message"]
    messages.append(msg)

    if not msg.get("tool_calls"):
        print(msg["content"])
        break

    for call in msg["tool_calls"]:
        args = json.loads(call["function"]["arguments"])
        result = run_weather(args["city"])
        messages.append({
            "role": "tool",
            "tool_call_id": call["id"],
            "content": json.dumps(result, ensure_ascii=False),
        })

이 코드를 실행하면 모델이 먼저 get_weather를 호출하기로 결정하고, 결과를 받은 뒤 한 문장으로 답변을 구성하는 것을 볼 수 있습니다. 이것이 완전한 agent 루프입니다.

모델 선택 방법

같은 루프에서 model 필드만 바꾸면 모델을 교체할 수 있습니다. 비용 차이가 큽니다:

모델	입력	출력	적합
GPT-6 Luna	$0.025	$0.125	단순 도구 호출, 분류, 추출
GPT-6.1 Terra	$0.25	$1.25	일상 agent, 코드 작업
GPT-6.1 Sol	$0.50	$2.50	복잡한 다단계 작업
Claude Opus 5.5	$2.02	$10.08	긴 작업, 깊은 추론 필요

단일 도구 호출 루프는 대략 수천 token이며, 가장 저렴한 Luna 기준으로 한 번에 1리도 안 됩니다. 강의 실험용으로는 비용이 무시할 수준입니다.

강의에서 특정 모델을 지정했다면 강의대로 쓰고, 지정이 없거나 쓸 수 없다면 같은 등급의 대체 모델을 써도 학습 효과에는 영향이 없습니다. 루프 로직은 동일하기 때문입니다.

강의에서 가장 막히기 쉬운 세 가지

도구 호출 반환 형식이 맞지 않음. 모델 제공사마다 tool_calls의 필드 구성에 차이가 있습니다. Chat Completions 호환 프로토콜을 쓰는 모델은 형식이 통일되어 있어 모델을 바꿔도 파싱 코드를 고칠 필요가 없습니다.

컨텍스트가 점점 길어짐. 매轮마다 전체 기록을 넣으면 서른 번째轮에서 한도에 도달합니다. 강의 후반부에서 잘라내기 전략을 다루지만, 초반에는 이 함정이 있다는 것만 알아두세요.

모델이 도구를 호출하지 않고 텍스트만 반환함. 보통 도구 설명이 너무 모호하거나, 프롬프트에 '사용 가능한 도구가 있다'는 점을 명확히 하지 않은 경우입니다. 설명을 구체적으로 바꾸거나 시스템 프롬프트에 명시하세요.

실행된 후 할 일

먼저 프레임워크를 서두르지 마세요.

최소 루프가 돌아간 후 다음을 순서대로 보완하세요:

1. 오류 처리 추가: 도구 실행 실패 시 오류 메시지를 모델에 돌려주고 재시도하거나 다른 경로를 선택하게 함
2. 사용량 통계 추가: 매 호출의 token 수를 기록해야 비용이 어디에 쓰이는지 알 수 있음
3. 타임아웃과 재시도 추가: 네트워크 흔들림은 일상
4. 그다음 프레임워크 고려: 작업이 멀티 에이전트나 복잡한 상태 머신을 필요로 할 만큼 복잡해지면 그때 프레임워크를 도입해도 늦지 않음

강의에서 가르치는 아키텍처는 보통 프로덕션을 지향하므로, 그대로 따라 만들면 첫 단계에서 막히기 쉽습니다. 먼저 세 컴포넌트를 돌리고 나머지는 필요에 따라 추가하세요.

자주 묻는 질문

특정 모델을 반드시 써야 하나요?

아니요. 도구 호출(function calling)을 지원하기만 하면 루프 로직은 공통입니다. 강의에서 지정한 모델을 쓸 수 없을 때 같은 가격대의 대체 모델을 써도 이해에는 영향이 없습니다.

무료 강의와 유료 강의의 차이는 무엇인가요?

X의 그 논의에 따르면 차이는 지식 자체보다 구조와 질의응답에 더 있습니다. 예제를 실행하는 일은 양쪽 모두 직접 해야 합니다.

도구가 실제 API를 호출할 수 있나요?

네. run_weather를 실제 HTTP 요청으로 바꾸면 됩니다. 도구 함수 내의 예외를 모두 잡아야 합니다. 그렇지 않으면 한 번의 실패로 전체 루프가 끊깁니다.

한 번 실행에 비용이 얼마인가요?

최소 예제는 수천 token이며, 가장 저렴한 모델은 한 번에 1리도 안 되고 비싼 모델도 몇 푼 수준입니다. 실험용으로는 비용 걱정이 없습니다.

핵심 결론

agent 강의의 걸림돌은 결코 이론이 아니라 첫 예제가 실행되지 않는다는 점입니다. 세 가지로 완전한 루프를 실행할 수 있습니다: 쓸 수 있는 Key 하나, 도구 정의 하나, 결과를 다시 먹이는 루프 하나. 실행된 후에 엔지니어링 세부 사항을 보완하는 것이 반대 순서보다 열 배 쉽습니다.

사용 가능한 텍스트 모델과 가격 보기

---

자료 출처

• 화제의 발단: Dean W. Perkins(@deanwperkins), https://x.com/deanwperkins/status/2116911546282733623
• 해당 글에는 구체적인 강의 링크가 없으며, 이 글은 특정 강의를 가리키지 않고 예제를 실행하는 일반적인 구성만 다룹니다
• 코드 예제와 가격 데이터는 본 사이트에서 정리한 것이며, 가격은 HiAPI 프로덕션 환경(2026-11-02)에서 가져왔습니다