기반 경로: n8n/packages/nodes-base/nodes/, n8n/packages/@n8n/nodes-langchain/nodes/ 생성일: 2026-02-04 소스: 실제 *.node.ts 파일에서 추출 [T] = Trigger 노드, [LC] = LangChain 패키지 노드

목차

1. 트리거 및 시작점
2. 로직 및 흐름 제어
3. 데이터 변환 및 처리
4. 코드 및 스크립트 실행
5. HTTP 및 API 통신
6. 파일 및 바이너리 처리
7. 이메일
8. 메신저 및 채팅
9. 메시지 큐 및 실시간 통신
10. 클라우드 저장소
11. 데이터베이스
12. CRM 및 영업
13. 프로젝트 및 작업 관리
14. 이벤트 및 폼
15. 소셜 미디어
16. 개발 및 DevOps
17. 결제 및 금융
18. AWS 서비스
19. Google 서비스
20. Microsoft / Azure 서비스
21. AI / ML (nodes-base)
22. AI Agent 및 체인 (LangChain)
23. LLM 모델 연결 (LangChain)
24. Embeddings (LangChain)
25. 벡터 저장소 (LangChain)
26. 메모리 (LangChain)
27. AI 도구 (LangChain)
28. Retriever (LangChain)
29. 텍스트 분할 및 파싱 (LangChain)
30. MCP (LangChain)
31. n8n 내부 및 기타
32. 마케팅 및 이메일 자동화
33. 모니터링 및 관측성
34. 보안 및 인증
35. IoT 및 홈 자동화
36. 기타 통합

1. 트리거 및 시작점

워크플로우 실행을 시작하는 트리거 노드들.

트리거 노드 공통 특징:

• 모든 트리거는 ITriggerFunctions 또는 IWebhookFunctions 구현
• 입력 없음 (inputs: [])
• trigger() 또는 webhook() 메서드로 실행 시작
• manualTriggerFunction 제공 시 수동 테스트 실행 가능

2. 로직 및 흐름 제어

워크플로우 내 조건 분기, 루프, 병합 등의 흐름 로직.

3. 데이터 변환 및 처리

입출력 데이터의 형태, 구조, 내용을 변환하는 노드들.

4. 코드 및 스크립트 실행

사용자 정의 코드를 직접 실행하는 노드들.

Code 노드 상세:

nodes-base/Code 노드

• 실행 모드:
  • runOnceForAllItems: 전체 아이템을 한번에 처리
  • runOnceForEachItem: 각 아이템마다 개별 실행
• 샌드박스 종류:
  • JavaScriptSandbox: V8 Isolate 기반 안전한 실행 환경
  • JsTaskRunnerSandbox: Task Runner를 통한 격리 실행
  • PythonSandbox: Python 코드 실행 환경
  • PythonTaskRunnerSandbox: Python Task Runner 실행
• 사용 가능 객체: $items, $input, $json, $binary, $itemIndex, $runIndex, $now, 등
• 의존성 주입: @n8n/di Container를 통한 설정 관리

@n8n/nodes-langchain/Code 노드

• 동적 입출력: 사용자 정의 연결 타입 지원
  • 입력: AiChain, AiDocument, AiEmbedding, AiLanguageModel, AiMemory, AiOutputParser, AiTextSplitter, AiTool, AiVectorStore, Main
  • 출력: 동일한 타입 지원
• 실행 방식:
  • execute: 일반 워크플로우 노드로 실행
  • supplyData: AI 컴포넌트로 실행 (Tool, Chain 등 반환)
• LangChain 통합: @langchain/core/tools (Tool 클래스) 사용
• 레거시 호환: langchain → @langchain/classic 자동 변환

5. HTTP 및 API 통신

외부 API와의 HTTP 요청/응답을 담당하는 범용 노드.

6. 파일 및 바이너리 처리

파일 읽기, 쓰기, 변환을 담당하는 노드들.

7. 이메일

이메일 발송 및 수신을 담당하는 노드들.

8. 메신저 및 채팅

메신저 앱과의 통신을 담당하는 노드들.

9. 메시지 큐 및 실시간 통신

메시지 큐, Pub/Sub, MQTT 등 비동기 통신 노드들.

10. 클라우드 저장소

클라우드 파일 저장소 및 드라이브와의 연동.

11. 데이터베이스

관계형 및 NoSQL 데이터베이스와의 연동.

12. CRM 및 영업

고객 관계 관리 및 영업 파이프라인 통합.

13. 프로젝트 및 작업 관리

프로젝트, 이슈, 작업 관리 도구와의 통합.

14. 이벤트 및 폼

폼 제출, 이벤트 등록, 웹비너 등의 이벤트 통합.

15. 소셜 미디어

SNS 및 소셜 미디어 플랫폼과의 통합.

16. 개발 및 DevOps

소프트웨어 개발, CI/CD, Git 관련 통합.

17. 결제 및 금융

결제 처리, 인보이스, 금융 서비스 통합.

18. AWS 서비스

Amazon Web Services 서비스 통합.

19. Google 서비스

Google Cloud 및 Workspace 서비스 통합.

20. Microsoft / Azure 서비스

Microsoft 365 및 Azure 서비스 통합.

21. AI / ML (nodes-base)

nodes-base 패키지의 AI 및 ML 관련 노드.

22. AI Agent 및 체인 (LangChain)

LangChain 기반 AI 에이전트 및 체인 노드. [LC]

Agent 노드 상세:

• 버전: 1.0-1.9 (V1), 2.0-2.3 (V2), 3.0-3.1 (V3, 기본값)
• 지원 에이전트 타입:
  • Conversational: 대화형 에이전트 (conversationalAgentExecute)
  • OpenAI Functions: OpenAI Function Calling 사용 (openAiFunctionsAgentExecute)
  • Plan and Execute: 계획 수립 후 실행 (planAndExecuteAgentExecute)
  • ReAct: Reasoning + Acting 패턴 (reActAgentAgentExecute)
  • SQL: SQL 데이터베이스 쿼리 (sqlAgentAgentExecute)
  • Tools: 범용 도구 에이전트 (toolsAgentExecute, V1/V2/V3 별도 구현)
• 동적 입력: Chat Model(필수), Memory(선택, 최대 1개), Tools(무제한), Output Parser(선택, 최대 1개)

23. LLM 모델 연결 (LangChain)

LLM 모델을 에이전트/체인에 연결하는 노드. [LC]

공통 특징:

• 모든 LLM 노드는 ISupplyDataFunctions를 통해 LangChain 모델 인스턴스를 제공
• listSearch.searchModels 메서드로 사용 가능한 모델 목록 동적 로드
• N8nLlmTracing으로 LLM 호출 추적 및 로깅
• HTTP 프록시 에이전트 지원 (getProxyAgent)
• 실패 시 자동 재시도 핸들러 (makeN8nLlmFailedAttemptHandler)

24. Embeddings (LangChain)

텍스트를 벡터로 변환하는 Embedding 모델 노드. [LC]

25. 벡터 저장소 (LangChain)

벡터 DB와의 연동 및 조회 노드. [LC]

26. 메모리 (LangChain)

AI 에이전트의 대화 이력 및 메모리 관리 노드. [LC]

참고: 모든 메모리 노드는 @langchain/community/memory 또는 관련 라이브러리를 사용하며, ISupplyDataFunctions를 통해 메모리 인스턴스를 제공합니다.

27. AI 도구 (LangChain)

에이전트가 호출할 수 있는 Tool 노드. [LC]

28. Retriever (LangChain)

벡터 저장소에서 관련 정보를 검색하는 Retriever 노드. [LC]

29. 텍스트 분할 및 파싱 (LangChain)

긴 텍스트를 청크로 분할하거나 LLM 출력을 파싱하는 노드. [LC]

Text Splitters:

Output Parsers:

Rerankers:

Document Loaders:

30. MCP (LangChain)

Model Context Protocol 관련 노드. [LC]

31. n8n 내부 및 기타

n8n 자체 기능과 관련된 노드들.

32. 마케팅 및 이메일 자동화

이메일 마케팅, 뉴스레터, 리드 관리 등의 마케팅 통합.

33. 모니터링 및 관측성

시스템 모니터링, 로깅, 알림 관련 통합.

34. 보안 및 인증

보안, 인증, 비밀 관리 관련 노드들.

35. IoT 및 홈 자동화

IoT 장치 및 스마트홈 연동.

36. 기타 통합

위 카테고리에 해당하지 않는 기타 서비스 통합.

통계 요약

노드 로딩 및 실행 아키텍처

1. 노드 등록 및 로딩

노드 발견 프로세스 (packages/cli/src/load-nodes-and-credentials.ts):

// 1. 노드 패키지에서 발견
async init() {
  await this.loadNodesFromNodeModules(nodeModulesDir, 'n8n-nodes-base');
  await this.loadNodesFromNodeModules(nodeModulesDir, '@n8n/n8n-nodes-langchain');
  await this.loadNodesFromCustomDirectories();
  await this.postProcessLoaders();
}

// 2. 등록 데이터 구조
known: {
  nodes: { "n8n-nodes-base.webhook": { className: "Webhook", sourcePath: "..." } }
}
loaded: {
  nodes: { "n8n-nodes-base.webhook": LoadedClass<INodeType> }
}
types: {
  nodes: [{ name: "n8n-nodes-base.webhook", displayName: "Webhook", ... }]
}

노드 접근 (packages/workflow/src/NodeTypes.ts):

// Workflow 인스턴스를 통한 노드 타입 조회
const nodeType = workflow.nodeTypes.getByNameAndVersion(node.type, node.typeVersion);
// 반환: INodeType 인스턴스 (execute, trigger, webhook, poll 메서드 포함)

2. 워크플로우 활성화 및 노드 실행

Webhook 노드

활성화 시 (packages/cli/src/active-workflow-manager.ts:118-188):

async addWebhooks(workflow, additionalData, mode, activationMode) {
  const webhooks = workflow.getWebhooks(); // 모든 webhook 노드 수집

  for (const webhookData of webhooks) {
    const path = workflow.expression.getSimpleParameterValue(
      node, webhookData.path, mode, {}, { ...additionalData }
    );

    // database에 webhook 등록
    await this.webhookService.storeWebhook({
      workflowId: workflow.id,
      webhookPath: path,
      node: webhookData.node,  // ← 노드 이름 저장
      method: webhookData.httpMethod,
    });
  }
}

실행 시 (packages/cli/src/webhooks/live-webhooks.ts:80-151):

async executeWebhook(request: WebhookRequest, response: Response) {
  // 1. database에서 webhook 조회
  const webhook = await this.findWebhook(path, httpMethod);

  // 2. workflow 로드
  const workflowData = await this.workflowRepository.findOne({
    where: { id: webhook.workflowId }
  });

  // 3. Workflow 인스턴스 생성
  const workflow = new Workflow({ id, name, nodes, connections, nodeTypes });

  // 4. webhook 노드 찾기
  const workflowStartNode = workflow.getNode(webhook.node);  // ← 저장된 노드 이름 사용

  // 5. webhook 실행
  return await WebhookHelpers.executeWebhook(
    workflow,
    webhookData,
    workflowStartNode,  // ← 시작 노드로 전달
    ...
  );
}

실제 실행 (packages/cli/src/webhooks/webhook-helpers.ts:366-382):

async executeWebhook(...) {
  // 1. webhook 노드의 webhook() 메서드 실행
  const webhookResultData = await Container.get(WebhookService).runWebhook(
    workflow,
    webhookData,
    workflowStartNode,
    ...
  );

  // 2. WorkflowRunner를 통해 전체 워크플로우 실행
  const executionId = await Container.get(WorkflowRunner).run({
    executionMode: 'webhook',
    executionData: preparedRunExecutionData,  // webhook 노드 출력을 시작 데이터로
    workflowData,
  });
}

Trigger 노드

활성화 시 (packages/cli/src/active-workflow-manager.ts:190-281):

async addTriggersAndPollers(dbWorkflow, workflow, options) {
  const triggerNodes = workflow.getTriggerNodes();

  for (const triggerNode of triggerNodes) {
    // TriggerContext 생성 (emit 콜백 포함)
    const triggerFunctions = this.getExecuteTriggerFunctions(
      dbWorkflow, additionalData, mode, activation
    );

    // trigger() 메서드 호출
    const triggerResponse = await this.triggersAndPollers.runTrigger(
      workflow,
      triggerNode,
      triggerFunctions,
      ...
    );

    // 메모리에 저장 (계속 실행 중)
    this.activeWorkflows.add(workflow.id, { triggerResponses: [triggerResponse] });
  }
}

emit 콜백 (packages/cli/src/active-workflow-manager.ts:339-401):

getExecuteTriggerFunctions(workflowData, additionalData, mode, activation) {
  return (workflow: Workflow, node: INode) => {
    const emit = (data: INodeExecutionData[][]) => {
      // 트리거가 데이터를 emit하면 워크플로우 실행
      const executePromise = this.workflowExecutionService.runWorkflow(
        workflowData,
        node,        // ← trigger 노드
        data,        // ← emit된 데이터
        additionalData,
        mode,
      );
    };

    return new TriggerContext(workflow, node, additionalData, mode, emit);
  };
}

예시 - ManualTrigger 노드:

// nodes-base/nodes/ManualTrigger/ManualTrigger.node.ts
async trigger(this: ITriggerFunctions): Promise<ITriggerResponse> {
  const manualTriggerFunction = async () => {
    this.emit([this.helpers.returnJsonArray([{}])]);  // ← emit 호출
  };

  return { manualTriggerFunction };
}

Execute 노드 (일반 노드)

실행 시 (packages/core/src/execution-engine/workflow-execute.ts:1404-2100):

processRunExecutionData(workflow: Workflow): PCancelable<IRun> {
  return new PCancelable(async (resolve) => {
    // 실행 루프
    while (this.runExecutionData.executionData!.nodeExecutionStack.length !== 0) {
      const executionData: IExecuteData =
        this.runExecutionData.executionData!.nodeExecutionStack.shift();

      const executionNode = executionData.node;

      // 노드 실행
      const runNodeData = await this.runNode(
        workflow,
        executionData,
        this.runExecutionData,
        runIndex,
        ...
      );

      // 결과 저장
      this.runExecutionData.resultData.runData[executionNode.name] = nodeSuccessData;

      // 다음 노드들을 스택에 추가
      workflow.getChildNodes(executionNode.name).forEach((childNodeName) => {
        this.addNodeToBeExecuted(workflow, { node: childNodeName, ... });
      });
    }

    resolve(this.getFullRunData(startedAt));
  });
}

노드 실행 상세 (packages/core/src/execution-engine/workflow-execute.ts:1662-1725):

private async executeNode(workflow, node, nodeType, ...) {
  // 1. ExecuteContext 생성
  const context = new ExecuteContext(
    workflow,
    node,
    additionalData,
    mode,
    runExecutionData,
    ...
  );

  // 2. execute() 메서드 호출
  let data: INodeExecutionData[][];
  if (nodeType.execute) {
    data = await nodeType.execute.call(context);  // ← 노드의 execute() 실행
  }

  return { data, hints: context.hints };
}

3. 주요 실행 파일 및 역할

4. 실행 흐름 요약

[노드 파일 작성]
  ↓
packages/nodes-base/nodes/Webhook/Webhook.node.ts
  ↓ (빌드)
dist/nodes/Webhook/Webhook.node.js
  ↓ (package.json에 등록)
{
  "n8n": {
    "nodes": ["dist/nodes/Webhook/Webhook.node.js"]
  }
}
  ↓ (서버 시작 시)
LoadNodesAndCredentials.init()
  ↓ (패키지 스캔)
loadNodesFromNodeModules('n8n-nodes-base')
  ↓ (메타데이터 등록)
known.nodes['n8n-nodes-base.webhook'] = { className: 'Webhook', sourcePath: '...' }
types.nodes.push({ name: 'n8n-nodes-base.webhook', displayName: 'Webhook', ... })
  ↓
[워크플로우 활성화]
  ↓
ActiveWorkflowManager.add(workflowId)
  ↓ (Webhook 노드인 경우)
addWebhooks() → WebhookService.storeWebhook() → database 저장
  ↓ (Trigger 노드인 경우)
addTriggersAndPollers() → runTrigger() → 메모리에 유지
  ↓
[실행 트리거]
  ↓ (Webhook)
HTTP 요청 → LiveWebhooks.executeWebhook() → WebhookHelpers.executeWebhook()
  ↓ (Trigger)
emit() 콜백 → WorkflowExecutionService.runWorkflow()
  ↓
[공통 실행 경로]
WorkflowRunner.run()
  ↓
runMainProcess() 또는 enqueueExecution()
  ↓
WorkflowExecute.processRunExecutionData()
  ↓ (실행 루프)
executeNode() → nodeType.execute.call(context)
  ↓
결과 수집 → 다음 노드를 스택에 추가
  ↓
getFullRunData() → 실행 완료

5. 노드 타입별 실행 차이점

6. 모든 노드의 실제 사용 위치 분석

핵심 원리: n8n 노드는 직접 import되지 않고 동적으로 로드됨

중요한 이해: 대부분의 노드는 코드에서 직접 import { GraphQL } from '...'처럼 import되지 않습니다. 대신 다음과 같은 동적 로딩 메커니즘을 사용합니다:

1. 노드 정의: packages/nodes-base/nodes/GraphQL/GraphQL.node.ts에서 클래스 정의
2. 노드 등록: packages/nodes-base/package.json의 n8n.nodes 배열에 등록
3. 동적 로딩: LoadNodesAndCredentials 서비스가 서버 시작 시 자동 스캔
4. 이름으로 참조: 런타임에서 노드 이름(문자열)으로 접근

전체 노드 공통 사용 패턴

1. 노드 로딩 및 등록 (모든 640개 노드 공통)

파일: packages/cli/src/load-nodes-and-credentials.ts

// 서버 시작 시 모든 노드 자동 로딩
async init() {
  await this.loadNodesFromNodeModules();
  this.postProcessLoaders();
}

// package.json에서 노드 발견
private async loadNodesFromNodeModules() {
  // 1. n8n-nodes-base/package.json 읽기
  // 2. n8n.nodes 배열에서 각 노드 경로 추출
  // 3. 노드 클래스 동적 로드
  // 예: "dist/nodes/GraphQL/GraphQL.node.js" → GraphQL 클래스

  this.known.nodes['n8n-nodes-base.graphql'] = {
    className: 'GraphQL',
    sourcePath: 'packages/nodes-base/nodes/GraphQL/GraphQL.node.ts'
  };
}

// 노드 타입 레지스트리에 저장
private postProcessLoaders() {
  this.types.nodes.push({
    name: 'n8n-nodes-base.graphql',
    displayName: 'GraphQL',
    description: 'Makes a GraphQL request...',
    // ... 모든 노드 메타데이터
  });
}

결과: 모든 노드(GraphQL, Set, Webhook, Postgres 등 640개 모두)가 NodeTypes 서비스에 등록됨.

2. 노드 조회 (런타임에서 이름으로 접근)

파일: packages/workflow/src/NodeTypes.ts

export class NodeTypes {
  // 이름으로 노드 타입 조회 (모든 노드 공통)
  getByNameAndVersion(nodeType: string, version?: number): INodeType {
    // 예: 'n8n-nodes-base.graphql' → GraphQL 노드 클래스 반환
    // 예: 'n8n-nodes-base.postgres' → Postgres 노드 클래스 반환
    return this.loadedNodes[nodeType].type;
  }
}

사용 위치:

• packages/cli/src/webhooks/live-webhooks.ts:60 - 웹훅 노드 검증
• packages/cli/src/active-workflow-manager.ts:전체 - 모든 노드 활성화 시
• packages/core/src/execution-engine/workflow-execute.ts:전체 - 모든 노드 실행 시
• packages/workflow/src/Workflow.ts:전체 - 워크플로우 구조 파싱 시

3. 워크플로우에서 노드 참조

파일: packages/workflow/src/Workflow.ts

export class Workflow {
  // 워크플로우의 모든 노드는 name(문자열)으로 저장됨
  nodes: INode[] = [
    { name: 'GraphQL', type: 'n8n-nodes-base.graphql', parameters: {...} },
    { name: 'Postgres1', type: 'n8n-nodes-base.postgres', parameters: {...} },
    { name: 'Webhook', type: 'n8n-nodes-base.webhook', parameters: {...} }
  ];

  // 이름으로 노드 찾기 (모든 노드 실행의 핵심 메서드)
  getNode(nodeName: string): INode | null {
    return this.nodes.find(node => node.name === nodeName);
  }

  // 트리거 노드만 필터링
  getTriggerNodes(): INode[] {
    return this.nodes.filter(node => {
      const nodeType = this.nodeTypes.getByNameAndVersion(node.type);
      return nodeType.trigger !== undefined;
    });
  }

  // 웹훅 노드만 필터링
  getWebhooks(): IWebhookData[] {
    const webhooks = [];
    for (const node of this.nodes) {
      const nodeType = this.nodeTypes.getByNameAndVersion(node.type);
      if (nodeType.webhook) {
        webhooks.push(/* webhook 데이터 */);
      }
    }
    return webhooks;
  }
}

노드 타입별 구체적 사용 위치

A. Webhook 노드 (Webhook, HttpRequest, ChatTrigger 등)

활성화 시: packages/cli/src/active-workflow-manager.ts:129-179

async addWebhooks(workflow, mode) {
  const webhooks = workflow.getWebhooks();  // ← 모든 webhook 노드 찾기

  for (const webhookData of webhooks) {
    // database에 저장 (webhook_entity 테이블)
    await this.webhookService.storeWebhook({
      workflowId: workflow.id,
      webhookPath: webhookData.path,
      node: webhookData.node,  // ← 노드 이름 (예: "Webhook", "HttpRequest1")
      method: webhookData.httpMethod,
    });
  }
}

실행 시: packages/cli/src/webhooks/live-webhooks.ts:71-172

async executeWebhook(request, response) {
  // 1. database에서 webhook 찾기
  const webhook = await this.findWebhook(path, httpMethod);
  // webhook.node = "Webhook" (저장된 노드 이름)

  // 2. 워크플로우 로드
  const workflow = new Workflow({ nodes, connections, nodeTypes });

  // 3. 노드 이름으로 시작 노드 찾기
  const workflowStartNode = workflow.getNode(webhook.node);  // ← 여기서 사용!

  // 4. 노드의 webhook() 메서드 실행
  return await WebhookHelpers.executeWebhook(
    workflow,
    webhookData,
    workflowStartNode,  // ← Webhook 노드 전달
    ...
  );
}

적용 노드 (package.json에서 webhook 메서드를 가진 노드):

• Webhook (line 578) - packages/nodes-base/nodes/Webhook/Webhook.node.ts
• HttpRequest 시리즈 (line 602-605) - packages/nodes-base/nodes/HttpRequest/
• ChatTrigger (langchain line 89) - packages/@n8n/nodes-langchain/nodes/trigger/ChatTrigger/
• McpTrigger (langchain line 52) - packages/@n8n/nodes-langchain/nodes/mcp/McpTrigger/
• Form 시리즈 - packages/nodes-base/nodes/Form/

B. Trigger 노드 (ManualTrigger, ScheduleTrigger, KafkaTrigger 등)

활성화 시: packages/cli/src/active-workflow-manager.ts:190-281

async addTriggersAndPollers(workflow, mode) {
  const triggerNodes = workflow.getTriggerNodes();  // ← 모든 trigger 노드 찾기

  for (const triggerNode of triggerNodes) {
    // TriggerContext 생성 (emit 콜백 포함)
    const triggerFunctions = this.getExecuteTriggerFunctions(...);

    // trigger() 메서드 호출
    const triggerResponse = await this.triggersAndPollers.runTrigger(
      workflow,
      triggerNode,  // ← 트리거 노드 (예: ManualTrigger, KafkaTrigger)
      triggerFunctions,
    );

    // 메모리에 계속 유지
    this.activeWorkflows.add(workflow.id, { triggerResponses: [triggerResponse] });
  }
}

emit 콜백: packages/cli/src/active-workflow-manager.ts:339-401

getExecuteTriggerFunctions(workflowData) {
  return (workflow: Workflow, node: INode) => {
    const emit = (data: INodeExecutionData[][]) => {
      // 트리거가 emit하면 워크플로우 실행
      this.workflowExecutionService.runWorkflow(
        workflowData,
        node,  // ← trigger 노드 (예: "ScheduleTrigger", "KafkaTrigger")
        data,
        ...
      );
    };
    return new TriggerContext(workflow, node, additionalData, mode, emit);
  };
}

적용 노드 (package.json에서 trigger 메서드를 가진 노드, [T] 표시):

• ManualTrigger (line 647) - packages/nodes-base/nodes/ManualTrigger/
• ScheduleTrigger (line 744) - packages/nodes-base/nodes/Schedule/
• KafkaTrigger (line 624) - packages/nodes-base/nodes/Kafka/
• RabbitMQTrigger (line 723) - packages/nodes-base/nodes/RabbitMQ/
• PostgresTrigger (line 716) - packages/nodes-base/nodes/Postgres/
• 기타 모든 *Trigger 노드 (총 약 80개)

C. Execute 노드 (GraphQL, Set, Code, Postgres 등 대부분의 노드)

실행 시: packages/core/src/execution-engine/workflow-execute.ts:1404-2100

async processRunExecutionData(workflow: Workflow) {
  // 실행 루프 - 모든 execute 노드가 여기서 실행됨
  while (this.runExecutionData.executionData!.nodeExecutionStack.length !== 0) {
    const executionData = this.runExecutionData.executionData!.nodeExecutionStack.shift();
    const executionNode = executionData.node;  // ← 노드 이름 (예: "GraphQL1", "Set", "Code2")

    // 노드 실행
    const runNodeData = await this.runNode(
      workflow,
      executionData,
      ...
    );

    // 다음 노드들을 스택에 추가
    workflow.getChildNodes(executionNode.name).forEach((childNodeName) => {
      this.addNodeToBeExecuted(workflow, { node: childNodeName });
    });
  }
}

노드 실행 상세: packages/core/src/execution-engine/workflow-execute.ts:1662-1725

private async executeNode(workflow, node: INode, ...) {
  // 1. 노드 타입 조회 (이름으로)
  const nodeType = workflow.nodeTypes.getByNameAndVersion(node.type);
  // 예: node.type = 'n8n-nodes-base.graphql' → GraphQL 클래스 반환

  // 2. ExecuteContext 생성
  const context = new ExecuteContext(workflow, node, ...);

  // 3. execute() 메서드 호출
  let data: INodeExecutionData[][];
  if (nodeType.execute) {
    data = await nodeType.execute.call(context);  // ← 노드의 execute() 실행
  }

  return { data };
}

적용 노드 (execute 메서드를 가진 모든 노드, 약 500개):

• GraphQL (line 578) - packages/nodes-base/nodes/GraphQL/GraphQL.node.ts
• Set (line 752-755) - packages/nodes-base/nodes/Set/
• Code (line 473) - packages/nodes-base/nodes/Code/Code.node.ts
• Postgres (line 714-716) - packages/nodes-base/nodes/Postgres/
• Slack (line 758-761) - packages/nodes-base/nodes/Slack/
• GoogleSheets (line 567-569) - packages/nodes-base/nodes/Google/Sheet/
• If (line 594-596) - packages/nodes-base/nodes/If/
• Switch (line 779-781) - packages/nodes-base/nodes/Switch/
• 기타 대부분의 노드

D. AI/LangChain 노드 (Agent, Tool, Memory, VectorStore 등)

특수한 실행 방식: packages/@n8n/nodes-langchain/nodes/agents/Agent/Agent.node.ts

AI 노드는 두 가지 방식으로 실행됩니다:

1. 일반 노드로 실행 (execute 메서드)

   async execute(this: IExecuteFunctions) {
   // workflow 실행 중 다른 노드처럼 실행됨
   // 위의 "C. Execute 노드" 패턴과 동일
   }

2. AI 컴포넌트로 실행 (supplyData 메서드)

   async supplyData(this: ISupplyDataFunctions, itemIndex: number) {
   // Agent, Tool, Chain 등 LangChain 객체 반환
   // 다른 AI 노드가 연결해서 사용
   return { response: agentInstance };
   }

연결 해석: packages/workflow/src/Workflow.ts

getConnectionInputData(connectionType: string, ...) {
  // AI 노드들의 동적 연결 해석
  // 예: Agent → Tool → VectorStore 연결
  const connectedNode = this.getNode(connection.node);
  const nodeType = this.nodeTypes.getByNameAndVersion(connectedNode.type);
  if (nodeType.supplyData) {
    return await nodeType.supplyData.call(context, itemIndex);
  }
}

적용 노드 (langchain package.json):

• Agent (line 6) - packages/@n8n/nodes-langchain/nodes/agents/Agent/
• ToolHttpRequest (line 77) - packages/@n8n/nodes-langchain/nodes/tools/ToolHttpRequest/
• VectorStorePinecone (line 99) - packages/@n8n/nodes-langchain/nodes/vector_store/VectorStorePinecone/
• MemoryBufferWindow (line 55) - packages/@n8n/nodes-langchain/nodes/memory/MemoryBufferWindow/
• 기타 모든 LangChain 노드 (약 100개)

노드 이름으로 검색되는 주요 위치 정리

package.json 등록 라인 번호와 실제 파일 매핑

nodes-base 주요 노드

langchain 주요 노드

결론: 모든 노드는 동일한 방식으로 사용됨

핵심 요약:

1. 노드 정의: 각 .node.ts 파일에서 클래스 정의 (640개 모두)
2. 노드 등록: package.json의 n8n.nodes 배열에 등록 (640개 모두)
3. 동적 로딩: LoadNodesAndCredentials가 서버 시작 시 자동 스캔 (640개 모두)
4. 런타임 참조:
   • 노드 이름(문자열)으로 접근: workflow.getNode("GraphQL1")
   • 노드 타입(문자열)으로 클래스 조회: nodeTypes.getByNameAndVersion("n8n-nodes-base.graphql")
5. 실행:
   • Webhook 노드 → live-webhooks.ts에서 HTTP 요청 수신 시 실행
   • Trigger 노드 → active-workflow-manager.ts에서 활성화 후 emit 콜백으로 실행
   • Execute 노드 → workflow-execute.ts의 실행 루프에서 순차 실행
   • AI 노드 → 일반 execute + supplyData 두 가지 방식

GraphQL 예시:

• ❌ 직접 import 없음: import { GraphQL } from '...' (이런 코드는 존재하지 않음)
• ✅ 동적 로딩: LoadNodesAndCredentials → NodeTypes 레지스트리
• ✅ 이름으로 참조: workflow.getNode("GraphQL1") → GraphQL 노드 인스턴스
• ✅ 타입으로 조회: nodeTypes.getByNameAndVersion("n8n-nodes-base.graphql") → GraphQL 클래스
• ✅ 실행: workflow-execute.ts의 executeNode()에서 graphqlNode.execute() 호출

이 패턴은 모든 640개 노드에 동일하게 적용됩니다.

문서 버전: 3.0 | 생성일: 2026-02-04 | 업데이트: 2026-02-09 | 소스: 실제 코드베이스 분석

목차

• 개요
• 핵심 기능
  • 1. Observability (관찰성)
  • 2. Prompt Management (프롬프트 관리)
  • 3. Evaluation (평가)
• 플랫폼 기능
• 통합 및 연동
• 시작하기
• 사용 사례
• 보안 및 컴플라이언스

개요

Langfuse는 LLM(Large Language Model) 애플리케이션을 위한 오픈소스 엔지니어링 플랫폼입니다. 팀이 협업하여 LLM 애플리케이션을 디버깅, 분석, 반복 개선할 수 있도록 돕는 통합 솔루션을 제공합니다.

주요 특징

• ✅ 완전한 오픈소스: GitHub에서 공개되어 있으며, 커스텀 통합을 위한 Public API 제공
• ✅ 프로덕션 최적화: 최소한의 성능 오버헤드로 설계
• ✅ 우수한 SDK: Python 및 JavaScript 네이티브 SDK 제공
• ✅ 프레임워크 지원: OpenAI SDK, LangChain, LlamaIndex 등 주요 프레임워크와 통합
• ✅ 멀티모달 지원: 텍스트, 이미지 등 다양한 모달리티 추적
• ✅ 자체 호스팅 가능: 클라우드 또는 온프레미스 배포 가능

핵심 기능

1. Observability (관찰성)

LLM 애플리케이션의 모든 동작을 투명하게 추적하고 모니터링할 수 있는 기능입니다.

주요 기능

📊 Trace (추적)

• 완전한 가시성: 모든 LLM 호출, API 호출, 검색(retrieval), 임베딩 등을 추적
• 계층적 구조: 복잡한 호출 체인을 트리 구조로 시각화
• 타임라인 뷰: 각 단계의 실행 시간과 지연 시간을 시각적으로 분석
• 비용 추적: 토큰 사용량 및 API 비용을 실시간으로 모니터링

🔄 Sessions (세션)

• 대화 추적: 멀티턴 대화나 에이전트 워크플로우를 세션으로 그룹화
• 사용자 여정 분석: 전체 사용자 인터랙션 흐름 파악
• 컨텍스트 유지: 대화 히스토리와 컨텍스트를 한눈에 확인

👤 User Tracking (사용자 추적)

• 사용자별 분석: userId를 통해 개별 사용자의 비용과 사용량 모니터링
• 딥링크 생성: 사용자별 뷰로 직접 연결되는 링크 생성 가능
• 사용 패턴 분석: 사용자 행동 및 선호도 파악

🤖 Agent Graphs (에이전트 그래프)

• 워크플로우 시각화: 복잡한 에이전트 워크플로우를 그래프로 표현
• 의사결정 추적: 에이전트의 의사결정 경로 및 로직 분석
• 디버깅 용이성: 에이전트 실행 흐름에서 문제점 빠르게 파악

📈 Dashboard (대시보드)

• 실시간 메트릭: 품질, 비용, 지연시간 등 핵심 지표를 대시보드에서 모니터링
• 커스텀 뷰: 필요한 지표만 선택하여 맞춤형 대시보드 구성
• 알림 설정: 임계값 초과 시 알림 수신

통합 방법

Python SDK 예제:

from langfuse import Langfuse

# 초기화
langfuse = Langfuse(
    public_key="pk-lf-...",
    secret_key="sk-lf-..."
)

# Trace 생성
trace = langfuse.trace(
    name="my-llm-app",
    user_id="user-123",
    metadata={"environment": "production"}
)

# Generation 추적
generation = trace.generation(
    name="chat-completion",
    model="gpt-4",
    input={"messages": [{"role": "user", "content": "Hello"}]},
    output={"content": "Hi there!"},
    usage={"prompt_tokens": 10, "completion_tokens": 5}
)

JavaScript/TypeScript SDK 예제:

import { Langfuse } from "langfuse";

const langfuse = new Langfuse({
  publicKey: "pk-lf-...",
  secretKey: "sk-lf-..."
});

const trace = langfuse.trace({
  name: "my-llm-app",
  userId: "user-123",
  metadata: { environment: "production" }
});

const generation = trace.generation({
  name: "chat-completion",
  model: "gpt-4",
  input: { messages: [{ role: "user", content: "Hello" }] },
  output: { content: "Hi there!" },
  usage: { promptTokens: 10, completionTokens: 5 }
});

지원 통합

• Native SDKs (Python, JavaScript/TypeScript)
• 50+ 라이브러리/프레임워크 통합
• OpenTelemetry 지원
• LLM Gateway (LiteLLM 등)

2. Prompt Management (프롬프트 관리)

프롬프트를 체계적으로 관리하고 버전 관리하며, 팀과 협업할 수 있는 기능입니다.

주요 기능

📝 Create & Version Control (생성 및 버전 관리)

• UI/API/SDK 지원: 다양한 방법으로 프롬프트 생성 및 수정
• 버전 히스토리: 모든 변경 사항을 추적하고 이전 버전으로 롤백 가능
• 협업 편집: 팀원들과 함께 프롬프트를 편집하고 리뷰
• 변경 추적: 누가, 언제, 무엇을 변경했는지 완벽하게 기록

🚀 Deploy (배포)

• 환경별 라벨: production, staging, development 등 환경별로 프롬프트 배포
• 코드 변경 없이 배포: 라벨만 변경하여 즉시 프롬프트 업데이트
• A/B 테스팅: 여러 프롬프트 버전을 동시에 테스트
• 점진적 롤아웃: 일부 사용자에게만 먼저 배포하여 안전하게 테스트

🎮 Playground (플레이그라운드)

• 인터랙티브 테스트: 프롬프트를 즉시 테스트하고 결과 확인
• 모델 비교: 여러 LLM 모델에서 동일한 프롬프트 테스트
• 파라미터 조정: Temperature, max_tokens 등 파라미터를 조정하며 실험
• 빠른 반복: 코드 작성 없이 빠르게 프롬프트 개선

📊 Metrics (메트릭)

• 성능 비교: 프롬프트 버전별 지연시간, 비용, 품질 비교
• 통계 분석: 평균, 중앙값, 백분위수 등 상세 통계
• 시각화: 그래프와 차트로 성능 변화 추이 파악

🔗 Link with Traces (트레이스 연동)

• 컨텍스트 이해: 프롬프트가 실제 애플리케이션에서 어떻게 사용되는지 확인
• 실제 성능 측정: 프로덕션 환경에서의 프롬프트 성능 분석
• 문제 진단: 특정 프롬프트로 인한 문제를 빠르게 식별

🧪 Experiments (실험)

• 데이터셋 테스트: 데이터셋에 대해 프롬프트와 모델 조합을 체계적으로 테스트
• 자동화된 평가: 설정한 기준에 따라 자동으로 성능 평가
• 결과 비교: 여러 실험 결과를 한 번에 비교

고급 기능

🔧 Variables (변수)

• 동적 프롬프트: 변수를 사용하여 상황에 맞게 프롬프트 커스터마이징
• 재사용성: 공통 부분을 변수로 관리하여 중복 제거

# 프롬프트 템플릿
"""
당신은 {{role}}입니다.
사용자 질문: {{user_question}}
답변 형식: {{format}}
"""

# 사용 시
prompt = langfuse.get_prompt("assistant-template")
compiled = prompt.compile(
    role="친절한 AI 어시스턴트",
    user_question="Python이란?",
    format="간단명료하게"
)

🧩 Composability (구성 가능성)

• 프롬프트 조합: 여러 프롬프트를 조합하여 복잡한 프롬프트 생성
• 모듈화: 공통 프롬프트 부분을 모듈로 분리하여 관리

📋 Message Placeholders (메시지 플레이스홀더)

• 대화 템플릿: 채팅 형식의 프롬프트에서 메시지 구조 정의
• 역할 관리: system, user, assistant 역할별 메시지 관리

⚙️ Config (설정)

• 모델 설정: temperature, max_tokens 등 모델 파라미터를 프롬프트와 함께 저장
• 일관성: 프롬프트와 설정을 함께 관리하여 재현성 보장

🔔 Webhooks & Integrations

• 자동화: 프롬프트 변경 시 Slack 알림, CI/CD 트리거 등
• GitHub 연동: 프롬프트를 Git 리포지토리와 동기화
• n8n 노드: 노코드 워크플로우 자동화

💾 Caching (캐싱)

• 성능 최적화: 자주 사용되는 프롬프트 결과를 캐싱
• 비용 절감: 중복 API 호출 방지

📁 Folders (폴더)

• 조직화: 프롬프트를 폴더로 구조화하여 관리
• 팀별 분리: 팀이나 프로젝트별로 프롬프트 분류

사용 예제

프롬프트 생성 및 가져오기:

from langfuse import Langfuse

langfuse = Langfuse()

# 프롬프트 가져오기
prompt = langfuse.get_prompt(
    name="customer-support-agent",
    label="production"  # 또는 version=3
)

# 프롬프트 컴파일 (변수 치환)
compiled_prompt = prompt.compile(
    customer_name="홍길동",
    issue_type="결제 문제"
)

# LLM에 전달
response = openai.chat.completions.create(
    model="gpt-4",
    messages=compiled_prompt
)

3. Evaluation (평가)

LLM 애플리케이션의 품질을 측정하고 개선하기 위한 체계적인 평가 시스템입니다.

주요 평가 방법

🤖 LLM-as-a-Judge

• 자동화된 평가: 다른 LLM을 사용하여 출력물의 품질을 자동으로 평가
• 다양한 기준: 정확성, 관련성, 일관성, 유해성 등 다양한 기준으로 평가
• 확장성: 대량의 데이터를 빠르게 평가 가능
• 커스터마이징: 도메인 특화 평가 기준 설정 가능

예제:

# LLM-as-a-Judge 평가 설정
langfuse.score(
    trace_id="trace-123",
    name="answer-quality",
    value=0.85,
    comment="답변이 정확하고 관련성이 높음"
)

👥 Annotation Queues (어노테이션 큐)

• 휴먼 평가: 사람이 직접 출력물을 검토하고 평가
• 베이스라인 구축: 자동화된 평가의 기준이 되는 골드 스탠다드 생성
• 팀 협업: 여러 평가자가 동시에 작업 가능
• 일관성 관리: 평가 가이드라인을 통해 평가자 간 일관성 유지

📊 Scores via UI/API/SDK

• 유연한 입력: UI, API, SDK를 통해 점수 입력
• 다양한 타입: 숫자형, 불린형, 범주형 점수 지원
• 메타데이터: 점수와 함께 추가 정보 저장

API 예제:

POST /api/public/scores
{
  "traceId": "trace-123",
  "name": "user-satisfaction",
  "value": 1,
  "dataType": "BOOLEAN",
  "comment": "사용자가 답변에 만족함"
}

SDK 예제:

langfuse.score(
    trace_id="trace-123",
    name="hallucination-check",
    value=0,
    data_type="NUMERIC",
    comment="환각 없음"
)

👍 User Feedback (사용자 피드백)

• 실시간 수집: 사용자로부터 직접 피드백 수집
• 브라우저 SDK: 프론트엔드에서 바로 피드백 전송
• 암묵적 피드백: 클릭, 체류 시간 등 행동 데이터 수집
• 명시적 피드백: 좋아요/싫어요, 별점, 텍스트 피드백 등

브라우저 SDK 예제:

import { Langfuse } from "langfuse";

const langfuse = new Langfuse({
  publicKey: "pk-lf-..."
});

// 사용자 피드백 전송
langfuse.score({
  traceId: "trace-123",
  name: "user-feedback",
  value: 1, // 좋아요
  comment: "정확한 답변이었어요!"
});

📈 Score Analytics (점수 분석)

• 트렌드 분석: 시간에 따른 품질 변화 추이 파악
• 분포 확인: 점수 분포를 통해 성능 패턴 이해
• 비교 분석: 버전 간, 모델 간 성능 비교
• 대시보드: 시각적으로 평가 결과 확인

Experiments (실험)

📚 Datasets (데이터셋)

• 테스트 케이스 관리: 일관된 테스트를 위한 데이터셋 구축
• 버전 관리: 데이터셋 변경 사항 추적
• 다양한 시나리오: Edge case, 일반적인 케이스 등 포괄적으로 커버
• 재사용: 동일한 데이터셋으로 반복 테스트

데이터셋 생성:

# 데이터셋 생성
dataset = langfuse.create_dataset(
    name="customer-support-qa",
    description="고객 지원 QA 테스트 케이스"
)

# 아이템 추가
dataset.create_item(
    input={"question": "환불은 어떻게 하나요?"},
    expected_output={"answer": "구매일로부터 14일 이내 환불 가능합니다."}
)

🧪 Experiments via SDK/UI

• 체계적 테스트: 프롬프트와 모델 조합을 데이터셋에 대해 테스트
• 자동화: 스크립트를 통해 실험 자동 실행
• UI 지원: 코드 없이 UI에서 실험 실행 가능
• 결과 비교: 여러 실험을 나란히 비교

실험 실행:

from langfuse import Langfuse

langfuse = Langfuse()

# 데이터셋 로드
dataset = langfuse.get_dataset("customer-support-qa")

# 실험 실행
for item in dataset.items:
    # 프롬프트 가져오기
    prompt = langfuse.get_prompt("support-agent", version=2)

    # LLM 호출
    response = llm.generate(
        prompt=prompt.compile(**item.input),
        trace_id=item.id
    )

    # 결과 평가
    langfuse.score(
        trace_id=item.id,
        name="accuracy",
        value=evaluate(response, item.expected_output)
    )

평가 워크플로우

graph TD
    A[프로덕션 트레이스] --> B{평가 필요}
    B --> C[LLM-as-a-Judge]
    B --> D[Annotation Queue]
    B --> E[User Feedback]
    C --> F[Score 생성]
    D --> F
    E --> F
    F --> G[Analytics Dashboard]
    G --> H{문제 발견}
    H -->|Yes| I[Dataset 추가]
    I --> J[Experiment 실행]
    J --> K[개선된 버전]
    K --> L[프로덕션 배포]
    H -->|No| M[모니터링 계속]

플랫폼 기능

Metrics (메트릭)

📊 Custom Dashboards (커스텀 대시보드)

• 맞춤형 뷰: 필요한 메트릭만 선택하여 대시보드 구성
• 실시간 업데이트: 데이터가 실시간으로 반영
• 공유: 팀원들과 대시보드 공유
• 필터링: 날짜, 사용자, 모델 등 다양한 기준으로 필터링

📡 Metrics API

• 프로그래밍 방식 접근: API를 통해 메트릭 데이터 조회
• 통합: 자체 모니터링 시스템에 통합
• 자동화: 알림, 리포팅 자동화

# Metrics API 사용 예제
import requests

response = requests.get(
    "https://cloud.langfuse.com/api/public/metrics",
    headers={"Authorization": "Bearer sk-lf-..."},
    params={
        "from": "2024-01-01",
        "to": "2024-01-31",
        "groupBy": "model"
    }
)

metrics = response.json()

🔌 Analytics 통합

• PostHog: 제품 분석 플랫폼과 연동
• Mixpanel: 사용자 행동 분석 도구와 연동
• 커스텀 통합: Webhook을 통해 다른 도구와 연동

API & Data Platform

💾 Export (데이터 내보내기)

UI에서 내보내기:

• CSV, JSON 형식으로 데이터 다운로드
• 날짜 범위, 필터 조건 지정
• 대량 데이터 처리

Blob Storage로 내보내기:

• S3, Azure Blob Storage, GCS 등 지원
• 자동화된 정기 백업
• 장기 보관 및 규정 준수

# 데이터 내보내기 설정
langfuse.configure_export(
    destination="s3://my-bucket/langfuse-exports",
    schedule="daily",
    format="parquet"
)

🔍 Observations API

• 세밀한 데이터 접근: 개별 관찰(observation) 데이터에 접근
• 필터링: 복잡한 쿼리로 원하는 데이터만 추출
• 페이지네이션: 대량 데이터를 효율적으로 처리

📖 Public API

• 완전한 기능: UI에서 할 수 있는 거의 모든 작업을 API로 수행
• RESTful: 표준 REST API 디자인
• 문서화: 상세한 API 레퍼런스 제공

API Reference: https://api.reference.langfuse.com

🔎 Query via SDKs

• Python/JS SDK: SDK를 통해 데이터 쿼리
• 타입 안전성: TypeScript 타입 지원
• 편의성: 복잡한 쿼리를 간단하게 작성

# SDK로 데이터 쿼리
traces = langfuse.fetch_traces(
    name="chat-completion",
    from_timestamp="2024-01-01",
    to_timestamp="2024-01-31",
    user_id="user-123"
)

for trace in traces:
    print(f"Trace: {trace.id}, Cost: {trace.cost}")

🤝 MCP Server (Model Context Protocol)

• 표준 프로토콜: MCP를 통한 데이터 접근
• 상호 운용성: 다양한 도구와 쉽게 통합

Administration (관리)

🔐 Authentication & SSO

• 다양한 인증 방식:
  • Email/Password
  • Google OAuth
  • GitHub OAuth
  • SAML 2.0 (엔터프라이즈)
  • OIDC (엔터프라이즈)
• Multi-Factor Authentication (MFA): 추가 보안 계층
• Session 관리: 세션 타임아웃, 동시 로그인 제한

👥 Access Control (RBAC)

• 역할 기반 접근 제어:
  • Owner: 모든 권한
  • Admin: 관리 권한
  • Member: 일반 사용자
  • Viewer: 읽기 전용
• 세밀한 권한: 프로젝트, 데이터셋, 프롬프트 등 리소스별 권한 설정
• 팀 관리: 팀 생성 및 멤버 관리

🔄 SCIM & Org API

• 자동 프로비저닝: SCIM을 통한 사용자 자동 추가/제거
• 디렉토리 동기화: Azure AD, Okta 등과 동기화
• 조직 API: 프로그래밍 방식으로 조직 관리

📝 Audit Logs

• 모든 활동 기록: 누가, 언제, 무엇을 했는지 완벽하게 추적
• 규정 준수: SOC 2, ISO 27001 등 규정 요구사항 충족
• 보안 모니터링: 의심스러운 활동 감지

🗑️ Data Deletion & Retention

• 데이터 삭제 정책: 자동 또는 수동 데이터 삭제
• 보존 기간 설정: 데이터 유형별 보존 기간 설정
• GDPR 준수: 사용자 데이터 삭제 권리 보장

# 데이터 보존 정책 설정
langfuse.set_retention_policy(
    traces=90,  # 90일 후 삭제
    scores=365,  # 1년 후 삭제
    datasets="永久"  # 영구 보존
)

🔌 LLM Connections

• 모델 프로바이더 연동: OpenAI, Anthropic, Azure OpenAI 등
• API 키 관리: 안전한 키 저장 및 관리
• 자동 토큰 계산: 연동된 모델의 토큰 사용량 자동 계산

💰 Spend Alerts

• 비용 알림: 설정한 임계값 초과 시 알림
• 예산 관리: 프로젝트별, 사용자별 예산 설정
• 실시간 모니터링: 현재 지출 현황 확인

📊 Billable Units

• 투명한 과금: 어떻게 비용이 계산되는지 명확히 표시
• 사용량 추적: 트레이스, 스코어, 저장 용량 등 사용량 확인
• 비용 최적화: 사용 패턴 분석을 통한 비용 절감

통합 및 연동

프레임워크 통합

🦜 LangChain

from langfuse.langchain import LangfuseCallbackHandler

handler = LangfuseCallbackHandler(
    public_key="pk-lf-...",
    secret_key="sk-lf-..."
)

# LangChain 체인에 추가
chain.run(input="Hello", callbacks=[handler])

🦙 LlamaIndex

from llama_index.core import set_global_handler

set_global_handler("langfuse")

# 이후 모든 LlamaIndex 호출이 자동으로 추적됨

🌐 OpenAI SDK

from langfuse.openai import openai

# OpenAI SDK를 래핑
client = openai.OpenAI()

# 기존 코드 그대로 사용하면 자동 추적
response = client.chat.completions.create(
    model="gpt-4",
    messages=[{"role": "user", "content": "Hello"}]
)

⚡ Vercel AI SDK

import { createOpenAI } from '@ai-sdk/openai';
import { observeVercelAI } from 'langfuse';

const openai = observeVercelAI(createOpenAI({
  apiKey: process.env.OPENAI_API_KEY
}));

🔧 Instructor

from instructor import patch
from langfuse.openai import openai

client = patch(openai.OpenAI())

# Pydantic 모델과 함께 사용

🚀 LiteLLM (Gateway)

import litellm
from litellm.integrations.langfuse import LangfuseLogger

litellm.success_callback = ["langfuse"]
litellm.failure_callback = ["langfuse"]

# 이후 모든 LiteLLM 호출이 자동 추적
response = litellm.completion(
    model="gpt-4",
    messages=[{"role": "user", "content": "Hello"}]
)

노코드 플랫폼 통합

🎯 Dify

• Langfuse를 Dify 워크플로우에 연동
• 시각적으로 LLM 애플리케이션 구축하면서 자동 추적

🌊 Flowise

• Flowise 노드에 Langfuse 추가
• 드래그 앤 드롭으로 LLM 앱 구축 + 모니터링

🌐 Langflow

• Langflow 컴포넌트와 통합
• 플로우 실행 자동 추적

기타 통합

📊 PostHog

• 제품 분석과 LLM 메트릭 결합
• 사용자 행동과 AI 성능 상관관계 분석

📈 Mixpanel

• 이벤트 추적과 LLM 데이터 통합
• 코호트 분석 및 퍼널 분석

시작하기

개발 라이프사이클별 가이드

PoC → 개발 → 테스트 → 프로덕션
 ↓      ↓      ↓        ↓
관찰   프롬프트  평가    모니터링
      관리     실험

1단계: 트레이싱 설정 (모든 단계)

빠른 시작:

pip install langfuse

from langfuse import Langfuse

langfuse = Langfuse(
    public_key="your-public-key",
    secret_key="your-secret-key"
)

# 첫 번째 트레이스
trace = langfuse.trace(name="my-app")

권장사항:

• ✅ 개발 초기부터 트레이싱 설정
• ✅ 환경별로 프로젝트 분리 (dev, staging, prod)
• ✅ 의미 있는 이름과 메타데이터 추가

2단계: 프롬프트 관리 도입 (개발 단계)

시기: 프롬프트가 어느 정도 안정화되기 시작할 때

단계:

1. 기존 프롬프트를 Langfuse에 등록
2. 코드에서 프롬프트 가져오기로 변경
3. 팀과 함께 프롬프트 개선
4. 버전 관리 시작

# Before
prompt = "당신은 고객 지원 AI입니다..."

# After
prompt = langfuse.get_prompt("customer-support", label="production")

3단계: 평가 설정 (테스트/프로덕션 단계)

개발 환경:

1. 테스트 데이터셋 구축
2. 실험 실행
3. 품질 메트릭 정의

프로덕션 환경:

1. 사용자 피드백 수집
2. LLM-as-a-Judge 설정
3. 정기적인 어노테이션

단계별 체크리스트

PoC 단계

• Langfuse 계정 생성
• 기본 트레이싱 설정
• 첫 번째 트레이스 생성
• 대시보드에서 데이터 확인

개발 단계

• 프롬프트를 Langfuse로 이관
• 버전 관리 시작
• Playground에서 테스트
• 팀원 초대 및 권한 설정

테스트 단계

• 테스트 데이터셋 구축
• 평가 기준 정의
• 실험 실행
• 결과 분석

프로덕션 단계

• 사용자 피드백 시스템 구축
• 모니터링 대시보드 설정
• 알림 설정 (비용, 오류 등)
• 정기 리뷰 프로세스 수립

사용 사례

1. 고객 지원 챗봇

과제:

• 다양한 질문 유형 처리
• 일관된 답변 품질 유지
• 비용 관리

Langfuse 활용:

# 1. 대화 추적
trace = langfuse.trace(
    name="customer-support",
    user_id=customer_id,
    session_id=conversation_id,
    metadata={"channel": "web", "language": "ko"}
)

# 2. 프롬프트 관리
prompt = langfuse.get_prompt("support-agent", label="production")

# 3. 의도 분류
classification = trace.span(
    name="intent-classification",
    input=user_message
)

# 4. 답변 생성
response = trace.generation(
    name="response-generation",
    model="gpt-4",
    input=prompt.compile(
        user_message=user_message,
        user_history=history
    )
)

# 5. 사용자 피드백 수집
langfuse.score(
    trace_id=trace.id,
    name="user-satisfaction",
    value=user_rating
)

결과:

• 📊 대화당 평균 비용 30% 감소
• ⭐ 사용자 만족도 15% 향상
• 🚀 신규 프롬프트 배포 시간 70% 단축

2. 문서 검색 및 요약 (RAG)

과제:

• 관련 문서 정확하게 검색
• 환각(hallucination) 방지
• 답변 품질 측정

Langfuse 활용:

trace = langfuse.trace(name="rag-pipeline")

# 1. 문서 검색
retrieval = trace.span(
    name="document-retrieval",
    input={"query": user_question},
    metadata={"top_k": 5}
)
docs = vector_db.search(user_question, k=5)
retrieval.end(output={"retrieved_docs": len(docs)})

# 2. 리랭킹
reranking = trace.span(name="reranking")
ranked_docs = reranker.rank(docs, user_question)
reranking.end(output={"top_docs": ranked_docs[:3]})

# 3. 답변 생성
generation = trace.generation(
    name="answer-generation",
    model="gpt-4",
    input={
        "question": user_question,
        "context": ranked_docs
    }
)

# 4. 환각 체크 (LLM-as-a-Judge)
langfuse.score(
    trace_id=trace.id,
    name="hallucination-check",
    value=hallucination_score
)

결과:

• ✅ 환각 감소 40%
• 🎯 답변 정확도 25% 향상
• 📈 검색 성능 실시간 모니터링

3. 코드 생성 어시스턴트

과제:

• 다양한 프로그래밍 언어 지원
• 코드 품질 보장
• 사용자별 컨텍스트 유지

Langfuse 활용:

# 세션으로 연속된 코딩 세션 추적
trace = langfuse.trace(
    name="code-assistant",
    session_id=coding_session_id,
    user_id=developer_id
)

# 컨텍스트 수집
context_span = trace.span(name="context-gathering")
code_context = get_project_context(project_id)
context_span.end(output=code_context)

# 프롬프트 선택 (언어별)
prompt = langfuse.get_prompt(
    f"code-gen-{programming_language}",
    label="production"
)

# 코드 생성
generation = trace.generation(
    name="code-generation",
    model="gpt-4",
    input=prompt.compile(
        task=user_request,
        context=code_context,
        language=programming_language
    )
)

# 코드 품질 평가
langfuse.score(
    trace_id=trace.id,
    name="code-quality",
    value=static_analysis_score
)

결과:

• 💻 코드 생성 성공률 85%
• 🐛 버그 발생률 50% 감소
• ⚡ 개발자 생산성 2배 향상

4. 콘텐츠 생성 플랫폼

과제:

• 브랜드 톤앤매너 일관성
• 다양한 콘텐츠 형식 지원
• A/B 테스트

Langfuse 활용:

# A/B 테스트를 위한 프롬프트 버전
import random

version = "A" if random.random() < 0.5 else "B"
prompt = langfuse.get_prompt(
    "content-generator",
    label=f"experiment-{version}"
)

trace = langfuse.trace(
    name="content-generation",
    metadata={"experiment_group": version}
)

# 콘텐츠 생성
generation = trace.generation(
    name="generate-content",
    model="gpt-4",
    input=prompt.compile(
        topic=content_topic,
        tone=brand_tone,
        format=content_format
    )
)

# 사용자 참여도 추적
langfuse.score(
    trace_id=trace.id,
    name="engagement-rate",
    value=calculate_engagement(content_id)
)

결과:

• 📝 콘텐츠 생산량 3배 증가
• 🎨 브랜드 일관성 95% 달성
• 📊 A/B 테스트로 참여도 20% 향상

보안 및 컴플라이언스

🔒 보안 인증

• SOC 2 Type II: 데이터 보안 및 가용성 인증
• ISO 27001: 정보 보안 관리 시스템 인증
• GDPR 준수: 유럽 개인정보 보호 규정 완전 준수
• HIPAA 준수: 의료 데이터 보호 규정 준수 (엔터프라이즈)

🛡️ 데이터 보호

• 암호화:
  • 전송 중: TLS 1.3
  • 저장 중: AES-256
• 데이터 격리: 프로젝트별 완전한 데이터 분리
• 접근 제어: 세밀한 RBAC 및 IP 화이트리스트
• 감사 로그: 모든 접근 및 변경 사항 기록

🏢 자체 호스팅

• 완전한 제어: 자체 인프라에서 운영
• 데이터 주권: 데이터가 외부로 나가지 않음
• 커스터마이징: 필요에 맞게 수정 가능
• 지원 옵션: 엔터프라이즈 지원 제공

자체 호스팅 옵션:

• Docker Compose
• Kubernetes (Helm Chart 제공)
• AWS, GCP, Azure 등 클라우드 플랫폼

📋 데이터 거버넌스

• 데이터 레지던시: 데이터 저장 위치 선택 가능
• 백업: 자동 백업 및 재해 복구
• 삭제 권리: GDPR 삭제 권리 지원
• 데이터 이동성: 언제든 데이터 내보내기 가능

커뮤니티 및 지원

📚 문서 및 리소스

• 공식 문서: https://langfuse.com/docs
• API 레퍼런스: https://api.reference.langfuse.com
• Python SDK: https://python.reference.langfuse.com
• JS/TS SDK: https://js.reference.langfuse.com

💬 커뮤니티

• Discord: 실시간 채팅 및 질문
• GitHub Discussions: 기술적인 논의
• GitHub Issues: 버그 리포트 및 기능 요청

🎯 시작하기

1. 무료 계정 생성: https://cloud.langfuse.com
2. 데모 프로젝트 체험: https://langfuse.com/docs/demo
3. 10분 비디오 데모: https://langfuse.com/watch-demo

📞 엔터프라이즈 문의

• 영업 문의: https://langfuse.com/talk-to-us
• 지원: support@langfuse.com
• 채용: https://langfuse.com/careers

가격 정책

💸 무료 티어

• 월 50,000개 트레이스
• 모든 핵심 기능
• 커뮤니티 지원

📊 Pro 티어

• 추가 트레이스당 종량제
• 우선 지원
• 고급 분석 기능

🏢 엔터프라이즈

• 무제한 사용
• 전담 지원
• SSO, SCIM, 감사 로그
• 커스텀 계약

최신 가격: https://langfuse.com/pricing

로드맵

Langfuse는 활발하게 개발 중이며, 커뮤니티 피드백을 기반으로 계속 발전하고 있습니다.

최신 로드맵: https://langfuse.com/docs/roadmap

최근 추가된 기능 (Changelog):

• MCP (Model Context Protocol) 지원
• 향상된 에이전트 그래프 시각화
• 프롬프트 GitHub 통합
• 커스텀 대시보드 빌더
• 성능 최적화

계획된 기능:

• 더 많은 LLM 프로바이더 통합
• 고급 평가 기능
• 실시간 모니터링 강화
• AI 기반 인사이트

결론

Langfuse는 LLM 애플리케이션을 개발하고 운영하는 데 필요한 모든 도구를 제공하는 종합 플랫폼입니다.

핵심 가치:

• 🔍 투명성: 애플리케이션 내부를 완벽하게 이해
• 🚀 속도: 빠른 반복과 개선
• 📊 품질: 체계적인 평가와 모니터링
• 🤝 협업: 팀과 함께 더 나은 AI 만들기
• 🔒 신뢰: 엔터프라이즈급 보안과 컴플라이언스

시작이 간단합니다:

pip install langfuse

from langfuse import Langfuse
langfuse = Langfuse()
# 이제 시작입니다!

더 나은 LLM 애플리케이션을 만들기 위한 여정을 Langfuse와 함께하세요! 🚀

1. 터미널에서 실행

   npx add-skill vercel-labs/agent-skills

   

2. 선택된 스킬 인스톨

   • React&Nest js 모범사례
   • 웹 디자인 가이드 라인

     ◆  Select skills to install
     │  ◻ vercel-react-best-practices (React and Next.js performance optimization guidelines fro...)
     │  ◻ web-design-guidelines
     └

     

3.설치할 에이전트(IDE) 선택

  Detected 8 agents
│
◆  Select agents to install skills to
│  ◼ Antigravity (.agent/skills)
│  ◼ Claude Code
│  ◼ Codex
│  ◼ Cursor
│  ◼ Gemini CLI
│  ◼ GitHub Copilot
│  ◼ OpenCode
│  ◼ Windsurf

4. 설치 범위

   • 프로젝내
   • 전체

     ◆  Installation scope
     │  ● Project (Install in current directory (committed with your project))
     │  ○ Global

     

5. 설치 방법

• Symlink
• Copy to all agents

6. 인스톨 요약 및 실행

   ◇  Installation Summary ────────────────────────────────────────────────────╮
   │                                                                           │
   │  ~/Recent_AI/.agents/skills/vercel-react-best-practices                   │
   │    symlink → Antigravity, Claude Code, Codex, Cursor, Gemini CLI +3 more  │
   │                                                                           │
   │  ~/Recent_AI/.agents/skills/web-design-guidelines                         │
   │    symlink → Antigravity, Claude Code, Codex, Cursor, Gemini CLI +3 more  │
   │                                                                           │
   ├───────────────────────────────────────────────────────────────────────────╯
   │
   ◆  Proceed with installation?
   │  ● Yes / ○ No

   

7. 인스톨 완료 정보

• 터미널 내 설치 정보 안내
• 좌측 Agent skill 사용할 수 있는 폴더들 생성

목차

1. 빠른 시작
2. 사전 요구사항
3. 프로젝트 클론 및 설치
4. 서버 실행
5. 설치된 패키지 상세
6. 트러블슈팅

빠른 시작

새로운 PC에서 5분 안에 Agent Builder를 실행하세요.

# 1. Git Repository 클론
git clone https://github.com/ai-exploration-25/n8n_new_project.git
cd n8n_new_project/n8n

# 2. 의존성 설치
npx pnpm@10.22.0 install

# 3. 프로젝트 빌드
npx pnpm@10.22.0 build

# 4. 서버 실행
# 터미널 1: 프론트엔드 개발 서버
npx pnpm@10.22.0 dev

# 터미널 2: 백엔드 API 서버
npx pnpm@10.22.0 start

# 5. 브라우저에서 접속
# http://localhost:5678

사전 요구사항

필수 소프트웨어

참고: pnpm은 자동으로 npx를 통해 사용되므로 별도 설치 불필요

시스템 요구사항

• 메모리: 최소 4GB RAM (권장 8GB 이상)
• 디스크 공간: 최소 2GB 여유 공간
• OS: macOS, Linux, Windows (WSL2 권장)

프로젝트 클론 및 설치

1단계: Repository 클론

# HTTPS 방식 (권장)
git clone https://github.com/ai-exploration-25/n8n_new_project.git

# 또는 SSH 방식
git clone git@github.com:ai-exploration-25/n8n_new_project.git

# 프로젝트 디렉토리로 이동
cd n8n_new_project/n8n

2단계: 의존성 설치

# pnpm을 사용하여 모든 패키지 설치 (약 3-5분 소요)
npx pnpm@10.22.0 install

설치되는 패키지 수:

• 직접 의존성: 87개
• 전체 패키지 (의존성 포함): 약 1,500개

3단계: 프로젝트 빌드

# Turbo를 사용한 모노레포 빌드 (약 2-3분 소요)
npx pnpm@10.22.0 build

빌드되는 패키지: 39개 (n8n 모노레포 전체)

서버 실행

개발 모드 (권장)

옵션 1: 전체 개발 환경 (프론트엔드 + 백엔드)

두 개의 터미널이 필요합니다:

# 터미널 1: 프론트엔드 개발 서버 (Vue + Vite)
npx pnpm@10.22.0 dev

# 터미널 2: 백엔드 API 서버 (Express + n8n)
npx pnpm@10.22.0 start

옵션 2: 백엔드만 실행

npx pnpm@10.22.0 dev:be
npx pnpm@10.22.0 start

옵션 3: 프론트엔드만 실행

npx pnpm@10.22.0 dev:fe

프로덕션 모드

# 빌드된 파일로 실행
npx pnpm@10.22.0 start

접속 URL

서버가 정상적으로 실행되면 다음 주소로 접속할 수 있습니다:

프로젝트 개요

브랜딩

이 프로젝트는 n8n 워크플로우 자동화 플랫폼을 기반으로 Agent Builder로 리브랜딩되었습니다.

주요 변경사항:

• n8n 로고 → 다른 로고
• 이메일 템플릿 브랜딩 변경
• UI 텍스트 및 레이블 커스터마이징

Git 커밋 히스토리

1953adb5 feat: Replace n8n logo with Other logo in email templates
76e24ef0 feat: Replace n8n logo with Agent Builder branding
5fc3cb5a chore: Add gitignore and lefthook configuration
ffb751cc feat: Add Korean localization for n8n frontend
b5179ec0 Initial commit: n8n agent builder project

설치된 패키지 상세 분류

1. 핵심 워크플로우 패키지

2. 스키마 검증 및 타입 안정성

3. Vue.js 프론트엔드 생태계

4. LangChain AI/ML 생태계

5. AI/ML 서비스 클라이언트

6. 벡터 데이터베이스 및 임베딩

7. 백엔드 프레임워크 및 서버

8. 데이터 처리 및 변환

9. 보안 및 인증

10. 테스팅 프레임워크

11. 개발 도구

12. HTTP 클라이언트 및 네트워크

13. 파서 및 컴파일러

14. UI 컴포넌트 및 시각화

15. 유틸리티 및 헬퍼

16. 데이터베이스 및 스트리밍

17. 모니터링 및 에러 추적

설치 통계

• 총 설치된 패키지 수: 87개 (직접 의존성 86개 + devDependency 1개)
• 전체 패키지 수 (의존성 포함): 1,500개
• 주요 카테고리:
  • Vue.js 생태계: 7개
  • LangChain AI/ML: 9개
  • 테스팅: 9개
  • 데이터 처리: 8개
  • 보안: 4개
  • 백엔드: 4개

주요 사용 패턴

프론트엔드 아키텍처

Vue 3 + Pinia + Vue Router + VueUse
└── 컴포넌트 테스팅: Vue Test Utils
└── UI 컴포넌트: Vue Flow, Chart.js, AG Grid
└── 빌드: Vite + Vue Plugin

AI/ML 스택

LangChain Core
├── OpenAI, Anthropic, Cohere (LLM 제공자)
├── HuggingFace (모델 추론)
├── Pinecone, Qdrant (벡터 DB)
└── Text Splitters (텍스트 처리)

백엔드 스택

Express (웹 서버)
├── Bull (작업 큐)
├── JWT (인증)
├── WebSocket (실시간 통신)
└── Axios (HTTP 클라이언트)

테스팅 스택

Vitest (단위 테스트)
├── Playwright (E2E)
├── Nock (HTTP 목킹)
├── Testcontainers (통합 테스트)
└── MirageJS (API 목킹)

설치 명령어 히스토리

# 1차: n8n-workflow 핵심 패키지
npm install n8n-workflow --cache /tmp/npm-cache

# 2차: XSS, AI SDK 등 보안 및 AI 패키지
npm install xss minifaker @n8n_io/ai-assistant-sdk --cache /tmp/npm-cache

# 3차: LangChain 생태계
npm install jest-mock-extended @langchain/core @langchain/langgraph @langchain/classic @langchain/openai @langchain/textsplitters picocolors --cache /tmp/npm-cache

# 4차: Vue 및 핵심 유틸리티
npm install vue pinia vue-router express lodash luxon uuid moment-timezone axios vitest nock nanoid class-validator form-data xml2js jsonwebtoken ws fast-glob json-schema change-case @pinia/testing @vueuse/core @vue-flow/core @faker-js/faker @vue/test-utils vitest-mock-extended --cache /tmp/npm-cache

# 5차: 테스팅 및 UI 라이브러리
npm install @typescript-eslint/utils @typescript-eslint/rule-tester @playwright/test @storybook/vue3-vite miragejs testcontainers @lezer/common @lezer/highlight @lezer/lr @dagrejs/dagre @clack/prompts --cache /tmp/npm-cache

# 6차: LangChain 커뮤니티 및 벡터 DB
npm install @langchain/community @langchain/anthropic @langchain/aws @langchain/cohere @pinecone-database/pinecone @qdrant/js-client-rest @supabase/supabase-js @huggingface/inference @kafkajs/confluent-schema-registry --cache /tmp/npm-cache

# 7차: 유틸리티 패키지
npm install bcryptjs cheerio acorn acorn-walk bull cache-manager class-transformer cli-progress bowser basic-auth chart.js callsites chokidar amqplib alasql ag-grid-community --cache /tmp/npm-cache

# 8차: 모니터링 및 도구
npm install @modelcontextprotocol/sdk @sentry/vue @sentry/node @sentry/core @rudderstack/rudder-sdk-node @internationalized/date @mozilla/readability @vitejs/plugin-vue --cache /tmp/npm-cache

# 9차: 테스트 유틸리티
npm install jest-expect-message --save-dev --cache /tmp/npm-cache

n8n 로컬 실행 가이드

사전 요구사항

• Node.js >= 22.16
• pnpm >= 10.22.0

실행 단계

# 1. n8n 디렉토리로 이동
cd /Users/user/Desktop/n8n_repository/n8n_new_project/n8n

# 2. pnpm으로 의존성 설치 (npx 사용)
npx pnpm@10.22.0 install

# 3. 프로젝트 빌드
npx pnpm@10.22.0 build

# 4. 개발 서버 실행 (옵션 선택)
npx pnpm@10.22.0 dev           # 전체 개발 환경
npx pnpm@10.22.0 dev:be        # 백엔드만
npx pnpm@10.22.0 dev:fe        # 프론트엔드만
npx pnpm@10.22.0 dev:ai        # AI 기능만

# 또는 프로덕션 모드로 실행
npx pnpm@10.22.0 start

TypeScript 설정 수정 내역

1. composite 설정 추가

• 파일: packages/workflow/tsconfig.build.esm.json
• 변경: "composite": true 추가
• 이유: TypeScript 프로젝트 참조 요구사항

2. extends 경로 수정

• 파일: packages/@n8n/api-types/tsconfig.json
• 변경: "@n8n/typescript-config/tsconfig.common.json" → "../typescript-config/tsconfig.common.json"
• 이유: 상대 경로로 올바르게 해석되도록 수정

보안 권고사항

설치 중 발견된 취약점:

• 2개의 critical severity 취약점 발견
• 권장 조치: npm audit fix --force 실행 고려
• 주의: 일부 deprecated 패키지 경고 발생 (glob@7.2.3, rimraf@3.0.2 등)

추가 참고사항

n8n 원본 프로젝트 특징

• 패키지 매니저: pnpm (workspace 기반 모노레포)
• 빌드 시스템: Turbo
• Node 버전: >= 22.16
• 총 TypeScript 파일: 약 8,990개
• 주요 디렉토리:
  • packages/nodes-base: 3,259개 노드 파일
  • packages/cli: 1,172개 백엔드 파일
  • packages/frontend/editor-ui: 1,075개 프론트엔드 파일

현재 프로젝트 환경

• 작업 디렉토리: /Users/user/Desktop/n8n_repository/n8n_new_project
• 패키지 매니저: npm (pnpm 대신)
• 캐시 우회: --cache /tmp/npm-cache 사용 (권한 문제 회피)

마이그레이션 노트

n8n 원본은 모노레포 구조로 workspace:* 프로토콜을 사용하여 내부 패키지를 참조합니다:

• @n8n/permissions
• @n8n/config
• @n8n/db
• @n8n/di
• 기타 30+ 개의 @n8n 스코프 패키지

현재 프로젝트에서는 이러한 내부 패키지들을 직접 구현하거나 외부 대안으로 대체해야 할 수 있습니다.

트러블슈팅

일반적인 문제 해결

1. npm 캐시 권한 오류

# 오류: EACCES: permission denied, mkdir '/Users/user/.npm/_cacache/...'
# 해결: 임시 캐시 디렉토리 사용
npm install --cache /tmp/npm-cache

2. TypeScript 컴파일 오류

오류 A: Referenced project must have setting "composite": true

# 파일: packages/workflow/tsconfig.build.esm.json
# 해결: "composite": true 추가됨 (이미 수정 완료)

오류 B: File '@n8n/typescript-config/tsconfig.common.json' not found

# 파일: packages/@n8n/api-types/tsconfig.json
# 해결: 상대 경로로 변경됨 (이미 수정 완료)

3. 포트 충돌

# 오류: Port 5678 is already in use
# 해결 1: 기존 프로세스 종료
lsof -ti:5678 | xargs kill -9

# 해결 2: 환경 변수로 다른 포트 사용
N8N_PORT=5679 npx pnpm@10.22.0 start

4. Node.js 버전 불일치

# 현재 버전 확인
node --version

# nvm 사용 시
nvm install 22.16
nvm use 22.16

# 또는 최신 LTS 버전
nvm install --lts

5. 빌드 실패

# 전체 정리 후 재빌드
npx pnpm@10.22.0 clean
npx pnpm@10.22.0 install
npx pnpm@10.22.0 build

6. 데이터베이스 마이그레이션 오류

# n8n은 첫 실행 시 자동으로 SQLite DB 생성
# 문제 발생 시 DB 파일 삭제 후 재시작
rm -rf ~/.n8n/database.sqlite
npx pnpm@10.22.0 start

환경 변수 설정 (선택사항)

n8n은 환경 변수 없이도 기본 설정으로 실행됩니다. 필요시 다음과 같이 설정할 수 있습니다:

# .env 파일 생성 예시 (선택사항)
N8N_PORT=5678
N8N_PROTOCOL=http
N8N_HOST=localhost
N8N_EDITOR_BASE_URL=http://localhost:5678
N8N_LOG_LEVEL=info

# 데이터베이스 설정 (기본값: SQLite)
DB_TYPE=sqlite
DB_SQLITE_DATABASE=~/.n8n/database.sqlite

# 보안 설정
N8N_BASIC_AUTH_ACTIVE=false
N8N_JWT_SECRET=<your-secret-key>

성능 최적화

개발 환경

# 백엔드만 개발할 때
npx pnpm@10.22.0 dev:be

# 프론트엔드만 개발할 때
npx pnpm@10.22.0 dev:fe

# AI 기능만 개발할 때
npx pnpm@10.22.0 dev:ai

프로덕션 환경

# 빌드 최적화
npx pnpm@10.22.0 build:deploy

# Docker 이미지 빌드 (선택사항)
npx pnpm@10.22.0 build:docker

로그 확인

# n8n 로그 위치
~/.n8n/logs/

# 실시간 로그 확인
tail -f ~/.n8n/logs/n8n.log

# 개발 모드 콘솔 출력
N8N_LOG_LEVEL=debug npx pnpm@10.22.0 start

데이터 백업

# n8n 데이터 디렉토리
~/.n8n/

# 백업 (워크플로우, 크레덴셜, 실행 이력 포함)
cp -r ~/.n8n ~/n8n-backup-$(date +%Y%m%d)

# 복원
cp -r ~/n8n-backup-YYYYMMDD ~/.n8n

추가 리소스

공식 문서

• n8n 공식 문서
• n8n GitHub Repository
• n8n Community Forum

개발 가이드

• n8n 커스텀 노드 개발
• n8n API 문서
• n8n 워크플로우 예제

이 프로젝트

• Repository: https://github.com/ai-exploration-25/n8n_new_project
• 브랜딩: Agent Builder
• 기반 버전: n8n v2.2.0

빠른 참조 명령어 모음

# === 초기 설정 ===
git clone https://github.com/ai-exploration-25/n8n_new_project.git
cd n8n_new_project/n8n
npx pnpm@10.22.0 install
npx pnpm@10.22.0 build

# === 개발 ===
npx pnpm@10.22.0 dev           # 프론트엔드 개발 서버
npx pnpm@10.22.0 start         # 백엔드 서버

# === 테스트 ===
npx pnpm@10.22.0 test          # 전체 테스트
npx pnpm@10.22.0 lint          # 린팅
npx pnpm@10.22.0 typecheck     # 타입 체크

# === 정리 ===
npx pnpm@10.22.0 clean         # 빌드 파일 정리
rm -rf node_modules            # 의존성 정리

# === 포트 확인 ===
lsof -i:5678                   # 백엔드 포트
lsof -i:8080                   # 프론트엔드 포트

생성일: 2026-01-10 마지막 업데이트: 2026-01-10 문서 버전: 2.0 대상 독자: 신규 개발자, DevOps 엔지니어 프로젝트: Agent Builder (n8n v2.2.0 기반)

[AGI의 5단계]

1단계 대화형 AI - 챗봇 AI와 대화

2단계 추론 AI - 인간 수준의 문제 해결

3단계 자율 AI - 독립적으로 작업을 수행하는 AI

4단계 혁신 AI - 새로운 방법을 개발하고, 기존 방법을 개선할 수 있는 AI

5단계 조직 AI - 전체 조직의 작업을 수행할 수 있는 AI

Claude API : https://www.developerfastlane.com/blog/how-to-use-claude-api

설치 명령어

1. 스크립트 설치 (YOLO 방식)

터미널에서 아래 명령어 입력

curl -fsSL https://opencode.ai/install | bash

가장 간단하며, macOS와 Linux 등에서 빠르게 사용 가능.

2. npm (Node.js 패키지)

npm install -g opencode-ai@latest

npm이 설치된 환경에서 실행.

3. 기타 패키지 관리자

• Bun: bun install -g opencode-ai
• pnpm: pnpm install -g opencode-ai
• Yarn: yarn global add opencode-ai
• Homebrew (macOS/Linux): brew install sst/tap/opencode
• Arch Linux: paru -S opencode-bin 선호하는 패키지 관리자를 활용.

4. Windows 수동 설치

• GitHub releases 페이지에서 최신 opencode.exe 다운로드 후 실행
• 경로: 예시 C:\opencode\opencode.exe.

설치 후 인증 및 실행

1. OpenCode 설치 후 터미널에 opencode 명령어 입력하여 실행.
2. 최초 실행 시 AI Provider 인증 필요:

   opencode auth login

   후 선택 가능한 LLM Provider(예: GPT, Claude 등) 리스트에서 연결.
3. 사용하고 싶은 프로젝트 폴더에서:

   opencode .

   혹은

   <path-to-opencode>/opencode.exe .

설치 및 실행 과정은 매우 직관적이며, 공식 사이트 문서에서 최신 방법을 확인할 수 있습니다.

vscode 설치

BMAD 개요 및 특징

BMAD는 AI 중심의 애자일 개발 방식으로, 역할별 AI 에이전트가 기획, 설계, 개발, 테스트 전 과정을 분업 협업합니다.

주요 역할로는 분석가, 프로젝트 매니저, 아키텍트, PO, 스크럼 마스터, 개발자, QA 에이전트 등이 있으며, 단계별로 일관된 컨텍스트를 유지하며 PRD 및 아키텍처 문서부터 개발 스토리 생성, 구현, 테스트를 체계화합니다.

BMAD는 특히 대규모 또는 복잡한 프로젝트에 적합하며, AI를 단순 도구가 아닌 협업 파트너로 활용하는 데 초점이 있습니다.

연관 자료

https://discuss.pytorch.kr/t/bmad-method-ai-ai/7481

https://github.com/bmad-code-org/BMAD-METHOD

SuperClaude 개요 및 특징

SuperClaude는 Anthropic의 Claude 언어 모델을 보완하는 가벼운 프레임워크로, 개발 지원을 위해 역할 기반 페르소나(persona)를 도입합니다.

각 페르소나는 고유한 사고방식, 커뮤니케이션 스타일, 도구 선호도 등을 포함해 전문가 팀처럼 Claude를 기능하게 하며, 명령어 중심 워크플로우와 컨텍스트 유지 기능을 강조합니다.

SuperClaude는 개발 중 발생하는 다양한 기술 도메인을 다루는 동시에, 장기 기억 지원과 증거 기반 판단을 통해 Claude의 한계를 보완하고, 코드 보조부터 개발 전반의 효율성 향상을 목표로 합니다.

연관 자료

https://superclaude.org/

https://github.com/SuperClaude-Org/SuperClaude_Framework

https://goddaehee.tistory.com/387

비교 및 차이점

항목

BMAD

SuperClaude

목적

AI 에이전트를 역할별로 나누어 애자일 개발 전과정 자동화 및 협업 지원

Claude 언어 모델의 한계를 보완, 다양한 페르소나로 전문화된 개발 지원

역할 체계

명확한 역할 구분(분석가, PM, 개발자, QA 등)

페르소나 기반 역할(인지 원형)로 동적 전환 및 다중 역할 가능

핵심 기술

Context-Engineered Development, Agentic Planning

페르소나, 명령어 중심 워크플로우, 장기 기억, MCP 통합

활용 분야

복잡한 소프트웨어 및 프로젝트 개발

Claude 코드 기반 개발 일반, 코드 보조 및 전문가 팀 기능 구현

컨텍스트 관리

기획부터 개발, 테스트까지 동일 컨텍스트 유지

페르소나마다 개별 컨텍스트 창 유지, 명확한 역할별 지식과 행동 양식 적용

주요 장점

개발 전 과정 흐름과 문서화 일관성, 대규모 협업 최적화

다양한 역할 전환 통한 유연성, 고도화된 판단력 및 장기 메모리로 효율성 극대화

페르소나 목록

BMAD 페르소나 목록

분석가 (Analyst)

프로젝트 매니저 (Project Manager)

아키텍트 (Architect)

PO (Product Owner)

스크럼 마스터 (Scrum Master)

개발자 (Developer)

QA 에이전트 (Quality Assurance Agent)

테스트 아키텍트 (Test Architect, QA 역할 고도화)[github: bmad-code-org/BMAD-METHOD]

SuperClaude 페르소나 목록

Architect (시스템 설계자)

Frontend Developer (프론트엔드 개발자)

Backend Developer (백엔드 개발자)

Security Specialist (보안 전문가)

Documentation Specialist (문서 전문가)

Tester / QA (테스트 및 품질 관리 담당)

Reviewer (코드 리뷰 담당)

DevOps (배포 및 운영 담당)

Release Manager (릴리스 관리 담당)

Claude Code 개요

Claude Code는 터미널 환경에 최적화된 AI 기반 코딩 도우미로, 자연어 명령으로 다양한 개발 업무를 자동화하고 생산성을 높이는 혁신적인 도구입니다.

주요 특징

• 터미널 환경 최적화: 별도 앱이나 브라우저 없이 터미널에서 직접 Claude와 대화하며 작업
• 코드 분석 및 자동화: 코드베이스 전체 분석 후 코드 생성, 리팩토링, 디버깅, 테스트, Git 관리 등 자동화
• 자연어 명령 지원: “이 함수 설명해줘”, “에러 수정해줘”, “모든 함수에 docstring 달아줘” 등 직관적 명령 가능

주요 기능

• 프로젝트 구조 및 코드 설명, 전체 파일 동시 수정
• 자동 테스트 생성 및 린트 수행
• Git 커밋, 병합, 코드 리뷰, 오류 수정 등의 작업 자연어 처리
• 대용량 프로젝트, 복잡한 코드도 대응 가능하며 코드 품질 검사 및 자동 개선 루틴 지원

공식 사이트

• https://www.anthropic.com/claude-code
• 최신 정보, 공식 문서, 릴리스 노트 확인 가능

로컬 설치 방법

사전 준비

• Node.js 18버전 이상 설치 필요
• Node.js 설치 페이지: https://nodejs.org

설치 명령어

npm install -g @anthropic-ai/claude-code

(선택) 네이티브 설치

• 맥/리눅스/WSL

  curl -fsSL https://claude.ai/install.sh | bash

• 윈도우 Powershell

  irm https://claude.ai/install.ps1 | iex

설치 상태 확인

claude doctor

실행 및 첫 로그인

1. 프로젝트 폴더로 이동 또는 새 프로젝트 생성

   mkdir ~/Projects/claude_code_test
   cd ~/Projects/claude_code_test

2. Claude Code 실행

   claude

3. 터미널 스타일 선택, 로그인 방법 선택
   초기 실행 시 Anthropic Console 로그인(이메일/비밀번호) 진행

4. 라이선스 선택

• Claude Pro/Max/Team/Enterprise 구독 계정으로 로그인 가능
• API 키 기반 과금도 가능

5. 프로젝트 환경 설정 및 권한 승인
   폴더 접근권한 요청 시 ‘Yes, proceed’ 선택

6. 터미널 최적 설정 적용 권장 (Option+Enter 줄바꿈, Visual Bell 등)

7. 시작 팁

• /init 명령어로 CLAUDE.md 생성, 작업 지침 작성 추천
• /terminal-setup 명령어로 터미널 최적화 설정 가능

유용한 명령어 및 팁

참고 링크 및 추가 정보

• 카카오 개발자 가이드: https://revfactory.github.io/claude-code-mastering/#claude-code-%EB%A7%88%EC%8A%A4%ED%84%B0%ED%95%98%EA%B8%B0
• IDE 통합 확장: https://docs.claude.com/ko/docs/claude-code/ide-integrations
• 공식 가이드/도움말: https://docs.anthropic.com/ko/docs/claude-code/overviewanthropic
• 설치 및 인증 안내: https://docs.anthropic.com/ko/docs/claude-code/setupanthropic
• 설치 및 사용법 블로그: https://www.0x00.kr/ai/claude/claude-code-install-and-simple-usage0x00+1

• [Node.js] (https://nodejs.org/ko)
• Intellij (2024.2 버전이상)
• [Claude Desktop App] (https://claude.ai/download)

Claude Desktop App 설정하기

Claude Desktop App > 설정 > 개발자 > 설정편집

// 설정정보 입력
{
    "mcpServers": {
        "jetbrains": {
        "command": "npx",
        "args": ["-y", "@jetbrains/mcp-proxy"]
        }
    }
}

Intellij 설정 성공 시 > jetbrains > running

IntelliJ 설정하기

IntelliJ > Settings > Plugins

MCP Server 설치

Settings > Tools > MCP Server > Enable 체크

Claude 연결상태 확인

바이블코딩 테스트

결과

이상으로 IntelliJ 에서 Claude 연결 후 바이블코딩 테스트하기를 마치겠습니다.

바이블코딩 연결 및 사용을 처음해봐서 부족한 부분이 많아서 댓글 달아주시면 좀 더 쉬운 방향으로 수정하겠습니다.

감사합니다.