AI 에이전트 엔지니어링 플랫폼
[](https://github.com/voltagent/voltagent/issues)
[](https://github.com/voltagent/voltagent/pulls)
[](https://opensource.org/licenses/MIT)
[](CODE_OF_CONDUCT.md)
[](https://www.npmjs.com/package/@voltagent/core)
[](https://www.npmjs.com/package/@voltagent/core)
[](https://s.voltagent.dev/discord)
[](https://twitter.com/voltagent_dev)
⭐ 마음에 드시면 스타를 눌러주세요 ⬆️
VoltAgent는 두 가지 주요 부분으로 구성된 엔드투엔드 AI 에이전트 엔지니어링 플랫폼입니다:
- **[오픈소스 TypeScript 프레임워크](#core-framework)** – 메모리, RAG, 가드레일, 도구, MCP, 음성, 워크플로 등.
- **[VoltOps 콘솔](#voltops-console)** `클라우드` `셀프 호스팅` – 관찰 가능성, 자동화, 배포, 평가, 가드레일, 프롬프트 등.
완전한 코드 제어로 에이전트를 구축하고 프로덕션 준비된 가시성과 운영으로 출시하세요.
코어 TypeScript 프레임워크
오픈소스 프레임워크를 사용하면 모든 AI 제공자에 연결하면서 메모리, 도구, 다단계 워크플로를 갖춘 지능형 에이전트를 구축할 수 있습니다. 전문화된 에이전트가 감독자 조정 하에 함께 작동하는 정교한 멀티 에이전트 시스템을 만드세요.
- **[코어 런타임](https://voltagent.dev/docs/agents/overview/) (`@voltagent/core`)**: 타입이 지정된 역할, 도구, 메모리, 모델 제공자를 한 곳에 정의하여 모든 것을 체계적으로 유지하세요.
- **[워크플로 엔진](https://voltagent.dev/docs/workflows/overview/)**: 커스텀 제어 흐름을 연결하는 대신 다단계 자동화를 선언적으로 설명하세요.
- **[감독자 & 서브 에이전트](https://voltagent.dev/docs/agents/sub-agents/)**: 작업을 라우팅하고 동기화를 유지하는 감독자 런타임 하에 전문화된 에이전트 팀을 실행하세요.
- **[도구 레지스트리](https://voltagent.dev/docs/agents/tools/) & [MCP](https://voltagent.dev/docs/agents/mcp/)**: 라이프사이클 훅과 취소 기능을 갖춘 Zod 타입 도구를 제공하고, 추가 글루 코드 없이 [모델 컨텍스트 프로토콜](https://modelcontextprotocol.io/) 서버에 연결하세요.
- **[LLM 호환성](https://voltagent.dev/docs/getting-started/providers-models/)**: 에이전트 로직을 다시 작성하지 않고 구성을 변경하여 OpenAI, Anthropic, Google 또는 다른 제공자 간 전환하세요.
- **[메모리](https://voltagent.dev/docs/agents/memory/overview/)**: 내구성 있는 메모리 어댑터를 연결하여 에이전트가 실행 간 중요한 컨텍스트를 기억하도록 하세요.
- **[검색 & RAG](https://voltagent.dev/docs/rag/overview/)**: 데이터 소스에서 사실을 가져오고 모델이 답변하기 전에 응답을 기반으로 하는(RAG) 검색기 에이전트를 연결하세요.
- **[VoltAgent 지식 베이스](https://voltagent.dev/docs/rag/voltagent/)**: 문서 수집, 청킹, 임베딩, 검색을 위한 매니지드 RAG 서비스를 사용하세요.
- **[음성](https://voltagent.dev/docs/agents/voice/)**: OpenAI, ElevenLabs 또는 커스텀 음성 제공자로 텍스트 음성 변환 및 음성 텍스트 변환 기능을 추가하세요.
- **[가드레일](https://voltagent.dev/docs/guardrails/overview/)**: 런타임에 에이전트 입력 또는 출력을 가로채고 검증하여 콘텐츠 정책 및 안전 규칙을 적용하세요.
- **[평가](https://voltagent.dev/docs/evals/overview/)**: 워크플로와 함께 에이전트 평가 스위트를 실행하여 에이전트 동작을 측정하고 개선하세요.
#### MCP 서버 (@voltagent/mcp-docs-server)
Claude, Cursor 또는 Windsurf와 같은 AI 기반 코딩 어시스턴트를 위해 LLM에게 VoltAgent 사용법을 가르치기 위해 MCP 서버 `@voltagent/mcp-docs-server`를 사용할 수 있습니다. 이를 통해 AI 어시스턴트가 코딩하는 동안 VoltAgent 문서, 예제, 변경 로그에 직접 액세스할 수 있습니다.
📖 [MCP 문서 서버 설정 방법](https://voltagent.dev/docs/getting-started/mcp-docs-server/)
## ⚡ 빠른 시작
`create-voltagent-app` CLI 도구를 사용하여 몇 초 만에 새로운 VoltAgent 프로젝트를 생성하세요:
```bash
npm create voltagent-app@latest
```
이 명령은 설정을 안내합니다.
이제 에이전트와 포괄적인 워크플로 예제를 모두 등록하는 `src/index.ts`에서 스타터 코드를 볼 수 있으며, 워크플로 예제는 `src/workflows/index.ts`에서 찾을 수 있습니다.
```typescript
import { VoltAgent, Agent, Memory } from "@voltagent/core";
import { LibSQLMemoryAdapter } from "@voltagent/libsql";
import { createPinoLogger } from "@voltagent/logger";
import { honoServer } from "@voltagent/server-hono";
import { openai } from "@ai-sdk/openai";
import { expenseApprovalWorkflow } from "./workflows";
import { weatherTool } from "./tools";
// 로거 인스턴스 생성
const logger = createPinoLogger({
name: "my-agent-app",
level: "info",
});
// 선택적 영구 메모리 (기본 인메모리를 사용하려면 제거)
const memory = new Memory({
storage: new LibSQLMemoryAdapter({ url: "file:./.voltagent/memory.db" }),
});
// 프로젝트를 위한 간단한 범용 에이전트
const agent = new Agent({
name: "my-agent",
instructions: "날씨를 확인하고 다양한 작업을 도울 수 있는 유용한 어시스턴트",
model: openai("gpt-4o-mini"),
tools: [weatherTool],
memory,
});
// 에이전트 및 워크플로로 VoltAgent 초기화
new VoltAgent({
agents: {
agent,
},
workflows: {
expenseApprovalWorkflow,
},
server: honoServer(),
logger,
});
```
그 후, 프로젝트로 이동하여 실행하세요:
```bash
npm run dev
```
dev 명령을 실행하면 tsx가 코드를 컴파일하고 실행합니다. 터미널에 VoltAgent 서버 시작 메시지가 표시되어야 합니다:
```
══════════════════════════════════════════════════
VOLTAGENT SERVER STARTED SUCCESSFULLY
══════════════════════════════════════════════════
✓ HTTP Server: http://localhost:3141
Test your agents with VoltOps Console: https://console.voltagent.dev
══════════════════════════════════════════════════
```
에이전트가 이제 실행 중입니다! 상호작용하려면:
1. 콘솔 열기: 터미널 출력의 [VoltOps LLM 관찰 가능성 플랫폼](https://console.voltagent.dev) 링크를 클릭하세요(또는 브라우저에 복사하여 붙여넣기).
2. 에이전트 찾기: VoltOps LLM 관찰 가능성 플랫폼 페이지에서 에이전트가 나열된 것을 볼 수 있어야 합니다(예: "my-agent").
3. 에이전트 세부정보 열기: 에이전트 이름을 클릭하세요.
4. 채팅 시작: 에이전트 세부정보 페이지에서 오른쪽 하단의 채팅 아이콘을 클릭하여 채팅 창을 엽니다.
5. 메시지 보내기: "안녕하세요"와 같은 메시지를 입력하고 Enter를 누르세요.
[](https://github.com/user-attachments/assets/26340c6a-be34-48a5-9006-e822bf6098a7)
### 첫 번째 워크플로 실행하기
새 프로젝트에는 강력한 워크플로 엔진도 포함되어 있습니다.
비용 승인 워크플로는 일시 중단/재개 기능을 갖춘 휴먼 인 더 루프 자동화를 시연합니다:
```typescript
import { createWorkflowChain } from "@voltagent/core";
import { z } from "zod";
export const expenseApprovalWorkflow = createWorkflowChain({
id: "expense-approval",
name: "Expense Approval Workflow",
purpose: "Process expense reports with manager approval for high amounts",
input: z.object({
employeeId: z.string(),
amount: z.number(),
category: z.string(),
description: z.string(),
}),
result: z.object({
status: z.enum(["approved", "rejected"]),
approvedBy: z.string(),
finalAmount: z.number(),
}),
})
// 1단계: 비용 검증 및 승인 필요 여부 확인
.andThen({
id: "check-approval-needed",
resumeSchema: z.object({
approved: z.boolean(),
managerId: z.string(),
comments: z.string().optional(),
adjustedAmount: z.number().optional(),
}),
execute: async ({ data, suspend, resumeData }) => {
// 관리자의 결정으로 재개하는 경우
if (resumeData) {
return {
...data,
approved: resumeData.approved,
approvedBy: resumeData.managerId,
finalAmount: resumeData.adjustedAmount || data.amount,
};
}
// 관리자 승인이 필요한지 확인 ($500 초과 비용)
if (data.amount > 500) {
await suspend("Manager approval required", {
employeeId: data.employeeId,
requestedAmount: data.amount,
});
}
// 소액 비용 자동 승인
return {
...data,
approved: true,
approvedBy: "system",
finalAmount: data.amount,
};
},
})
// 2단계: 최종 결정 처리
.andThen({
id: "process-decision",
execute: async ({ data }) => {
return {
status: data.approved ? "approved" : "rejected",
approvedBy: data.approvedBy,
finalAmount: data.finalAmount,
};
},
});
```
VoltOps 콘솔에서 직접 사전 구축된 `expenseApprovalWorkflow`를 테스트할 수 있습니다:
[](https://github.com/user-attachments/assets/3d3ea67b-4ab5-4dc0-932d-cedd92894b18)
1. **워크플로 페이지로 이동**: 서버를 시작한 후 [워크플로 페이지](https://console.voltagent.dev/workflows)로 직접 이동하세요.
2. **프로젝트 선택**: 프로젝트 선택기를 사용하여 프로젝트를 선택하세요(예: "my-agent-app").
3. **찾기 및 실행**: **"Expense Approval Workflow"**가 나열된 것을 볼 수 있습니다. 클릭한 다음 **"Run"** 버튼을 클릭하세요.
4. **입력 제공**: 워크플로는 비용 세부 정보가 포함된 JSON 객체를 예상합니다. 자동 승인을 위한 소액 비용을 시도해보세요:
```json
{
"employeeId": "EMP-123",
"amount": 250,
"category": "office-supplies",
"description": "New laptop mouse and keyboard"
}
```
5. **결과 보기**: 실행 후 각 단계에 대한 상세 로그를 검사하고 콘솔에서 직접 최종 출력을 볼 수 있습니다.
## 예제
더 많은 예제는 [예제 리포지토리](https://github.com/VoltAgent/voltagent/tree/main/examples)를 방문하세요.
- **[Airtable 에이전트](https://voltagent.dev/recipes-and-guides/airtable-agent)** - 새 레코드에 반응하고 VoltOps 액션으로 Airtable에 업데이트를 작성합니다.
- **[Slack 에이전트](https://voltagent.dev/recipes-and-guides/slack-agent)** - 채널 메시지에 응답하고 VoltOps Slack 액션으로 답장합니다.
- **[ChatGPT 앱과 VoltAgent](https://voltagent.dev/examples/agents/chatgpt-app)** - VoltAgent를 MCP를 통해 배포하고 ChatGPT 앱에 연결합니다.
- **[WhatsApp 주문 에이전트](https://voltagent.dev/examples/agents/whatsapp-ai-agent)** - 자연스러운 대화로 음식 주문을 처리하는 WhatsApp 챗봇을 구축합니다. ([소스 코드](https://github.com/VoltAgent/voltagent/tree/main/examples/with-whatsapp))
- **[YouTube to 블로그 에이전트](https://voltagent.dev/examples/agents/youtube-blog-agent)** - MCP 도구를 사용한 감독자 에이전트로 YouTube 비디오를 Markdown 블로그 게시물로 변환합니다. ([소스 코드](https://github.com/VoltAgent/voltagent/tree/main/examples/with-youtube-to-blog))
- **[AI 광고 생성 에이전트](https://voltagent.dev/examples/agents/ai-instagram-ad-agent)** - BrowserBase Stagehand와 Google Gemini AI를 사용하여 Instagram 광고를 생성합니다. ([소스 코드](https://github.com/VoltAgent/voltagent/tree/main/examples/with-ad-creator))
- **[AI 레시피 생성 에이전트](https://voltagent.dev/examples/agents/recipe-generator)** - 재료와 선호도에 따라 개인화된 요리 제안을 만듭니다. ([소스 코드](https://github.com/VoltAgent/voltagent/tree/main/examples/with-recipe-generator) | [비디오](https://youtu.be/KjV1c6AhlfY))
- **[AI 연구 어시스턴트 에이전트](https://voltagent.dev/examples/agents/research-assistant)** - 포괄적인 보고서를 생성하는 멀티 에이전트 연구 워크플로. ([소스 코드](https://github.com/VoltAgent/voltagent/tree/main/examples/with-research-assistant) | [비디오](https://youtu.be/j6KAUaoZMy4))
VoltOps 콘솔: LLM 관찰 가능성 - 자동화 - 배포
VoltOps 콘솔은 VoltAgent의 플랫폼 측면으로, 관찰 가능성, 자동화, 배포를 제공하여 실시간 실행 추적, 성능 메트릭, 시각적 대시보드로 프로덕션 에이전트를 모니터링하고 디버그할 수 있습니다.
🎬 [라이브 데모 체험](https://console.voltagent.dev/demo)
📖 [VoltOps 문서](https://voltagent.dev/voltops-llm-observability-docs/)
🚀 [VoltOps 플랫폼](https://voltagent.dev/voltops-llm-observability/)
### 관찰 가능성 & 추적
상세한 추적 및 성능 메트릭으로 에이전트 실행 흐름을 깊이 있게 살펴보세요.
### 대시보드
모든 에이전트, 워크플로 및 시스템 성능 메트릭에 대한 포괄적인 개요를 얻으세요.
### 로그
모든 에이전트 상호작용 및 워크플로 단계에 대한 상세한 실행 로그를 추적하세요.
### 메모리 관리
에이전트 메모리, 컨텍스트 및 대화 기록을 검사하고 관리하세요.
### 추적
에이전트 동작을 이해하고 성능을 최적화하기 위해 완전한 실행 추적을 분석하세요.
### 프롬프트 빌더
콘솔에서 직접 프롬프트를 설계, 테스트 및 개선하세요.
### 배포
원클릭 GitHub 통합 및 매니지드 인프라로 에이전트를 프로덕션에 배포하세요.
📖 [VoltOps 배포 문서](https://voltagent.dev/docs/deployment/voltops/)
### 트리거 & 액션
웹훅, 스케줄, 커스텀 트리거로 에이전트 워크플로를 자동화하여 외부 이벤트에 반응하세요.
### 모니터링
전체 시스템에서 에이전트 상태, 성능 메트릭 및 리소스 사용량을 모니터링하세요.
### 가드레일
에이전트가 정의된 매개변수 내에서 작동하도록 안전 경계 및 콘텐츠 필터를 설정하세요.
### 평가
벤치마크에 대해 에이전트 동작, 정확도 및 성능을 테스트하는 평가 스위트를 실행하세요.
### RAG (지식 베이스)
내장된 검색 증강 생성 기능으로 에이전트를 지식 소스에 연결하세요.
## VoltAgent 학습하기
- **[대화형 튜토리얼로 시작](https://voltagent.dev/tutorial/introduction/)**하여 AI 에이전트 구축의 기본을 배우세요.
- **[문서](https://voltagent.dev/docs/)**: 가이드, 개념 및 튜토리얼을 깊이 있게 살펴보세요.
- **[예제](https://github.com/voltagent/voltagent/tree/main/examples)**: 실용적인 구현을 탐색하세요.
- **[블로그](https://voltagent.dev/blog/)**: 기술적 통찰력 및 모범 사례에 대해 더 읽어보세요.
## 기여
저희는 기여를 환영합니다! 기여 가이드라인을 참조해주세요(가능한 경우 링크 필요). 질문과 토론을 위해 저희 [Discord](https://s.voltagent.dev/discord) 서버에 참여하세요.
## 기여자 ♥️ 감사합니다
플러그인을 구축했든, 이슈를 열었든, 풀 리퀘스트를 제출했든, 아니면 단순히 Discord나 GitHub 토론에서 누군가를 도왔든, VoltAgent 여정의 일부가 된 모든 분들께 진심으로 감사드립니다.
VoltAgent는 커뮤니티의 노력이며, 여러분과 같은 사람들 덕분에 계속해서 더 나아지고 있습니다.
## 라이선스
MIT 라이선스 하에 라이선스가 부여됩니다, Copyright © 2026-present VoltAgent.