AI 애플리케이션 엔지니어링: LLM API부터 에이전트, 하네스 및 프로덕션 시스템까지

프롬프트, 컨텍스트 엔지니어링, 멀티모달 AI, 툴 호출, 후크, 승인, 압축(compaction), 메모리, 오케스트레이션, 그리고 프로덕션 아키텍처에 대한 종단 간 가이드.

서론: AI 애플리케이션은 단순한 모델 호출 그 이상이다

대규모 언어 모델(LLM)을 애플리케이션에 통합하는 것은 비교적 간단합니다. 요청을 보내고, 응답을 받고, 인터페이스에 표시하기만 하면 됩니다.

하지만 신뢰할 수 있는 AI 애플리케이션을 구축하는 것은 또 다른 도전입니다.

실제 애플리케이션은 컨텍스트를 관리하고, 툴을 실행하며, 상태를 보존하고, 중단을 처리하고, 승인을 요청하며, 실패로부터 복구하고, 사용자에게 진행 상황을 전달해야 합니다. 또한 일부 애플리케이션은 이미지를 처리하거나, 오디오, 비디오, 문서를 처리하거나, 구조화된 데이터 또는 실시간 이벤트를 처리할 필요가 있습니다.

이러한 요구사항이 증가함에 따라 모델은 더 큰 시스템의 단지 하나의 구성 요소가 됩니다.

본 글에서는 모델 기능 및 SDK 통합부터 에이전트 루프, 컨텍스트 관리, 하네스 엔지니어링, 그리고 프로덕션 운영에 이르기까지 AI 애플리케이션 엔지니어링의 전체 영역을 탐구합니다.

적절한 곳에서는 실용적인 TypeScript 예제를 위해 Vercel AI SDK를 사용할 것이며, OpenAI, Anthropic 및 기타 모델 제공업체에도 적용되는 개념들을 논의할 것입니다.

목표는 방대한 API 목록을 만드는 것이 아닙니다. 각 조각들이 어떻게 함께 맞물리는지, 어떤 문제를 해결하는지, 그리고 각각의 책임이 어디에 속하는지를 이해하는 것입니다.

1. AI 애플리케이션 스택 이해하기

개별 기능을 탐구하기 전에 정신적인 모델을 확립하는 것이 유용합니다.

프로덕션 AI 애플리케이션은 여러 협력하는 계층으로 이해할 수 있습니다.

1.1 모델 계층 (Model layer)

모델은 다음과 같은 기능을 제공합니다:

텍스트 생성 및 요약
추론 및 문제 해결
이미지 및 문서 이해
오디오 이해 및 생성
구조화된 출력 생성
툴 선택
임베딩 및 의미 표현(semantic representations)
지원되는 경우 비디오 이해

모든 모델이 모든 기능을 지원하는 것은 아닙니다. 가용성, 품질, 제한 사항 및 가격은 특정 모델과 제공업체에 따라 달라집니다.

1.2 API 및 SDK 계층

제공업체의 API는 네트워크 인터페이스를 통해 모델의 기능을 노출합니다. SDK는 타입 지정 함수(typed functions), 요청 빌더(request builders), 스트리밍 도우미(streaming helpers) 및 제공업체별 추상화(provider-specific abstractions)를 통해 해당 인터페이스 사용을 더 쉽게 만듭니다.

예시:

1.3 애플리케이션 런타임

런타임은 모델 주변에서 발생하는 것을 제어합니다:

프롬프트 및 컨텍스트 구성
사용 가능한 도구 선택
도구 호출 실행
에이전트 루프 관리
권한 부여 규칙 적용
훅(hooks) 및 미들웨어(middleware) 처리
상태 유지
실패 및 재시도 관리
장기 실행 작업 조정

1.4 경험 계층

사용자 인터페이스는 런타임의 동작을 전달합니다:

텍스트 스트리밍
도구 호출 진행 상황
구조화된 결과
상호 작용 컴포넌트
명확화 질문
승인 요청
작업 상태 및 오류

1.5 운영 및 거버넌스

프로덕션 시스템에는 추가적으로 다음이 필요합니다:

평가 및 회귀 테스트(Evaluation and regression testing)
관측 가능성 및 추적(Observability and tracing)
비용 및 지연 시간 제어
데이터 개인 정보 보호 및 보존 정책
보안 경계
인간 감독
복구 및 감사 가능성

유용한 규칙은 모델이 제안하고, 런타임이 조정하며, 도구가 작업을 수행하고, 애플리케이션이 정책을 강제한다는 것입니다.

AI 애플리케이션이 더욱 자율적이 되면서 이러한 분리는 점점 더 중요해집니다.

2. 애플리케이션에서 LLM이 실제로 작동하는 방식

AI 애플리케이션을 구축하기 위해 트랜스포머 아키텍처의 모든 세부 사항을 이해할 필요는 없지만, 시스템 설계를 좌우하는 개념들은 이해해야 합니다.

2.1 모델 및 추론

모델은 입력과 학습된 매개변수(parameters)를 기반으로 출력을 생성합니다. 애플리케이션에서 모델을 실행하여 출력을 만들어내는 과정을 추론(inference)이라고 부릅니다.

입력에는 지침(instructions), 대화 메시지, 검색된 문서, 이미지, 오디오, 도구 정의(tool definitions), 또는 구조화된 데이터가 포함될 수 있습니다.

출력은 일반 텍스트(plain text), 구조화된 콘텐츠, 오디오 응답, 또는 도구 호출 요청일 수 있습니다.

모델이 사용자의 데이터베이스, 파일 시스템, 내부 API, 또는 비즈니스 시스템에 자동으로 접근할 수는 없습니다. 이러한 기능들은 적절한 통합을 통해 노출되어야 합니다.

2.2 토큰 및 컨텍스트 창(Tokens and context windows)

모델은 텍스트 및 기타 콘텐츠를 근본적인 표현(underlying representations)을 통해 처리합니다. 텍스트의 경우, 이는 일반적으로 단어나 문자 대신 토큰(tokens)으로 측정됩니다.

토큰은 다음 요소에 영향을 미칩니다:

컨텍스트 창 용량(Context-window capacity)
입력 및 출력 비용(Input and output costs)
응답 생성 시간(Time to generate a response)
포함할 수 있는 대화 기록의 양
요청에 포함될 수 있는 도구 정의와 검색된 문서의 개수

컨텍스트 창은 모델이 요청을 위해 처리할 수 있는 컨텍스트의 양입니다. 정확한 제한 및 회계 규칙은 모델마다 다릅니다.

컨텍스트 창이 크다고 해서 자동으로 더 나은 결과를 낳는 것은 아닙니다. 관련성이 없거나 모순되는 정보가 사용 가능한 용량 내에 포함되더라도 요청을 덜 효과적으로 만들 수 있습니다.

2.3 메시지 및 역할(Messages and roles)

많은 대화형 API는 상호 작용을 역할을 가진 메시지 또는 동등한 콘텐츠 유형으로 표현합니다.

일반적인 역할에는 다음이 포함됩니다:

시스템 또는 개발자 지침(System or developer instructions): 동작, 제약 조건 및 애플리케이션 레벨 규칙을 설정합니다.
사용자(User): 사용자의 요청과 제공된 정보를 담고 있습니다.
어시스턴트(Assistant): 모델의 응답 또는 도구 사용 요청을 포함합니다.
도구 결과(Tool result): 외부 작업에 의해 반환된 정보를 담고 있습니다.

정확한 메시지 구조는 제공업체마다 다릅니다. 일부 API는 이미지, 오디오, 추론 관련 데이터 및 도구 상호 작용을 위한 더 풍부한 콘텐츠 블록도 지원합니다.

대화(conversation)가 반드시 일반 텍스트 메시지의 배열일 필요는 없습니다. 이는 다양한 유형의 콘텐츠와 이벤트의 시퀀스일 수 있습니다.

2.4 추론 및 확장된 사고 (Reasoning and extended thinking)

일부 모델은 복잡한 작업을 수행할 때 성능을 향상시킬 수 있는 추론 중심 기능(reasoning-oriented capabilities) 또는 설정 가능한 사고 모드(configurable thinking modes)를 지원합니다.

이는 코딩, 계획 수립, 분석 및 다단계 도구 사용에 유용할 수 있습니다. 하지만 추론 능력은 모델과 제공업체마다 다릅니다.

애플리케이션 개발자는 다음 사항들을 구별해야 합니다:

모델의 내부 계산(internal computation)
API를 통해 노출되는 모든 추론 관련 콘텐츠
사용자에게 보여지는 설명(user-facing explanation)
도구에 의해 실제로 수행된 작업

내부 추론을 노출하는 것이 투명성을 위해 필수적이라고 가정하지 마십시오. 유용한 애플리케이션은 대신 간결한 설명, 출처, 작업 기록(action history), 그리고 검증 가능한 결과를 보여줄 수 있습니다.

추론에는 실질적인 비용도 따릅니다. 더 많은 계산은 지연 시간(latency) 및 토큰 사용량 증가를 의미할 수 있습니다. 예를 들어, Anthropic의 extended-thinking 문서는 사고(thinking), 도구 사용(tool use), 스트리밍(streaming), 그리고 컨텍스트 관리 간의 상호 작용을 설명합니다.

3. AI 채팅 이상의 역량 (AI Capabilities Beyond Text Chat)

가장 중요하게 이해해야 할 점 중 하나는 AI가 채팅 창에서 텍스트를 생성하는 것과 동의어(synonymous)가 아니라는 것입니다.

최신 AI API는 여러 가지 역량을 노출하며, 애플리케이션은 하나의 워크플로우 내에서 이들 중 여러 개를 결합할 수 있습니다.

3.1 텍스트 생성 (Text generation)

텍스트 생성은 채팅 비서, 요약, 재작성(rewriting), 번역, 분류 및 콘텐츠 생성의 기반이 되는 친숙한 기능입니다.

일반적인 사용 사례는 다음과 같습니다:

질문 답변
보고서 요약
이메일 초안 작성
코드 설명
문서에서 정보 추출
상황별 추천 생성

출력은 점진적으로 스트리밍되거나, 생성이 완료된 후에 반환될 수 있습니다.

3.2 구조화된 출력 (Structured output)

때로는 애플리케이션이 자유 형식의 산문 대신 예측 가능한 데이터 구조를 필요로 합니다.

예를 들어, 태스크 분류기(task classifier)는 다음과 같은 출력을 반환해야 할 수 있습니다:

{
  "category": "billing",
  "priority": "high",
...

구조화된 출력 기능(Structured output features)을 사용하면 개발자가 스키마(schema)나 지원되는 구조화 생성 메커니즘을 사용하여 예상되는 형태를 설명할 수 있습니다.

이것은 다음 용도에 유용합니다:

분류(Classification)
데이터 추출(Data extraction)
폼 채우기(Form population)
보고서 생성(Report generation)
워크플로우 라우팅(Workflow routing)
타입이 지정된 UI 데이터 생성(Producing typed UI data)

스키마 제약 출력은 포맷팅 오류를 줄일 수 있지만, 값이 사실적으로 정확하거나 특정 액션이 안전하다는 것을 보장하지는 않습니다. 결과를 검증하고 비즈니스 규칙을 독립적으로 강제해야 합니다.

3.3 Vision 및 이미지 이해

Vision 기능을 갖춘 모델은 지원되는 API를 통해 제공된 이미지를 분석할 수 있습니다.

잠재적인 사용 사례에는 다음이 포함됩니다:

스크린샷 이해(Understanding screenshots)
차트에서 정보 추출(Extracting information from charts)
제품 이미지 분석(Analyzing product images)
다이어그램 해석(Interpreting diagrams)
지원되는 문서 이미지 읽기(Reading supported document images)
사용자가 시각적 인터페이스를 탐색하는 것을 도움(Helping users navigate a visual interface)

이미지 지원은 허용되는 형식, 해상도, 세부 사항 처리 및 토큰 계산에서 차이가 있습니다.

문서 이해는 OCR(광학 문자 인식), 레이아웃 분석, PDF 파싱 또는 전용 문서 처리 파이프라인을 필요로 할 수도 있습니다. 모델이 이미지를 이해하는 능력이 모든 문자나 표를 완벽하게 추출한다는 것을 의미하지는 않습니다.

3.4 오디오 이해 및 생성

오디오 기능은 다음을 지원할 수 있습니다:

음성-텍스트 전사(Speech-to-text transcription)
오디오 분류(Audio classification)
구어 질문 응답(Spoken question answering)
텍스트-음성 생성(Text-to-speech generation)
음성 비서(Voice assistants)
구두 요약(Spoken summaries)
지원되는 경우 오디오 번역(Audio translation, where supported)

간단한 음성 비서는 다음과 같은 파이프라인을 사용할 수 있습니다:

오디오 캡처.
음성을 전사하거나 해당 오디오를 직접 처리할 수 있는 모델로 전송합니다.
요청 해석.
필요한 경우 도구 호출(Invoke tools).
응답 생성.
응답을 음성으로 변환.
사용자에게 오디오 재생.

다른 아키텍처는 여러 단계를 함께 처리하는 음성 지원 모델을 사용합니다.

이러한 설계들은 서로 다른 지연 시간(latency), 비용, 상호작용 특성을 가집니다. 실시간 음성 애플리케이션의 경우 중단 처리(interruption handling), 턴 감지(turn detection), 스트리밍 오디오(streaming audio), 세션 관리(session management)가 필요할 수도 있습니다.

3.5 비디오 및 실시간 인식

비디오 이해는 지원되는 비디오 입력, 샘플링된 프레임, 오디오 트랙 또는 모델별 비디오 인터페이스로부터 구축될 수 있습니다.

잠재적인 사용 사례에는 다음이 포함됩니다:

녹화된 회의 요약
시연 이해
일련의 이벤트 분석
교육 비디오에서 정보 추출
시간에 따른 시각적 변화 해석

개발자는 프레임 샘플링, 타임스탬프, 오디오 동기화, 데이터 볼륨 및 처리 비용을 고려해야 합니다. 선택된 프레임을 받는 모델이 반드시 비디오의 모든 순간을 이해하는 것은 아닙니다.

3.6 임베딩 및 의미적 유사성

임베딩(Embeddings)은 콘텐츠를 수학적으로 비교할 수 있는 숫자 벡터로 표현합니다.

이는 다음 용도로 유용합니다:

의미 검색(Semantic search)
문서 검색(Document retrieval)
유사성 감지(Similarity detection)
추천 시스템(Recommendation systems)
클러스터링(Clustering)
검색 증강 생성(Retrieval-augmented generation, RAG)

예를 들어, 두 문서가 서로 다른 어휘를 사용하여 동일한 개념을 논할 수 있습니다. 의미 검색 시스템은 쿼리가 정확한 키워드를 공유하지 않더라도 관련 문서를 검색할 수 있습니다.

임베딩 그 자체가 답변이 아닙니다. 이는 검색 및 유사성 시스템에서 사용되는 표현(representations)입니다.

3.7 도구 사용 및 외부 동작

모델은 다음과 같은 기능을 노출하는 도구를 요청할 수 있습니다:

내부 문서 검색
데이터베이스 질의
파일 읽기
비즈니스 API 호출
티켓 생성
지원되는 계산 실행
웹 검색

모델은 일반적으로 도구 호출을 제안하고 인수를 제공합니다. 실제 실행 여부는 애플리케이션 또는 공급자 관리형 실행 환경이 결정합니다.

이러한 구분은 근본적입니다: 도구 호출(tool call)은 단순히 생성된 텍스트 조각에 불과하지 않으며, 행동을 설명하는 것과 실제로 실행하는 것은 같지 않습니다.

3.8 컴퓨터 사용 및 브라우저 상호작용

일부 시스템은 에이전트가 스크린샷, 클릭, 타이핑 또는 기타 동작을 통해 지원되는 인터페이스와 상호작용할 수 있도록 하는 컴퓨터 사용(computer-use) 또는 브라우저 사용(browser-use) 기능을 지원합니다.

이러한 기능들은 다음을 가능하게 할 수 있습니다:

브라우저 기반 리서치
레거시 인터페이스와의 상호작용
반복적인 UI 워크플로우
사용자 여정 테스트
적절한 API가 없는 애플리케이션 관련 작업들

컴퓨터 사용은 추가적인 위험을 초래합니다. 에이전트는 화면을 잘못 해석하거나, 잘못된 컨트롤을 클릭하거나, 신뢰할 수 없는 콘텐츠를 접할 수 있습니다. 민감한 작업을 위해서는 강력한 실행 경계(execution boundaries), 검증(validation), 그리고 적절한 인간의 감독(human oversight)이 필요합니다.