몇 줄의 코드로 프로덕션급 Agent 만들기

Chris Chen

5 분 읽기

Jun 10, 2026

에이전트 개발의 현재

초창기 에이전트는 일반 백엔드와 큰 차이가 없었다. 고객 응대, Q&A, 주문 조회 같은 시나리오에서는 사실상 비즈니스 인터페이스가 붙은 LLM 서비스에 가까웠다. 그러나 모델 능력이 올라오면서 에이전트는 진짜로 "손을 쓰기" 시작했다 — 파일을 다루고, 코드를 고치고, 테스트를 돌리고, 브라우저를 조작하고, 복잡한 시스템을 엮으면서 과거에는 사람이 해야 했던 일을 하나둘 가져가고 있다. 권한 경계를 한정하고 자원 사용을 통제하기 위해, 샌드박스는 필수 요소가 되었다.

다음 단계로 직관적으로 떠오르는 방식은 에이전트 로직과 도구를 같은 샌드박스에 함께 욱여넣는 것이다. 호출 경로가 짧고 상태 공유가 편하다. 구조는 깔끔하지만 멀티테넌시, 보안 격리, 비용 효율 같은 엔터프라이즈급 요구사항으로 들어가는 순간 한계가 드러난다. 로직 한 줄을 바꾸려면 전체 툴체인이 들어간 이미지를 다시 빌드해야 하고, 동시 요청 환경에서는 대화 하나당 샌드박스 한 벌을 통째로 점유하면서 자원 비용이 빠르게 쌓인다. 에이전트 로직과 자격증명, 신뢰할 수 없는 코드가 한 환경에서 돌면서 prompt injection 공격면도 넓어진다. 상태가 샌드박스에 묶여 있어 폐기되면 함께 사라지고, 복구도 까다롭다.

그래서 업계는 좀 더 디커플된 방식을 모색하기 시작했다 — 에이전트 로직, 도구 샌드박스, 상태가 각각 독립적으로 돌아가고, 컴포넌트마다 자신의 라이프사이클로 스케줄되며 서로 묶이지 않는 구조다.

다만 컴포넌트가 분리되면 호출 경로가 길어지고 환경이 파편화된다. 실제로 도입할 때는 보통 두 가지 난관 중 하나에 부딪힌다. 비즈니스 코드와 설정을 플랫폼 전용 형태로 — 플랫폼 SDK를 import 하고, 플랫폼 베이스 클래스를 상속하고, 플랫폼 전용 설정을 선언하는 식으로 — 다시 써야 하거나, 컴퓨트·상태·샌드박스·옵저버빌리티를 흩어진 독립 서비스 더미에서 직접 골라 조립하고 프레임워크에 맞춰 어댑팅 해야 한다. 로컬 디버깅과 분산 트레이싱 역시 매우 중요해진다.

Makers의 선택

Makers는 에이전트 개발 방식 자체를 다시 정의하지 않는다 — 진입 함수의 인자는 context 하나뿐이다. 플랫폼 SDK도 없고, 전용 설정도 없다. Claude Agent SDK, OpenAI Agents, LangGraph, DeepAgents, CrewAI 같은 주류 프레임워크를 그대로 가져다 쓰면 된다. 작성하는 코드는 그 프레임워크 공식 문서에 적힌 코드 그대로다. 직접 손으로 짜는 것도 물론 가능하다. 런타임 컨텍스트는 각 프레임워크 네이티브의 세션 메모리, 샌드박스 원자 인터페이스, 실시간 옵저버빌리티를 감싸고 있다 — 인프라와 하부 의존성은 플랫폼이 책임지고, 에이전트 자체는 개발자에게 남는다.

또 하나의 특징은 웹 애플리케이션과 에이전트가 같은 스택을 공유한다는 점이다. 하나의 프로젝트 안에서 에이전트와 프런트엔드를 함께 작성하고, 한 번 배포로 같은 도메인에 올린다.

몇 줄 코드로 띄우기

CLI 로 OpenAI Agents 템플릿을 받아 바로 실행해 보자.

$ npm install -g edgeone
$ edgeone makers create --template openai-agents-starter-node
$ cd openai-agents-starter-node && edgeone makers dev
  ▸ runtime  http://localhost:8088
  ▸ devtools http://localhost:8088/agent-metrics

:8088을 열면 템플릿에 포함된 대화 UI와 바로 대화할 수 있습니다.

:8088/agent-metrics를 열면, 플랫폼이 Runtime 시작 시점에 @openai/agents와 OpenAI SDK용 instrumentor를 미리 등록해 둔 상태이며, 매 요청의 LLM 호출, 도구 호출, Session 읽기/쓰기가 자동으로 트리에 들어가고 로컬 SQLite에 실시간으로 저장됩니다 — 별도의 계측 코드를 한 줄도 추가할 필요가 없습니다.

그 몇 줄 뒤에서

템플릿의 메인 핸들러에는, 플랫폼이 주입해 주는 context 외에 어떤 플랫폼 import 도 없다.

// agents/chat/index.ts —— 경로가 자동으로 POST /chat 에 매핑됨
import OpenAI from 'openai'
import { Agent, run, OpenAIChatCompletionsModel } from '@openai/agents'

export async function onRequest(context: any) {
  const { message, conversation_id } = context.request.body
  const { AI_GATEWAY_API_KEY, AI_GATEWAY_BASE_URL } = context.env

  const client = new OpenAI({ apiKey: AI_GATEWAY_API_KEY, baseURL: AI_GATEWAY_BASE_URL })
  const session = context.store.openaiSession(conversation_id)
  const agent = new Agent({
    name: 'Assistant',
    instructions: 'You are a helpful assistant.',
    model: new OpenAIChatCompletionsModel(client, '@makers/hy3-preview'),
    tools: [context.tools.web_search],
  })
  const result = await run(agent, message, { session })
  return Response.json({ reply: result.finalOutput })
}

handler에 등장하는 세 가지 플랫폼 능력 — 모델 게이트웨이, 세션 저장소, 내장 도구 — 는 모두 context에 묶여 있습니다.

context.env의 AI_GATEWAY_*는 프로젝트 생성 시 플랫폼이 자동으로 발급해 주입하는 환경 변수입니다. 이 값을 OpenAI SDK에 넘기면 호출이 내장 AI 게이트웨이를 통해 흘러가며, 별도의 Key 신청이 필요 없습니다 — 플랫폼은 한시적으로 다양한 모델의 토큰 쿼터를 제공하며, 원한다면 자신의 API Key로 교체할 수도 있습니다.

context.store.openaiSession(cid)가 반환하는 것은 @openai/agents의 네이티브 Session입니다. run()에 넘겨주면 대화 히스토리 읽기/쓰기를 그대로 인계받습니다 — 프레임워크 입장에서는 자기 자신의 인터페이스를 보고 있고, 플랫폼은 프레임워크에 투명합니다. LangGraph, Claude Agent SDK 같은 다른 프레임워크로 바꿔도 context.store 위에는 각 프레임워크 네이티브의 세션 저장 타입이 마찬가지로 노출되며, 하부는 플랫폼 Blob 스토리지가 처리합니다.

context.tools.*는 플랫폼이 미리 제공하는 도구 모음으로, 웹 검색, 코드 인터프리터, 브라우저 조작 등 자주 쓰이는 동작을 포괄합니다. 프레임워크의 tools에 그대로 넣어주기만 하면 됩니다. 샌드박스형 도구는 같은 대화의 첫 호출에서 마이크로 VM을 지연 시작해 이후에는 재사용하고, 타임아웃 시 회수합니다 — handler 시작 시 워밍업하지 않고, 콜드 스타트마다 다시 만들지도 않습니다.

커스텀 도구가 필요할 때는 context.sandbox가 노출하는 샌드박스 원자 인터페이스를 자유롭게 조합할 수 있습니다:

const runPython = tool({
  name: 'run_python',
  parameters: z.object({ code: z.string() }),
  execute: async ({ code }) => {
    const sb = await context.sandbox()       // 지연 로딩, 대화 단위로 재사용
    return await sb.codeInterpreter.run(code)
  },
})

배포

로컬에서 정상 동작이 확인되면, edgeone makers deploy 한 줄이면 배포가 끝난다. 배포 후에도 같은 span, 같은 instrumentation 을 그대로 보게 된다. 같은 프로젝트의 프런트엔드 코드도 함께 배포되어 동일 도메인에 매달린다.

플랫폼의 자원 스케줄러는 conversation_id 를 기준으로 같은 대화의 요청을 같은 에이전트 인스턴스와 도구 샌드박스로 라우팅한다. 필요할 때 만들고, 유휴 시 회수하며, 비즈니스 코드는 이를 인지할 필요가 없다.

여기까지 — 웹 도구, 세션 메모리, 옵저버빌리티가 빌트인된 프로덕션 레디 에이전트가 갖춰졌다. 개발자가 실제로 쓴 것은 여전히 @openai/agents 문서에 나오는 그 몇 줄이다.

LangGraph, Claude Agent SDK, CrewAI, DeepAgents 등 다른 프레임워크용 템플릿과, 어떤 프레임워크도 의존하지 않는 Python·JavaScript 의 미니멀 예제도 함께 제공한다. edgeone makers create 로 로컬에 받는 것 외에, 템플릿 갤러리에서 자신의 계정으로 원클릭 배포도 가능하다.

템플릿 목록 →

문서 →