에이전트 애플리케이션 개발과 렌더링 간의 관계 고찰

서론

개발자들이 전통적인 프런트엔드 및 백엔드 개발에서 AI Agent 애플리케이션 구축으로 전환할 때, 생성된 데이터가 사용자 정의 UI 렌더링과 어떻게 결합되는지에 대해 혼란을 자주 경험합니다. 이 글은 에이전트 개발의 핵심 정신 모델을 분석합니다: Large Language Models (LLMs)를 활용하여 엔지니어링 워크플로우를 구동하는 방식이며, LLM 기능, 클라이언트-서버 통신 프로토콜, 데이터 생성 및 UI 렌더링이 서로 어떻게 연결되는지를 명확히 합니다.

에이전트 애플리케이션 개발의 핵심 아이디어는 LLMs를 사용하여 엔지니어링 프로세스를 구동하는 데 있습니다. 여기서 중요한 과제는 LLM 출력을 제어하는 작동 가능한 렌더링 파이프라인을 구축하는 것입니다. 이 글은 문제를 세 가지 주요 섹션으로 나눕니다: LLM 기능 이해, 클라이언트-서버 프로토콜 경계 정의, 그리고 렌더링 로직과 함께 데이터 생성 구현. 여기에는 개발자들이 실제 프로젝트에 직접 적용할 수 있는 실용적인 코드 예제와 표준 패턴이 포함되어 있습니다.

1. LLM 기능 및 핵심 함수 이해

이해(Comprehension), 추론(Reasoning) 및 생성(Generation)

가장 기본적인 수준에서, LLM은 세 가지 핵심 작업을 수행할 수 있습니다: 입력 콘텐츠 이해, 추론 수행, 그리고 자연어 텍스트 생성. 간단한 API 호출이 이러한 동작을 보여줍니다.

llm.invoke("Hello")

모델은 자연어 답변을 반환합니다. 내부적으로 이 실행에는 세 가지 순차적인 단계가 포함됩니다:

1. 사용자 입력 메시지의 의미를 이해(Comprehend)하는 것.
2. 적절한 응답을 결정하기 위해 추론(Reasoning)을 수행하는 것.
3. 최종 답변으로 연속적인 텍스트 출력을 생성(Generate)하는 것.

이러한 기본적인 기능은 LLM이 대화형 상호작용, 요약 및 콘텐츠 생성을 처리할 수 있도록 합니다. 에이전트 시스템의 경우, 더 중요한 확장 기능은 Function Call을 통한 도구 호출입니다.

함수 호출 메커니즘

함수 호출(Function Call)은 LLM 내부에서 직접 함수를 실행하는 것이 아닙니다. LLM은 본질적으로 텍스트 완성 엔진입니다. 모델은 학습을 통해 외부 도구 호출 의도를 표현하기 위해 구조화된 JSON 텍스트를 생성하도록 배웁니다.

함수 호출이 널리 지원되기 전에는 개발자들이 프롬프트 엔지니어링(prompt engineering)에 크게 의존했습니다. 엔지니어들은 모델이 고정된 형식으로 콘텐츠를 출력하도록 강제하기 위해 상세한 지침을 작성했고, 그 결과를 정규 표현식(regular expressions)으로 파싱했습니다. 이 방법은 취약했습니다. 모델 출력의 사소한 편차만으로도 매개변수 파싱 전체가 깨질 수 있었습니다. Guidance와 같은 일부 초기 제약 프레임워크(constraint frameworks)는 이러한 불안정성을 완화하는 데 사용되었습니다.

DeepSeek을 포함한 최신 LLM과 많은 주류 모델들은 네이티브하게 함수 호출을 지원합니다. 이 기능은 LLM의 경계를 단순 텍스트 처리에서 구조화된 도구 오케스트레이션(tool orchestration)으로 확장합니다. 모델은 도구를 설명하고, 매개변수를 정의하며, 외부 로직을 트리거할 수 있습니다. 이것이 실용적인 AI 에이전트 워크플로우를 가능하게 하는 기반입니다.

2. 클라이언트 및 서버 프로토콜 설계

SSE (Server-Sent Events)

서버 전송 이벤트(Server-Sent Events)는 W3C에서 표준화한, HTTP를 기반으로 하는 단방향 실시간 푸시 프로토콜입니다. 이는 장기 연결을 위해 text/event-stream 콘텐츠 타입을 사용합니다. 서버는 이 영구 채널을 통해 클라이언트에게 지속적으로 데이터 청크를 푸시합니다. 일반적인 사용 사례로는 실시간 알림, 진행률 스트리밍(progress streaming), 그리고 스트리밍되는 AI 모델 출력이 있습니다.

SSE는 이벤트 스트리밍을 위한 고정된 메시지 형식을 정의합니다.

event: progress
id: 12
retry: 3000
...

• event: 이벤트 메시지의 유형을 식별합니다.
• id: 중단된 스트림을 재개하기 위한 이벤트 식별자입니다.
• retry: 밀리초 단위로 재연결 시도 간격입니다.
• data: 이벤트의 페이로드 본문입니다. 빈 줄은 개별 이벤트 항목을 구분합니다.

클라이언트가 이 스트림 모드를 협상하려면 Accept: text/event-stream HTTP 헤더를 포함해야 합니다. 개발자는 표준 SSE 사양을 사용하는 대신 사용자 지정 바이너리 또는 JSON 스트리밍 형식을 설계할 수도 있습니다.

SSE는 에이전트 애플리케이션에 자연스럽게 들어맞습니다. 에이전트 워크플로우는 서버에서 실행되며, LLM 추론은 상당한 시간을 소모합니다. 클라이언트로 증분 출력을 스트리밍하면 반응성이 뛰어난 사용자 경험을 제공할 수 있습니다.

네이티브 브라우저의 EventSource API에는 주목할 만한 제한 사항들이 있습니다.

1. 네이티브 EventSource는 GET 요청만 지원합니다. 요청 본문(request body)을 첨부할 수 없기 때문에, 개발자는 서버로 메시지 페이로드(payload)를 보낼 수 없습니다.
2. 이는 엄격하게 단방향 통신만을 강제합니다. 사용자가 메시지를 제출하고 지속적인 다운스트림 출력(downstream output)을 받는 표준 사용 패턴은 네이티브 EventSource로는 직접 구현할 수 없습니다.

표준 해결책은 Accept: text/event-stream 헤더를 사용하는 POST 요청을 이용하는 것입니다. POST 요청은 JSON 페이로드, 파일 및 이미지 콘텐츠를 전송할 수 있습니다. 서버는 이 헤더를 감지하고 스트리밍된 SSE 콘텐츠로 응답합니다.

const response = await fetch("/api/chat", {
  method: "POST",
  headers: {
...

Microsoft의 @microsoft/fetch-event-source 오픈소스 라이브러리가 이러한 제한 사항들을 해결해 줍니다. 이 라이브러리는 내부적으로 fetch를 사용하며 POST 기반 SSE 스트리밍을 지원합니다. 다음 예제는 사용자 지정 렌더링 콜백과 함께 재사용 가능한 메시지 전송 함수를 보여줍니다.

import { fetchEventSource } from "@microsoft/fetch-event-source";

async function sendMessage(message, render) {
...

SSE의 핵심 아이디어는 사용자 지정 스트리밍 프로토콜로 확장될 수 있습니다. 표준 SSE 대신 개발자는 NDJSON 스트림을 구현할 수 있습니다. 각 줄은 직렬화된 JSON 객체 하나를 포함합니다.

{"type":"progress","percent":60}
{"type":"completed","result":"Analysis finished"}

이 사용자 지정 라인 구분 JSON 접근 방식은 단순한 텍스트 청크 이상의 풍부하고 구조화된 이벤트 유형이 필요한 에이전트 애플리케이션에 잘 작동합니다.

3. 데이터 생성 및 UI 렌더링

LLM과 백엔드 서비스가 프론트엔드 컴포넌트를 구동하려면, 시스템은 사용 가능한 UI 컴포넌트를 설명해야 합니다. 메타데이터는 컴포넌트의 사용 사례(use cases), 허용되는 매개변수(parameters), 지원되는 이벤트(events) 및 사용자 상호작용 콜백을 정의합니다.

간소화된 React 승인(approval) 컴포넌트가 이 패턴을 보여줍니다.

interface ApprovalProps {
  requestId: string;
  title: string;
...
}

이 TypeScript 인터페이스는 데이터 구조와 콜백 시그니처를 정의합니다. 하지만 타입 정의만으로는 충분하지 않습니다. LLM과 백엔드는 이 컴포넌트가 적용되는 시나리오나 어떤 이벤트를 트리거해야 하는지 알 수 없습니다. 개발자는 목적, 매개변수 및 이벤트 매핑을 설명하기 위해 컴포넌트 메타데이터를 첨부해야 합니다.

아래의 approvalMeta 객체는 이 UI 컴포넌트에 대한 기계가 읽을 수 있는(machine-readable) 메타데이터를 제공합니다.

export const approvalMeta = {
  name: "Approval",
  description: "작업과 그 영향을 표시하고, 사용자에게 승인 또는 거부를 요청합니다.",
...
}

이 메타데이터는 onResolve(decision)을 호출하는 것이 approval.resolve 이벤트를 방출한다는 것을 설명합니다. 이는 requestId 식별자와 결정 페이로드(decision payload)를 포함합니다.

개발자는 컴포넌트 유형, 설명 및 이벤트 매핑을 유지 관리합니다. 빌드 도구는 TypeScript 타입 정보와 메타데이터 정의를 결합하여 표준화된 기계가 읽을 수 있는 컴포넌트 사양을 생성합니다. LLM은 이 사양을 읽고 에이전트 워크플로우 내에서 어떤 UI 컴포넌트를 렌더링할지 결정합니다.

이러한 분리는 깨끗한 경계를 만듭니다:

1. 백엔드 / LLM: 구조화된 데이터와 이벤트 지침을 생성합니다.
2. 클라이언트: 구조화된 페이로드를 수신하고, 일치하는 UI 컴포넌트를 렌더링하며, 사용자 상호작용을 포착하여 서버로 이벤트를 전송합니다.

LLM은 DOM 요소를 직접 조작하지 않습니다. 이는 UI 렌더링에 대한 선언적 지침(declarative instructions)만을 출력합니다. 클라이언트는 이러한 지침을 해석하고 네이티브 컴포넌트 렌더링을 관리합니다. 이 설계는 에이전트 로직과 프론트엔드 구현 세부 사항을 분리합니다.

4. 시스템 아키텍처 및 에이전트 워크플로우 요약

4. 시스템 아키텍처 및 에이전트 워크플로우 요약

전체 Agent 렌더링 워크플로우는 순차적인 파이프라인으로 요약할 수 있습니다:

1. 사용자가 프론트엔드 클라이언트에서 POST 스트리밍 요청을 통해 요청을 보냅니다.
2. 서버가 입력을 받고, LLM 추론을 호출합니다.
3. LLM은 일반 텍스트를 생성할지 아니면 Function Call을 통해 컴포넌트 렌더링 지침을 내보낼지 결정합니다.
4. 서버는 구조화된 이벤트를 SSE 또는 사용자 지정 스트림 프로토콜을 통해 클라이언트로 전송합니다.
5. 클라이언트가 수신되는 이벤트를 구문 분석합니다. 페이로드가 UI 컴포넌트를 설명하는 경우, 클라이언트는 일치하는 컴포넌트를 인스턴스화하고 렌더링합니다.
6. 사용자가 렌더링된 UI와 상호 작용하며, 컴포넌트 콜백을 트리거합니다.
7. 클라이언트가 상호 작용 이벤트를 서버로 다시 전송합니다.
8. 서버는 사용자 상호 작용 결과를 사용하여 Agent 추론을 재개합니다.

이 아키텍처는 렌더링 로직을 프론트엔드에 완전히 포함시킵니다. LLM은 고수준 워크플로우 결정과 데이터 생성에만 책임이 있습니다. 이러한 분리는 모델 출력과 UI 프레임워크 간의 강한 결합(tight coupling)을 방지합니다.

분산된 Agent 시스템에서 개발자들은 종종 API 게이트웨이를 통해 다중 모델 트래픽 라우팅을 관리합니다. 4sapi는 여러 LLM이 Agent 워크로드를 제공할 때 오케스트레이션을 단순화하는 통합 엔드포인트 관리를 제공합니다.

5. 일반적인 함정 및 엔지니어링 모범 사례

프로토콜 선택의 트레이드오프

SSE는 서버-클라이언트 스트리밍에 이상적이지만, 양방향 실시간 통신을 네이티브하게 처리할 수는 없습니다. Agent가 빈번한 양방향 메시지 교환이 필요하다면 WebSocket이 더 적합할 수 있습니다. 대부분의 텍스트 및 UI 스트리밍 시나리오에서는 POST 기반 SSE가 구현하기 더 간단하고 디버깅하기 쉽습니다.

컴포넌트 메타데이터 유지 관리

메타데이터는 가볍고 기계가 구문 분석할 수 있어야 합니다. 긴 자연어 설명을 포함하는 것은 피해야 합니다. 모든 컴포넌트는 트리거 조건, 입력 스키마 및 출력 이벤트 형식을 명시적으로 정의해야 합니다. 오래된 메타데이터는 LLM이 잘못된 컴포넌트를 선택하게 하여 렌더링 동작을 깨뜨립니다.

관심사 분리

LLM이 직접 원시 HTML이나 JSX를 출력하도록 두지 마십시오. 직접적인 코드 생성은 심각한 보안 위험과 강한 결합(tight coupling)을 초래합니다. 선호되는 패턴은 선언적 렌더링 지침입니다. LLM은 컴포넌트 식별자 및 매개변수를 출력하고, 클라이언트가 미리 구축된 등록된 컴포넌트를 렌더링합니다.

관심사 분리

스트리밍 연결은 예기치 않게 끊어질 수 있습니다. 클라이언트 코드는 재연결 로직(reconnection logic), 중단 제어기(abort controllers) 및 부분 상태 복구 기능을 구현해야 합니다. 각 이벤트는 식별자를 포함하여, 클라이언트가 상태를 잃지 않고 중단된 스트림을 재개할 수 있도록 해야 합니다.

결론

에이전트 애플리케이션을 구축하려면 전통적인 프런트엔드-백엔드 데이터 흐름을 다시 생각해야 합니다. 핵심 원칙은 명확한 분리입니다: LLM은 추론 및 구조화된 데이터 생성을 처리하고, 서버 프로토콜은 스트리밍 페이로드를 전달하며, 클라이언트는 미리 정의된 UI 컴포넌트를 렌더링하기 위한 지침을 소비합니다.

함수 호출(Function Call) 기능은 LLM이 UI 컴포넌트에 대한 의도를 선언할 수 있게 합니다. SSE 및 사용자 지정 스트리밍 프로토콜은 서버에서 브라우저로 증분 데이터를 안정적으로 전송합니다. 컴포넌트 메타데이터는 LLM의 추론과 프런트엔드 렌더링 사이의 격차를 해소합니다. 이러한 사고방식(mental model)은 개발자들이 LLM이 UI 마크업을 직접 생성하도록 만들려는 것과 같은 일반적인 실수를 피하는 데 도움을 줍니다.

이 패턴은 확장 가능한 에이전트 시스템을 지원합니다. 새로운 UI 컴포넌트는 독립적으로 추가될 수 있으며, 메타데이터가 등록되면 LLM이 이를 사용할 수 있습니다. 다중 모델(multi-model) 에이전트 배포를 실행할 때, 통합 게이트웨이 서비스는 엔드포인트 관리 및 요청 라우팅을 간소화합니다.

국제 접속: https://4sapi.com
국내 접속: https://4sapi.cn