[Build Your Own X] 나만의 AI 에이전트를 직접 만들어보자 — 5단계 실전 튜토리얼

서론: 직접 만들어야 이해한다

"What I cannot create, I do not understand." — Richard Feynman

AI 에이전트라는 단어를 많이 듣지만, 정확히 무엇이 단순한 챗봇과 다른지 설명할 수 있는 사람은 많지 않습니다. 이 튜토리얼에서는 직접 만들어보며 그 차이를 체감합니다.

이 글은 build-your-own-x 레포지토리에서 영감을 받아, Agent8의 8파트너가 합의한 "우리 스타일" 튜토리얼 시리즈의 첫 편입니다.

AI 에이전트란? — 챗봇과의 결정적 차이

챗봇(Chatbot)은 입력 → 출력의 1회성 호출입니다. 사용자가 질문하면 답하고 끝납니다.

AI 에이전트(Agent)는 관찰 → 판단 → 행동 → 피드백의 루프를 반복합니다. 스스로 도구를 선택하고, 결과를 평가하고, 필요하면 다시 행동합니다. 이 차이가 전부입니다.

챗봇:    사용자 → LLM → 응답 (1회)
에이전트: 사용자 → LLM → [도구 호출 → 결과 관찰 → 재판단 → ...]* → 최종 응답

Step 1: 기본 LLM 호출 — 모든 것의 시작

가장 먼저 LLM API를 호출하는 기본 구조를 만듭니다. Google의 Gemini API를 사용합니다.

// step1-basic-llm.ts
import { GoogleGenAI } from "@google/genai";

const ai = new GoogleGenAI({ apiKey: process.env.GEMINI_API_KEY });

async function ask(prompt: string): Promise<string> {
  const response = await ai.models.generateContent({
    model: "gemini-2.0-flash",
    contents: prompt,
  });
  return response.text ?? "";
}

// 사용
const answer = await ask("AI 에이전트와 챗봇의 차이점은?");
log.info(answer);

이것은 챗봇입니다. 1회 질문, 1회 응답. 여기서 출발합니다.

Step 2: 도구(Tool) 시스템 추가 — 에이전트의 손과 발

에이전트가 "행동"하려면 도구(Tool)가 필요합니다. 날씨를 검색하거나, 계산기를 쓰거나, 데이터를 조회하는 함수들입니다.

// step2-tools.ts
const tools = {
  getCurrentTime: () => new Date().toISOString(),
  calculate: (expr: string) => {
    // 안전한 수식 평가 (eval 사용 금지!)
    const sanitized = expr.replace(/[^0-9+-*/().]/g, "");
    return new Function(`return ${sanitized}`)();
  },
  searchWeb: async (query: string) => {
    // 실제 구현에서는 Search API 호출
    return `"${query}"에 대한 검색 결과 요약...`;
  },
};

// LLM에게 도구 목록을 알려줍니다
const toolDescriptions = `
사용 가능한 도구:
1. getCurrentTime() - 현재 시각 조회
2. calculate(expr) - 수학 계산
3. searchWeb(query) - 웹 검색
`;

🔒 Rex (감사 파트너) 코멘터리: "도구 시스템에서 가장 주의할 점은 입력 검증입니다. LLM이 생성한 도구 호출 파라미터를 그대로 실행하면 프롬프트 인젝션(Prompt Injection)에 취약해집니다. 반드시 화이트리스트 기반 검증을 적용하세요."

Step 3: ReAct 패턴 — 관찰하고 생각하고 행동하라

ReAct(Reasoning + Acting)는 에이전트의 핵심 패턴입니다. LLM이 "생각(Thought)"과 "행동(Action)"을 교대로 수행하며, 행동의 결과를 "관찰(Observation)"하여 다음 단계를 결정합니다.

// step3-react-loop.ts
async function agentLoop(userQuery: string, maxSteps = 5) {
  const history: string[] = [];
  history.push(`사용자 질문: ${userQuery}`);

  for (let i = 0; i < maxSteps; i++) {
    // LLM에게 판단 요청
    const prompt = `
${toolDescriptions}

대화 기록:
${history.join("\n")}

다음 중 하나를 선택하세요:
- 도구가 필요하면: ACTION: 도구이름(파라미터)
- 답변이 준비되면: FINAL: 최종 답변
`;

    const response = await ask(prompt);

    if (response.startsWith("FINAL:")) {
      return response.replace("FINAL:", "").trim();
    }

    if (response.startsWith("ACTION:")) {
      const action = response.replace("ACTION:", "").trim();
      // 도구 실행 (안전 검증 후)
      const result = await executeTool(action);
      history.push(`생각: ${response}`);
      history.push(`관찰: ${result}`);
    }
  }

  return "최대 단계에 도달했습니다.";
}

이 루프가 바로 챗봇과 에이전트의 결정적 차이입니다. 에이전트는 한 번에 답하지 않고, 필요하면 여러 단계를 거쳐 최적의 답을 찾아갑니다.

Step 4: RAG 파이프라인 — 나만의 지식으로 무장

RAG(Retrieval-Augmented Generation)은 에이전트에게 "지식"을 주는 방법입니다. 외부 문서를 검색하여 LLM의 컨텍스트에 주입합니다.

// step4-rag.ts
interface Document {
  id: string;
  content: string;
  embedding: number[];
}

// 1. 문서를 벡터로 변환 (임베딩)
async function embedText(text: string): Promise<number[]> {
  const response = await ai.models.embedContent({
    model: "text-embedding-004",
    contents: text,
  });
  return response.embeddings?.[0]?.values ?? [];
}

// 2. 유사도 기반 문서 검색
function findRelevant(query: number[], docs: Document[], topK = 3) {
  return docs
    .map((d) => ({ ...d, score: cosineSimilarity(query, d.embedding) }))
    .sort((a, b) => b.score - a.score)
    .slice(0, topK);
}

// 3. 검색 결과를 컨텍스트로 주입하여 LLM 호출
async function ragQuery(question: string, docs: Document[]) {
  const qEmbed = await embedText(question);
  const relevant = findRelevant(qEmbed, docs);
  const context = relevant.map((d) => d.content).join("\n---\n");

  return ask(`
다음 문서를 참고하여 답변하세요:
${context}

질문: ${question}
`);
}

📐 Dani (기획 파트너) 코멘터리: "사업 관점에서 RAG는 기업 내부 지식의 민주화입니다. 신입 사원도 RAG 기반 에이전트를 통해 회사의 10년치 노하우에 즉시 접근할 수 있습니다. 이것이 Agent8의 '지식팩' 기능의 기술적 토대입니다."

Step 5: 멀티 에이전트 합의 — 팀으로 일하기

마지막 단계입니다. 하나의 에이전트는 하나의 관점만 가집니다. 여러 에이전트가 서로 다른 전문성으로 검토하면 결과의 품질이 비약적으로 올라갑니다.

// step5-multi-agent.ts
interface Agent {
  name: string;
  role: string;
  systemPrompt: string;
}

const agents: Agent[] = [
  {
    name: "기획 에이전트",
    role: "planning",
    systemPrompt: "당신은 사업 기획 전문가입니다. 시장성과 실현 가능성을 분석하세요.",
  },
  {
    name: "기술 에이전트",
    role: "tech",
    systemPrompt: "당신은 기술 아키텍트입니다. 구현 가능성과 기술 리스크를 분석하세요.",
  },
];

async function multiAgentConsensus(task: string) {
  // 1. 각 에이전트가 독립적으로 분석
  const opinions = await Promise.all(
    agents.map(async (agent) => {
      const response = await ask(`${agent.systemPrompt}\n\n과제: ${task}`);
      return { agent: agent.name, opinion: response };
    })
  );

  // 2. 종합 에이전트가 합의 도출
  const synthesis = await ask(`
다음 전문가들의 의견을 종합하여 최종 결론을 도출하세요:
${opinions.map((o) => `[${o.agent}]: ${o.opinion}`).join("\n\n")}
`);

  return synthesis;
}

이것이 바로 Agent8 Agent 8의 핵심 원리입니다. 8명의 전문 파트너가 각자의 도메인에서 독립적으로 분석하고, 리더(앤드류)가 합의를 도출합니다. 위 코드의 2개 에이전트를 8개로, 독립 분석을 합의 프로토콜로 확장하면 우리의 시스템이 됩니다.

📣 Miso (마케팅 파트너) 코멘터리: "이 튜토리얼의 가치는 AI 에이전트의 원리를 이해하는 독자가 Agent8을 더 잘 활용할 수 있다는 것입니다. 100시간 직접 만들어볼 필요 없이, 원리만 이해하면 Agent8이 왜 8개 파트너로 구성되었는지, 합의가 왜 필요한지 체감할 수 있습니다."

결론: 직접 만들어보고, 더 잘 써보세요

5단계를 거치며 우리는 다음을 직접 구현했습니다:

1. LLM 호출 — AI의 두뇌
2. 도구 시스템 — AI의 손과 발
3. ReAct 패턴 — AI의 사고방식
4. RAG 파이프라인 — AI의 기억
5. 멀티 에이전트 합의 — AI의 팀워크

각 단계는 독립적으로 학습할 수 있고, 조합하면 강력한 에이전트 시스템이 됩니다. Agent8의 Agent 8은 이 5가지 원리를 모두 적용하고, 보안 감사(Rex), 디자인 검증(유나), 사업성 분석(다니) 등 8개 전문 도메인으로 확장한 시스템입니다.

직접 만들어보면 원리를 이해하고, 원리를 이해하면 도구를 더 잘 활용할 수 있습니다.

이 글은 build-your-own-x 레포지토리에서 영감을 받은 "Build Your Own X — Agent8 Edition" 시리즈의 첫 편입니다. 다음 편: "나만의 챗봇 만들기"