Cloudflare Workers AI 에이전트를 구축하는 것은 단순한 AI 프롬프트 기반의 질의응답을 넘어 자율적인 워크플로우로 나아가기 위한 다음 단계입니다. AI 에이전트로 알려진 이러한 시스템은 대규모 언어 모델(LLM)을 활용하여 외부 API 도구를 호출하고, 스스로 의사결정을 내리며, 할당된 작업을 자율적으로 실행합니다. 기존에는 이러한 에이전트를 가동하려면 고성능의 무거운 서버가 필요했으나, 본 튜토리얼에서는 Cloudflare Workers와 LangChain.js 를 사용해 서버리스 방식으로 AI 에이전트를 개발하고 글로벌 에지에 배포하는 방법을 소개합니다.

요약

  • AI 에이전트 이해: 에이전트는 LLM을 활용해 스스로 최선의 동작을 판단하고 외부 API(도구/tools)를 호출하여 사용자 요청을 자율적으로 해결합니다.
  • 에지 단에서 LangChain.js 구동: LangChain.js는 가벼운 Cloudflare Workers V8 런타임 환경과 완벽히 호환됩니다.
  • 맞춤형 도구 작성: Worker의 fetch 핸들러 내부에서 작동하는 맞춤형 도구를 생성하여 데이터를 수집하거나 데이터베이스 값을 조회할 수 있습니다.
  • 서버리스 바인딩 활용: 에이전트의 대화 세션 기록을 저장하기 위해 Cloudflare D1 SQL 데이터베이스 또는 KV 저장소를 연동합니다.
  • 무한 루프 방지 및 가드레일: API 호출 비용이 무분별하게 누적되는 것을 방지하기 위해 최대 실행 횟수 및 타임아웃을 제어합니다.

AI 에이전트란 무엇인가요?

일반적인 챗봇은 사용자가 프롬프트를 전송하면 모델이 텍스트 응답을 출력하는 단순한 1:1 요청-응답 루프를 돕니다. 반면, Cloudflare Workers AI 에이전트는 자율적으로 판단하여 작동합니다. 개발자가 에이전트의 목표를 지정하고 사용할 수 있는 “도구들”(API 호출, 데이터베이스 조회, 수학적 연산 등을 수행하는 맞춤형 JavaScript 함수)을 전달하면, 모델은 이 도구 중 어떤 것을 호출할지 결정하고 그 실행 결과를 스스로 검토한 뒤, 최종 목적지에 도달할 때까지 루프를 반복합니다. 이러한 자율 에이전트 로직은 고도화된 고객 지원 시스템, 백그라운드 업무 자동화, 데이터 관리 등에 매우 적합합니다. 기본 에지 API의 시작 단계에 대해서는 Cloudflare Workers를 활용한 서버리스 API 구축 가이드를 참고하십시오.

사전 준비 사항

시작하기 전에 다음 사항이 갖춰졌는지 확인하십시오.

  • Workers 서비스가 활성화된 Cloudflare 계정 (무료 플랜으로도 충분합니다).
  • Node.js 18 이상 버전 및 Wrangler CLI 설치 (npm install -g wrangler).
  • OpenAI API 키 또는 LangChain.js가 지원하는 기타 공급업체의 인증 키.
  • JavaScript Promise 객체 및 Workers의 fetch 핸들러 구조에 대한 이해.

필요한 LangChain 라이브러리를 설치합니다. Workers 환경은 압축된 결과물의 크기 한계가 있으므로, 프레임워크 전체를 한 번에 불러오는 대신 필요한 서브패키지만 개별적으로 임포트해야 합니다.

 1{
 2  "dependencies": {
 3    "@langchain/openai": "^0.3.0",
 4    "@langchain/core": "^0.3.0",
 5    "langchain": "^0.3.0"
 6  },
 7  "devDependencies": {
 8    "wrangler": "^3.0.0"
 9  }
10}

LangChain.js를 Workers 환경에 연동하기

LangChain은 LLM 기반의 애플리케이션을 구축할 때 가장 널리 쓰이는 프레임워크입니다. JavaScript 버전인 LangChain.js는 표준 웹 API를 기반으로 설계되어 Cloudflare의 가벼운 V8 격리 런타임과 완벽하게 호환됩니다.

먼저, Worker의 fetch 핸들러 내부에서 에이전트를 초기화합니다.

 1import { ChatOpenAI } from "@langchain/openai";
 2import { initializeAgentExecutorWithOptions } from "langchain/agents";
 3import { DynamicTool } from "@langchain/core/tools";
 4
 5export default {
 6  async fetch(request, env) {
 7    // 1. Define custom tools for the agent
 8    const databaseTool = new DynamicTool({
 9      name: "DatabaseQuery",
10      description: "Queries the customer database for billing status.",
11      func: async (input) => {
12        // Query database (e.g. Cloudflare D1)
13        return `Customer ${input} billing status is Active.`;
14      }
15    });
16
17    const tools = [databaseTool];
18
19    // 2. Initialize the reasoning model
20    const model = new ChatOpenAI({ 
21      apiKey: env.OPENAI_API_KEY,
22      modelName: "gpt-4o-mini"
23    });
24
25    // 3. Create the executor
26    const executor = await initializeAgentExecutorWithOptions(tools, model, {
27      agentType: "openai-functions",
28    });
29
30    // 4. Run the query
31    const result = await executor.call({ input: "Check status for Customer 101" });
32    return Response.json(result);
33  }
34};

이 구성은 사용자와 가장 가까운 에지 위치에서 구동되므로 콜드 스타트 시간이 거의 발생하지 않습니다. 외부 OpenAI API 호출 대신 사내 전용 모델을 연동하고자 한다면 Cloudflare Workers AI 튜토리얼 을 읽어보십시오.

Worker 프로젝트 환경 설정

LangChain.js는 사내 일부 Node.js 기본 모듈에 의존하므로, nodejs_compat 플래그를 설정하기 전까지는 빌드가 실패할 수 있습니다. wrangler.toml 파일에 이 플래그와 함께 도구에서 호출할 데이터베이스 바인딩 정보를 지정합니다.

1name = "ai-agent-worker"
2main = "src/index.js"
3compatibility_date = "2024-09-23"
4compatibility_flags = ["nodejs_compat"]
5
6[[d1_databases]]
7binding = "DB"
8database_name = "agent-memory"
9database_id = "<your-database-id>"

보안을 위해 API 키를 소스 코드에 직접 기재해서는 안 됩니다. 대신 암호화된 시크릿으로 등록하십시오.

1npx wrangler secret put OPENAI_API_KEY

로컬 환경에서 코드를 테스트할 때는 저장소에 실수로 암호키가 업로드되는 것을 방지하기 위해 별도의 .dev.vars 파일(.gitignore에 추가됨)을 생성하여 키값을 명시하고 wrangler dev가 이를 조회하도록 설정합니다.

상태 관리 및 에이전트 메모리 구성

서버리스 구조인 Workers는 각 요청 사이에 기존 메모리가 지워지는 상태비저장(stateless) 구조이므로, 대화 흐름을 이어가기 위해서는 별도의 메모리 스토리지를 바인딩해야 합니다.

가장 대표적인 방법은 Cloudflare D1과 같은 서버리스 SQL 데이터베이스에 연결하는 것입니다. 에이전트가 새로운 질문을 수신하면 D1에서 대화 세션의 이전 기록을 조회하여 모델에 참조 데이터로 함께 제공하고, 모델의 결과물과 유저 입력을 다시 데이터베이스에 기록합니다. 관계형 테이블을 생성하는 상세 방법은 Cloudflare D1 에지 데이터베이스 설정 가이드를 통해 안내받으실 수 있습니다.

간단한 메모리 조회/저장 함수는 다음과 같이 정의할 수 있습니다. 먼저 데이터베이스에 대화 히스토리 테이블(CREATE TABLE messages (id INTEGER PRIMARY KEY, session_id TEXT, role TEXT, content TEXT, created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP);)을 선언한 뒤 이를 호출합니다.

 1async function loadHistory(db, sessionId) {
 2  const { results } = await db
 3    .prepare(
 4      "SELECT role, content FROM messages WHERE session_id = ? ORDER BY created_at ASC"
 5    )
 6    .bind(sessionId)
 7    .all();
 8  return results ?? [];
 9}
10
11async function saveMessage(db, sessionId, role, content) {
12  await db
13    .prepare("INSERT INTO messages (session_id, role, content) VALUES (?, ?, ?)")
14    .bind(sessionId, role, content)
15    .run();
16}

매 요청의 서두에 로딩 함수를 배치하여 기존 대화를 임포트하고, 응답 반환 전에 최종 결과를 데이터베이스에 업데이트합니다. 장기간 영구 보존할 필요가 없는 단기 대화 세션의 경우 Cloudflare KV 스토리지가 D1보다 합리적인 비용 대안이 될 수 있습니다.

운영 환경에서의 폭주 방지 및 비용 통제

에이전트는 (질문 분석 → 도구 실행 → 결과 확인)의 폐루프 상태로 연속 동작하기 때문에, 설계가 잘못될 경우 무한 루프 상태에 진입하여 토큰 요금이 과다하게 청구될 위험이 있습니다.

  • 최대 반복 횟수(Max Iterations) 설정: 에이전트가 단일 요청당 실행 가능한 루프 횟수를 명시적으로 제한합니다 (예: 최대 5회 제한).
  • 타임아웃 구성: Workers는 CPU 타임에 한계가 적용되어 있습니다. 호출되는 도구들의 실행 시간이 너무 길어지지 않도록 예외 처리를 해야 합니다.
  • 트래픽 제한(Rate Limiting) 도입: 무분별한 토큰 남용을 예방하기 위해 API 진입점 단에서 계정별 요율 한도를 구성합니다.

코드 구조에서는 아래와 같이 실행 엔진 설정으로 이 두 가지 기본 가드레일을 등록할 수 있습니다.

1const executor = await initializeAgentExecutorWithOptions(tools, model, {
2  agentType: "openai-functions",
3  maxIterations: 5,
4  earlyStoppingMethod: "generate",
5  verbose: false,
6});

maxIterations 한도를 할당해 두면 모델이 결론을 내리지 못했더라도 5번째 루프가 끝나는 시점에 루프 실행이 정지되어 비용 폭증을 방지할 수 있습니다.

대화 컨텍스트 관리에 관한 더 상세한 개발 가이드는 OpenAI API 기반의 챗봇 구축 페이지에서 다루고 있습니다.

발생하기 쉬운 오류 및 디버깅 가이드

처음 애플리케이션을 배포할 때 맞닥뜨리는 트러블슈팅의 핵심 원인들을 모았습니다.

오류 증상원인 규명해결 방안
빌드할 때 Cannot find module 'node:async_hooks' 발생nodejs_compat 플래그 설정 누락wrangler.toml 파일에 compatibility_flags = ["nodejs_compat"] 적용 및 최신 호환 날짜 추가
배포 중에 번들 용량 한도 초과 에러프레임워크 전체 패키지를 임포트함개별 모듈 단위로 스코프를 좁혀 임포트하고 (@langchain/openai) 사용하지 않는 기능 제거
OPENAI_API_KEY is not defined환경변수가 누락되었거나 로컬 환경에 .dev.vars가 없음wrangler secret put 명령어로 키 등록; 로컬의 .dev.vars에 해당 변수 추가
요청 처리 중 타임아웃 발생연동된 도구의 응답 지연 또는 무한 루프maxIterations 값을 줄이고 각 도구의 내부 로직에 시간 한도 추가
특정 도구가 분명히 있어야 하는데 에이전트가 이를 건너뜀도구 설명(description)이 직관적이지 않음모델이 해당 도구의 목적을 정확히 식별할 수 있도록 프롬프트 성격의 상세 설명으로 문구 개선

디버깅할 때 다음 두 요소를 유념하십시오. 첫째, Workers는 물리적 응답 대기시간(I/O 대기)과 실제 CPU 사용 시간을 다르게 계산합니다. 따라서 외부 LLM 호출을 기다리는 시간 자체로 CPU 한도를 위반하는 경우는 드물지만, 긴 JSON 텍스트를 파싱하고 반복 연산하는 로직은 CPU 점유율을 급격히 높일 수 있습니다. 둘째, 에이전트의 상황 판단 정확도는 오직 도구 설명(description)에 좌우됩니다. 이 설명을 모델에 내리는 핵심 지침으로 생각하고 인풋과 아웃풋의 유형을 구체적으로 제공하십시오.

테스트 및 실 배포 절차

실제 글로벌 에지에 배포하기 전에 로컬 런타임 테스트를 필히 거쳐야 합니다. wrangler dev는 Cloudflare 배포 환경과 동일한 Workerd 엔진을 로컬 머신에 에뮬레이션하므로 정합성 높은 검증이 가능합니다.

1npx wrangler dev      # local iteration with hot reload
2npx wrangler deploy   # publish to the edge

에이전트가 배포된 후에는 에이전트의 내부 의사결정 프로세스를 모니터링해야 합니다. 발생 가능한 오류와 내부 동작 흐름을 트래킹하기 위해 아래 옵션으로 리얼타임 관측성을 확보하십시오.

1[observability]
2enabled = true

배포 상태에서 npx wrangler tail 명령을 내리면 인커밍 트래픽의 실행 상태를 실시간 로그 스트림으로 모니터링할 수 있습니다. 이외에 입력 검증을 통해 유해 텍스트가 데이터베이스 관련 도구로 들어가지 않게 사전에 클렌징하고, 시스템 오류 시 유저에게 내부 프로그램의 생에러 코드가 노출되지 않도록 표준 예외 문구를 응답으로 가공하는 방식을 권장합니다. 호출 빈도가 잦은 서비스의 경우 루프가 완전히 다 돌 때까지 응답을 차단하기보다는 스트리밍 출력 기능을 연동하여 체감 속도를 개선할 수 있습니다.

핵심 정리

  • AI 에이전트는 상황 추론 모델을 기반으로 최적의 맞춤형 API 도구를 직접 선택해 실행하여 복잡한 질문에 대응합니다.
  • LangChain.js 프레임워크는 Cloudflare Workers의 V8 샌드박스 엔진 내에서 매끄럽고 빠르게 작동합니다.
  • 외부 API 연동이나 데이터베이스 연동 함수를 JavaScript 도구로 작성해 에이전트에 주입합니다.
  • 요청마다 초기화되는 상태비저장 구조의 메모리 한계는 Cloudflare D1 SQL 데이터베이스로 해소합니다.
  • 의사결정 반복 횟수 제한 및 실행 시간 타임아웃 설정을 도입하여 불필요한 API 요금 발생과 런타임 오류를 방지합니다.

비즈니스 워크플로우에 AI 에이전트 도입하기

프로덕션 등급의 완결성 높은 AI 에이전트를 안정적으로 구축하려면 서버리스 엔진, 데이터베이스 인프라, 최적의 프롬프트 구성에 대한 포괄적인 엔지니어링 기술이 요구됩니다. Mecanik은 비즈니스 맞춤형 AI 도입 컨설팅 서비스 를 수행하고 있으며, 웹 개발자 채용 지원을 통해 숙련된 기술 엔지니어들을 매칭해 드립니다. 저희는 빠른 반응 속도와 높은 확장성을 지닌 고성능 지능형 에이전트 시스템 구축을 보장합니다. 당사의 프로젝트 매니저와 도입 로드맵을 상의해 보십시오.

자주 묻는 질문 (FAQ)

AI 챗봇과 AI 에이전트의 차이점은 무엇인가요? AI 챗봇은 사용자의 질문 프롬프트에 대해 준비된 정보를 취합하여 즉각 답변하는 형태입니다. 반면, AI 에이전트는 사용자의 질문 목표를 파악한 뒤, 이 작업을 완수하기 위해 필요한 외부 정보(API 등)를 스스로 파악하여 내부의 다양한 도구들을 순차적으로 실행하고 결과를 피드백하는 자율 동작 모델입니다.

Cloudflare Workers 환경에서 LangChain을 실행할 수 있습니까? 네, 가능합니다. LangChain.js 패키지는 웹 표준 API 규격을 따르도록 설계되어 Node.js 코어 모듈 전체를 필요로 하지 않는 Cloudflare Workers V8 엔진에서도 매끄럽게 컴파일되어 실행됩니다.

AI 에이전트에게 데이터베이스 읽기/쓰기 권한을 주려면 어떻게 해야 합니까? 데이터베이스를 조회하는 전용 비즈니스 로직을 구현한 뒤, 이를 LangChain의 커스텀 도구 규격으로 래핑하여 에이전트 선언 시 주입합니다. 에이전트가 데이터 처리가 필요하다고 판단하면 해당 도구 함수가 실행되어 쿼리가 돌게 됩니다.

에이전트가 불필요하게 동일 로직을 무한히 도는 현상을 막으려면 어떻게 합니까? 에이전트 실행기를 선언할 때 maxIterations 인자값을 주어 최대 동작 횟수(예: 5회)를 고정하고, 연동하는 개별 도구의 내부 로직에 철저한 시간 초과(Timeout) 한도를 정의해 둡니다.

AI 에이전트 가동을 위해 어떤 호스팅 환경이 가장 좋습니까? Cloudflare Workers와 같은 서버리스 에지 호스팅이 최적의 대안입니다. 전 세계 사용자 인접 위치에서 분산 실행되므로 통신 지연이 극히 낮고, D1 또는 R2 스토리지 서비스 등과 에지 전용 내부망 인터페이스로 직접 연동되어 빠른 트랜잭션을 지원하기 때문입니다.