voltagent/i18n/README-kr.md at main · VoltAgent/voltagent

AI 에이전트 엔지니어링 플랫폼

English | 繁體中文 | 简体中文 | 日本語 | 한국어

홈페이지 | 문서 | 예제

⭐ 마음에 드시면 스타를 눌러주세요 ⬆️

VoltAgent는 두 가지 주요 부분으로 구성된 엔드투엔드 AI 에이전트 엔지니어링 플랫폼입니다:

오픈소스 TypeScript 프레임워크 – 메모리, RAG, 가드레일, 도구, MCP, 음성, 워크플로 등.
VoltOps 콘솔 클라우드 셀프 호스팅 – 관찰 가능성, 자동화, 배포, 평가, 가드레일, 프롬프트 등.

완전한 코드 제어로 에이전트를 구축하고 프로덕션 준비된 가시성과 운영으로 출시하세요.

코어 TypeScript 프레임워크

오픈소스 프레임워크를 사용하면 모든 AI 제공자에 연결하면서 메모리, 도구, 다단계 워크플로를 갖춘 지능형 에이전트를 구축할 수 있습니다. 전문화된 에이전트가 감독자 조정 하에 함께 작동하는 정교한 멀티 에이전트 시스템을 만드세요.

코어 런타임 (@voltagent/core): 타입이 지정된 역할, 도구, 메모리, 모델 제공자를 한 곳에 정의하여 모든 것을 체계적으로 유지하세요.
워크플로 엔진: 커스텀 제어 흐름을 연결하는 대신 다단계 자동화를 선언적으로 설명하세요.
감독자 & 서브 에이전트: 작업을 라우팅하고 동기화를 유지하는 감독자 런타임 하에 전문화된 에이전트 팀을 실행하세요.
도구 레지스트리 & MCP: 라이프사이클 훅과 취소 기능을 갖춘 Zod 타입 도구를 제공하고, 추가 글루 코드 없이 모델 컨텍스트 프로토콜 서버에 연결하세요.
LLM 호환성: 에이전트 로직을 다시 작성하지 않고 구성을 변경하여 OpenAI, Anthropic, Google 또는 다른 제공자 간 전환하세요.
메모리: 내구성 있는 메모리 어댑터를 연결하여 에이전트가 실행 간 중요한 컨텍스트를 기억하도록 하세요.
검색 & RAG: 데이터 소스에서 사실을 가져오고 모델이 답변하기 전에 응답을 기반으로 하는(RAG) 검색기 에이전트를 연결하세요.
VoltAgent 지식 베이스: 문서 수집, 청킹, 임베딩, 검색을 위한 매니지드 RAG 서비스를 사용하세요.
음성: OpenAI, ElevenLabs 또는 커스텀 음성 제공자로 텍스트 음성 변환 및 음성 텍스트 변환 기능을 추가하세요.
가드레일: 런타임에 에이전트 입력 또는 출력을 가로채고 검증하여 콘텐츠 정책 및 안전 규칙을 적용하세요.
평가: 워크플로와 함께 에이전트 평가 스위트를 실행하여 에이전트 동작을 측정하고 개선하세요.

MCP 서버 (@voltagent/mcp-docs-server)

Claude, Cursor 또는 Windsurf와 같은 AI 기반 코딩 어시스턴트를 위해 LLM에게 VoltAgent 사용법을 가르치기 위해 MCP 서버 @voltagent/mcp-docs-server를 사용할 수 있습니다. 이를 통해 AI 어시스턴트가 코딩하는 동안 VoltAgent 문서, 예제, 변경 로그에 직접 액세스할 수 있습니다.

📖 MCP 문서 서버 설정 방법

⚡ 빠른 시작

create-voltagent-app CLI 도구를 사용하여 몇 초 만에 새로운 VoltAgent 프로젝트를 생성하세요:

npm create voltagent-app@latest

이 명령은 설정을 안내합니다.

이제 에이전트와 포괄적인 워크플로 예제를 모두 등록하는 src/index.ts에서 스타터 코드를 볼 수 있으며, 워크플로 예제는 src/workflows/index.ts에서 찾을 수 있습니다.

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,
});

그 후, 프로젝트로 이동하여 실행하세요:

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
══════════════════════════════════════════════════

에이전트가 이제 실행 중입니다! 상호작용하려면:

콘솔 열기: 터미널 출력의 VoltOps LLM 관찰 가능성 플랫폼 링크를 클릭하세요(또는 브라우저에 복사하여 붙여넣기).
에이전트 찾기: VoltOps LLM 관찰 가능성 플랫폼 페이지에서 에이전트가 나열된 것을 볼 수 있어야 합니다(예: "my-agent").
에이전트 세부정보 열기: 에이전트 이름을 클릭하세요.
채팅 시작: 에이전트 세부정보 페이지에서 오른쪽 하단의 채팅 아이콘을 클릭하여 채팅 창을 엽니다.
메시지 보내기: "안녕하세요"와 같은 메시지를 입력하고 Enter를 누르세요.

step-3-test.mp4

첫 번째 워크플로 실행하기

새 프로젝트에는 강력한 워크플로 엔진도 포함되어 있습니다.

비용 승인 워크플로는 일시 중단/재개 기능을 갖춘 휴먼 인 더 루프 자동화를 시연합니다:

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를 테스트할 수 있습니다:

workflow.mp4

워크플로 페이지로 이동: 서버를 시작한 후 워크플로 페이지로 직접 이동하세요.
프로젝트 선택: 프로젝트 선택기를 사용하여 프로젝트를 선택하세요(예: "my-agent-app").
찾기 및 실행: **"Expense Approval Workflow"**가 나열된 것을 볼 수 있습니다. 클릭한 다음 "Run" 버튼을 클릭하세요.
입력 제공: 워크플로는 비용 세부 정보가 포함된 JSON 객체를 예상합니다. 자동 승인을 위한 소액 비용을 시도해보세요:
```
{
  "employeeId": "EMP-123",
  "amount": 250,
  "category": "office-supplies",
  "description": "New laptop mouse and keyboard"
}
```
결과 보기: 실행 후 각 단계에 대한 상세 로그를 검사하고 콘솔에서 직접 최종 출력을 볼 수 있습니다.

예제

더 많은 예제는 예제 리포지토리를 방문하세요.

Airtable 에이전트 - 새 레코드에 반응하고 VoltOps 액션으로 Airtable에 업데이트를 작성합니다.
Slack 에이전트 - 채널 메시지에 응답하고 VoltOps Slack 액션으로 답장합니다.
ChatGPT 앱과 VoltAgent - VoltAgent를 MCP를 통해 배포하고 ChatGPT 앱에 연결합니다.
WhatsApp 주문 에이전트 - 자연스러운 대화로 음식 주문을 처리하는 WhatsApp 챗봇을 구축합니다. (소스 코드)
YouTube to 블로그 에이전트 - MCP 도구를 사용한 감독자 에이전트로 YouTube 비디오를 Markdown 블로그 게시물로 변환합니다. (소스 코드)
AI 광고 생성 에이전트 - BrowserBase Stagehand와 Google Gemini AI를 사용하여 Instagram 광고를 생성합니다. (소스 코드)
AI 레시피 생성 에이전트 - 재료와 선호도에 따라 개인화된 요리 제안을 만듭니다. (소스 코드 | 비디오)
AI 연구 어시스턴트 에이전트 - 포괄적인 보고서를 생성하는 멀티 에이전트 연구 워크플로. (소스 코드 | 비디오)