VoltAgent로 간단한 에이전트 만들어보기

지난 글에서 AI 스킬 얘기를 하다가, 실제로 오픈소스 에이전트 프레임워크 하나 정도는 직접 만져봐야겠다는 생각이 들었습니다. 그래서 이번엔 TypeScript 기반의 오픈소스 에이전트 프레임워크인 VoltAgent를 직접 써보고 느낀 점을 정리해보려고 합니다.

---

VoltAgent를 고른 이유

에이전트 프레임워크가 워낙 많다 보니 처음엔 뭘 써야 할지 고민이 됐습니다. 그중에서 VoltAgent를 고른 이유는 크게 두 가지였습니다.

• 프론트/백엔드 모두 TypeScript로 작업하는 환경이라 진입장벽이 낮았습니다.
• 옵저버빌리티(VoltOps)를 프레임워크 자체에서 기본으로 챙겨준다는 점이 마음에 들었습니다. 에이전트가 왜 이런 판단을 내렸는지 추적이 안 되면 결국 블랙박스가 될 수밖에 없다고 생각했는데, 이 부분을 처음부터 고려하고 설계된 프레임워크라는 게 눈에 띄었습니다.

---

프로젝트 세팅

시작은 CLI 하나로 끝났습니다.

npm create voltagent-app@latest

 

명령어를 실행하니 프로젝트 이름, 사용할 LLM 프로바이더 등을 물어보는 대화형 세팅이 나왔고, 몇 번 선택만 하니 바로 실행 가능한 예제 프로젝트가 만들어졌습니다. src/index.ts에 기본 에이전트 하나와 워크플로우 예제가 이미 들어있어서, 구조를 파악하는 데 오래 걸리지 않았습니다.

---

간단한 날씨 에이전트 만들어보기

가장 먼저 해본 건 튜토리얼에도 자주 나오는 "날씨를 알려주는 에이전트"였습니다. 툴 하나를 정의하고 에이전트에 연결하는 구조가 생각보다 직관적이었습니다.

import { Agent, createTool } from '@voltagent/core'
import { openai } from '@ai-sdk/openai'
import { z } from 'zod'

const fetchWeatherTool = createTool({
  name: 'fetchWeather',
  description: 'Get weather for a location',
  parameters: z.object({
    location: z.string().describe('The city and state, e.g. Seoul')
  }),
  execute: async (args) => {
    // 실제로는 날씨 API를 호출하는 부분
    return { temp: 24, condition: 'Clear' }
  }
})

const agent = new Agent({
  model: openai('gpt-4o-mini'),
  tools: [fetchWeatherTool],
})

 

createTool로 파라미터 스키마(zod)와 실행 함수만 정의해주면, 에이전트가 알아서 언제 이 툴을 호출해야 할지 판단합니다. 이 부분은 다른 프레임워크들과 크게 다르지 않았지만, 타입이 끝까지 따라온다는 점은 확실히 TypeScript 기반 프레임워크의 장점으로 느껴졌습니다.

---

여러 에이전트를 조합해보기

단일 에이전트만으로는 VoltAgent를 써본 의미가 크지 않을 것 같아서, Supervisor로 여러 에이전트를 묶어보는 것도 시도해봤습니다. 역할을 나눠서 에이전트를 여러 개 만들고, 이를 총괄하는 Supervisor 에이전트가 상황에 맞게 하위 에이전트에게 작업을 위임하는 구조였습니다.

처음엔 "이걸 굳이 나눠야 하나" 싶었는데, 막상 만들어보니 각 에이전트가 맡은 역할이 명확해지니까 프롬프트도 짧아지고, 어떤 에이전트가 어떤 판단을 내렸는지 추적하기도 훨씬 쉬워졌습니다.

 

---

VoltOps로 들여다본 에이전트의 판단 과정

개인적으로 가장 인상 깊었던 부분은 VoltOps 콘솔이었습니다. 에이전트를 실행하고 나서 콘솔에 들어가 보니, 어떤 입력에 어떤 툴을 호출했고, 그 결과를 어떻게 해석해서 최종 답변을 만들었는지가 타임라인 형태로 그대로 보였습니다.

지금까지 다른 도구들을 써볼 때는 콘솔 로그를 직접 찍어보거나, 프롬프트 안에 디버그용 지시문을 넣어가면서 에이전트가 왜 이런 답을 냈는지 유추해야 했는데, 이 과정 자체를 프레임워크가 기본으로 제공해준다는 점이 확실히 편했습니다. 실무에 적용한다면 장애가 났을 때 원인 추적 속도가 꽤 달라질 것 같다는 생각이 들었습니다.

 

---

써보면서 아쉬웠던 점

물론 아직 개선되면 좋겠다 싶은 부분도 있었습니다.

• 국내 자료나 커뮤니티가 아직 많지 않아서, 막히는 부분이 생기면 결국 공식 문서와 예제 코드를 직접 뜯어봐야 했습니다.
• 에이전트가 많아질수록 Supervisor 구조를 어떻게 설계해야 효율적인지에 대한 감이 아직 부족해서, 이 부분은 좀 더 써보면서 익혀야 할 것 같습니다.

---

정리

간단한 툴 하나짜리 에이전트부터 멀티 에이전트 구조까지 가볍게 만들어본 소감을 정리하면 이렇습니다.

• TypeScript 환경이라면 진입장벽이 낮고, 타입 안정성 덕분에 툴 정의나 파라미터 실수를 초반에 잡아낼 수 있었습니다.
• VoltOps로 에이전트의 판단 과정을 눈으로 확인할 수 있다는 점이 실무 적용 시 가장 큰 장점이 될 것 같습니다.
• 다만 아직 레퍼런스가 많지 않아서, 복잡한 워크플로우를 설계할 때는 시행착오가 좀 필요해 보입니다.

2026.07.17 - [n년차 개발자] - AI 시대 개발자 공부법, IDE 없이 개발하는 사람들을 보며 든 생각

 

 

지난 글에서 얘기했던 "AI 도구 활용 비중을 높이자"는 방향과 잘 맞는 경험이었던 것 같습니다.

다음엔 실제 업무에서 반복되는 작업 하나를 골라서 VoltAgent로 자동화해보고, 그 결과를 다시 정리해볼까 합니다.