Microsoft Agent Framework 멀티모달 에이전트: 이미지, PDF 및 제공자 간의 차이점

이 글은 Microsoft Agent Framework에 관한 제 시리즈의 14번째 파트입니다. 원문 포스트는 lukaswalter.dev에서 읽으실 수 있습니다.

이전 기사에서 우리는 에이전트를 위한 RAG (Retrieval-Augmented Generation)를 살펴보았습니다.
핵심은 검색(retrieval)이 마법이 아니라는 점입니다. 그것은 에이전트가 필요한 시점에 선택된 컨텍스트(context)를 제공하는 애플리케이션 기능입니다.

멀티모달 (Multimodal) 입력도 동일한 종류의 경계에 직면합니다.

Agent Framework는 이미지와 같은 비텍스트 콘텐츠를 에이전트 호출을 통해 전달할 수 있습니다.
그렇다고 해서 모든 제공자(provider), 모든 모델, 그리고 모든 파일 형식이 동일하게 작동한다는 의미는 아닙니다.
프레임워크는 공통 메시지 모델을 제공합니다.
무엇을 이해할 수 있는지, 콘텐츠를 어떻게 수용하는지, 비용이 얼마나 드는지, 그리고 예외 케이스(edge cases)가 어디에 있는지는 여전히 제공자가 결정합니다.

저의 규칙은 간단합니다: 파일을 보는 것이 핵심일 때 모델로 파일을 보내십시오.
제품이 재현성(repeatability), 확장성(scale), 인덱싱(indexing), 액세스 제어(access control) 또는 정확한 추출(exact extraction)에 의존한다면 직접 전처리하십시오.

멀티모달은 메시지 콘텐츠입니다

Agent Framework에서 기본 개념은 복잡하지 않습니다.
사용자 메시지는 여러 개의 콘텐츠 파트(content parts)를 포함할 수 있습니다.
한 파트는 텍스트일 수 있습니다.
다른 파트는 이미지 URI일 수 있습니다.
또 다른 파트는 미디어 타입(media type)을 가진 바이너리 데이터(binary data)일 수 있습니다.

이러한 구조는 Microsoft.Extensions.AI 콘텐츠 모델에서 비롯됩니다.
에이전트는 문자열(string)만 받는 것이 아닙니다.
AIContent 항목의 리스트를 포함하는 ChatMessage를 받을 수 있습니다.

최소한의 이미지 예시는 다음과 같습니다:

using Microsoft.Agents.AI;
using Microsoft.Extensions.AI;

...

로컬 이미지의 경우, 공개 URL 대신 DataContent를 사용하십시오:

byte[] imageBytes = await File.ReadAllBytesAsync(
    "screenshots/deployment-error.png",
    cancellationToken);
...

이 부분이 깔끔한 지점입니다.
애플리케이션이 메시지를 구축합니다.
에이전트가 실행됩니다.
모델이 이미지를 분석합니다.

동일한 코드가 모든 제공자(provider), 모든 모델, 모든 이미지 크기, 모든 PDF 및 모든 배포 환경에서 작동하는지 묻는 순간부터 복잡한 문제가 시작됩니다.
그렇지 않습니다.

프레임워크 지원은 모델 지원이 아닙니다

Agent Framework는 멀티모달 (multimodal) 콘텐츠를 표현할 수 있습니다.
이는 선택한 모델이 해당 콘텐츠를 처리할 수 있음을 보장하는 것과는 별개의 문제입니다.

세 가지 별개의 질문이 존재합니다:

1. 프레임워크가 해당 콘텐츠를 표현할 수 있는가?
2. 제공자 어댑터 (provider adapter)가 해당 콘텐츠를 제공자에게 보낼 수 있는가?
3. 배포된 모델이 사용자의 작업 요구 사항에 맞춰 해당 콘텐츠를 이해할 수 있는가?

첫 번째 질문에 대한 답이 '예'이더라도, 두 번째나 세 번째 질문에 대한 답은 '아니오'일 수 있습니다.

예를 들어, UriContent는 호스팅된 콘텐츠를 표현할 수 있습니다.
DataContent는 미디어 타입 (media type)이 포함된 바이너리 (binary) 콘텐츠를 표현할 수 있습니다.
하지만 텍스트 전용 모델은 여전히 이미지를 이해하지 못할 것입니다.
로컬 제공자는 base64 이미지 배열을 요구할 수 있습니다.
호스팅된 제공자는 이미지 URL은 지원하지만 프라이빗 인트라넷 URL은 지원하지 않을 수 있습니다.
모델은 요약을 위해 차트를 충분히 잘 읽을 수는 있지만, 정확한 값을 파악하기에는 부족할 수 있습니다.

멀티모달 지원을 전체 경로 (route)의 역량으로 취급하십시오:

Agent Framework 메시지
-> provider adapter
-> provider API
...

해당 경로의 어느 한 부분이라도 해당 모달리티 (modality)를 지원하지 않는다면, 추상화 (abstraction)만으로는 이를 해결할 수 없습니다.

네이티브로 작동하는 것들

이미지는 가장 직관적인 네이티브 멀티모달 입력입니다.
시각 기능이 있는 모델 (vision-capable models)의 경우, 일반적인 패턴은 다음과 같습니다:

텍스트 지시문 + 이미지 입력 -> 텍스트 응답

이는 다음과 같은 작업에 유용합니다:

• 스크린샷 분류 (triage)
• UI 리뷰
• 손글씨 메모 전사 (transcription)
• 간단한 차트 설명
• 문서 페이지 검사
• 적은 수의 이미지 비교
• 알려진 이미지 유형에서 가시적인 필드 추출

에이전트 애플리케이션에서 이는 보통 다음과 같이 집중된 역량이 됩니다:

사용자가 스크린샷 업로드
-> 애플리케이션이 이를 검증 및 저장
-> 에이전트가 스크린샷과 특정 질문을 함께 수신
...

프롬프트를 구체적으로 유지하세요.
광범위한 설명 자체가 제품인 경우가 아니라면, 모델에게 "이 이미지를 분석하세요"라고 요청하지 마세요.
대신 당신이 필요로 하는 필드(fields), 위험 요소(risks), 차이점(differences) 또는 결정 사항(decisions)을 요청하세요.

예를 들어:

이 Azure 배포 스크린샷을 검사하세요.

반환값:
...

그러한 지침은 모델에게 좁은 범위의 작업을 부여합니다.
또한 애플리케이션의 나머지 부분이 예측 가능한 데이터를 소비할 수 있도록 해줍니다.

PDF는 다릅니다

PDF는 단순히 큰 이미지 그 이상입니다.
PDF는 컨테이너(containers)입니다.

PDF에는 다음과 같은 것들이 포함될 수 있습니다:

• 임베디드 텍스트 (embedded text)
• 스캔된 페이지 이미지 (scanned page images)
• 표 (tables)
• 차트 (charts)
• 벡터 그래픽 (vector graphics)
• 양식 필드 (form fields)
• 주석 (annotations)
• 다중 열 (multiple columns)
• 회전된 페이지 (rotated pages)
• 숨겨지거나 중복된 텍스트 레이어 (hidden or duplicated text layers)

이는 "이 PDF를 읽으세요"라는 말이 여러 가지 서로 다른 의미를 가질 수 있음을 뜻합니다.

디지털로 생성된 (born-digital) PDF의 경우, 텍스트 추출 (text extraction)만으로 충분할 수 있습니다.
스캔된 PDF의 경우, OCR 또는 비전 (vision)이 필요합니다.
차트와 다이어그램이 포함된 보고서의 경우, 시각적 레이아웃 (visual layout)이 중요할 수 있습니다.
송장 (invoice)의 경우, 정확한 필드 추출 (field extraction) 및 검증 (validation)이 필요할 수 있습니다.
300페이지 분량의 매뉴얼의 경우, 아마도 인제스션 (ingestion), 청킹 (chunking), 검색 (retrieval) 및 인용 (citations)이 필요할 것입니다.

일부 제공자 API는 PDF를 직접 수락할 수 있습니다.
예를 들어, OpenAI의 파일 입력 흐름 (file input flow)은 호환 가능한 비전 모델을 위해 추출된 텍스트와 페이지 이미지를 모두 모델 컨텍스트 (model context)에 넣을 수 있습니다.
Claude는 플랫폼별 동작과 함께 페이지를 시각적으로 처리할 수 있는 PDF 지원 기능을 갖추고 있습니다.
Gemini는 PDF 처리를 명시적으로 지원하며, 자체적인 크기, 페이지 및 토큰 규칙에 따라 PDF 페이지를 시각적 입력 (visual inputs)으로 취급합니다.

그러한 지원은 유용합니다.
하지만 그것이 문서 경로 (document path)를 설계해야 할 필요성을 없애주지는 않습니다.

네이티브 PDF 입력 (Native PDF input)은 다음과 같은 경우에 적합합니다:

• 문서가 한 번의 요청에 들어갈 정도로 충분히 작은 경우
• 질문이 문서 전체 또는 알려진 몇 개의 페이지에 관한 경우
• 시각적 레이아웃이 중요한 경우
• 반복적인 검색을 위해 문서를 인덱싱 (index)할 필요가 없는 경우
• 제공자별 동작 (provider-specific behavior)을 허용할 수 있는 경우

수동 전처리 (Manual preprocessing)는 일반적으로 다음과 같은 경우에 더 좋습니다:

• 많은 문서를 처리하는 경우
• 나중에 문서를 검색할 수 있어야 하는 경우
• 문서별 또는 섹션별로 액세스 제어 (Access control)가 중요한 경우
• 추출 과정이 반복 가능 (Repeatable)해야 하는 경우
• 안정적인 인용 (Citations) 또는 페이지 참조가 필요한 경우
• 비즈니스 규칙에 따른 검증이 필요한 경우
• 표 (Tables), 양식 (Forms) 또는 필드 (Fields)를 정규화 (Normalize)해야 하는 경우
• 비용과 지연 시간 (Latency)을 예측할 수 있어야 하는 경우

프로덕션 시스템 (Production systems)의 경우, 저는 "에이전트에게 PDF 전체를 보내는 것"을 기본값으로 설정하는 일은 거의 없을 것입니다.
먼저 제가 실제로 어떤 종류의 문서 문제를 겪고 있는지 결정할 것입니다.

제공자 간의 차이가 중요합니다

제공자 (Provider) 간의 차이는 단순히 요청 구문 (Request syntax)뿐만 아니라 제품의 동작 방식에서도 나타납니다.

제공자의 문서는 빠르게 변경됩니다. 이 포스트를 위해 저는 2026년 6월 문서를 확인했으며, 실제 배포 전에는 여전히 이러한 사항들을 재검증할 것입니다:

영역	변동 사항	중요한 이유
지원되는 모달리티 (Supported modalities)	텍스트, 이미지, PDF, 오디오, 비디오 또는 이 중 일부만 지원	동일한 에이전트 설계가 다른 모델에서는 작동하지 않을 수 있음
...

실수는 이러한 차이점들을 너무 일찍 숨기는 것입니다.

제공자에 중립적인 인터페이스 (Provider-neutral interface)는 애플리케이션에 유용합니다.
하지만 인터페이스가 모든 제공자가 이미지와 PDF를 동일한 방식으로 처리한다고 가정한다면, 프로덕션 환경에서 문제가 드러나게 될 것입니다.

더 나은 추상화 (Abstraction)는 중요한 부분들을 노출하는 것입니다:

public sealed record MultimodalModelCapabilities(
    bool SupportsImageInput,
    bool SupportsPdfInput,
...

이것이 완벽할 필요는 없습니다.
단지 애플리케이션의 나머지 부분이 존재하지 않는 기능을 가정하는 것을 방지하기만 하면 됩니다.

에이전트를 원본 업로드로부터 격리하세요

에이전트가 임의로 업로드된 파일에 대해 무엇을 할지 직접 결정하게 두지 마세요.

애플리케이션이 업로드 경계 (Upload boundary)를 소유해야 합니다:

업로드 (upload)
-> 사용자 인증 (Authenticate user)
-> 문서 액세스 권한 부여 (Authorize document access)
...

파생된 아티팩트 (Derived artifacts)에는 다음이 포함될 수 있습니다:

• 추출된 텍스트 (Extracted text)
• OCR 텍스트
• 렌더링된 페이지 이미지
• 썸네일 (Thumbnails)
• 페이지 수
• 문서 메타데이터 (Document metadata)
• 표 추출 결과 (Table extraction output)
• 분류 결과 (Classification result)
• 검색을 위한 청크 ID (Chunk IDs for retrieval)

그 후 에이전트는 필요한 정보만을 전달받습니다.

예를 들어:

public sealed record PreparedAttachment(
    string AttachmentId,
    string MediaType,
...

이제 애플리케이션은 다음과 같은 결정을 내릴 수 있습니다:

• 검색 (retrieval) 결과에 따라 3페이지만 전송
• 이미지를 제외한 추출된 텍스트만 전송
• 페이지가 스캔된 문서인 경우 렌더링된 이미지 전송
• 파일 크기가 너무 큰 경우 거부
• 송장 (invoice)인 경우 전문 파서 (specialist parser) 요구

이러한 경계 설정은 지루할 수 있지만, 바로 여러분이 원하는 방식입니다.
그 대안은 모델에게 업로드된 모든 파일을 넘겨주고 모델이 알아서 올바르게 처리하기를 바라는 것뿐입니다.

네이티브 비전 (Native vision)은 OCR 인프라가 아닙니다

비전 모델 (Vision models)은 이미지 내의 텍스트를 읽을 수 있습니다.
하지만 그것이 모델을 완전한 OCR 플랫폼으로 만들어주지는 않습니다.

OCR 및 문서 처리 시스템은 일반적으로 범용 멀티모달 모델 (multimodal model)이 제공하지 못할 수도 있는 다음과 같은 요소들을 제공합니다:

• 안정적인 좌표 (stable coordinates)
• 신뢰도 점수 (confidence scores)
• 표 구조 (table structures)
• 키-값 쌍 (key-value pairs)
• 페이지 수준의 메타데이터 (page-level metadata)
• 반복 가능한 추출 (repeatable extraction)
• 결정론적 후처리 (deterministic post-processing)
• 특화된 문서 모델 (specialized document models)
• 배치 처리 제어 (batch processing controls)

만약 여러분의 제품에 이러한 속성들이 필요하다면, 먼저 문서 처리 파이프라인 (document processing pipeline)을 사용하세요.
그 다음 에이전트에게 정규화된 출력값 (normalized output)을 전달하십시오.

예를 들어:

송장 PDF
-> 문서 파서 (document parser)가 필드 추출
-> 애플리케이션이 합계 및 세금 ID 검증
...

에이전트는 설명 계층 (explanation layer)에서 유용합니다.
송장 합계에 대한 기록 시스템 (system of record)이 아닙니다.

표 (tables)의 경우도 마찬가지입니다.
정확한 행 수, 금액, ID 또는 합계가 필요하다면, 가능한 한 결정론적 코드 (deterministic code)로 표를 파싱하십시오.
에이전트는 결과를 설명하거나, 모호한 케이스를 처리하거나, 예외를 라우팅 (route exceptions)하는 데 사용하십시오.

문서 작업을 위해 도구 (tools)를 사용하세요

멀티모달 작업이 단일 모델 호출 이상의 복잡성을 띠게 된다면, 이를 도구 (tool)로 노출하십시오.

예를 들어:

public interface IDocumentInspection
{
    Task<DocumentInspectionResult> InspectAsync(
...

에이전트는 Blob storage, PDF 렌더링, OCR 또는 업로드된 모든 파일에 직접 접근할 필요가 없습니다.
에이전트에게는 제어된 작업이 필요합니다:

using System.ComponentModel;
using Microsoft.Extensions.DependencyInjection;

...

이는 이전 도구 및 RAG 포스트에서 언급한 설계 규칙을 그대로 유지합니다: 가공되지 않은 인프라(raw infrastructure)가 아닌, 제어된 기능(controlled capabilities)을 노출하는 것입니다.

도구는 내부적으로 적절한 경로를 선택할 수 있습니다:

• 네이티브 멀티모달 모델 (native multimodal model) 호출
• 텍스트를 추출하여 텍스트 모델 (text model) 호출
• 선택된 페이지를 렌더링하여 이미지 전송
• 문서 지능 서비스 (document intelligence service) 호출
• 지원되지 않는 파일 거부
• 사용자에게 더 좁은 페이지 범위 요청

에이전트는 문서 검사 (document inspection)를 요청합니다.
애플리케이션은 문서 검사가 어떻게 작동할지를 결정합니다.

파일이 포함될 때 로깅(Logging)이 더 중요해집니다

텍스트 프롬프트 (text prompts)는 이미 로깅할 가치가 있습니다.
파일 입력은 로깅의 중요성을 더욱 높입니다.

멀티모달 에이전트 호출 시, 최소한 다음 사항들을 로깅해야 합니다:

• 모델 (model) 및 제공자 (provider)
• 프롬프트 버전 (prompt version)
• 첨부 파일 ID (attachment ID)
• 미디어 유형 (media type)
• 파일 크기 (file size)
• 페이지 수 (page count, 해당되는 경우)
• 전송된 선택 페이지 또는 이미지
• 사용된 전처리 경로 (preprocessing path)
• 제공자 요청 ID (provider request ID, 사용 가능한 경우)
• 토큰 사용량 (token usage) 또는 이미지/페이지 사용량
• 안전성 또는 콘텐츠 필터 (safety or content-filter) 결과

기본적으로 기밀 파일의 원본 내용(raw confidential file contents)을 로깅하지 마십시오.
식별자, 파생된 메타데이터 (derived metadata), 그리고 적절한 권한으로 경로를 재현할 수 있을 만큼의 충분한 추적 데이터 (trace data)를 로깅하십시오.

이것이 없다면 디버깅은 추측의 영역이 됩니다:

에이전트가 PDF를 잘못 처리했습니다.

위와 같은 정보는 실행 가능한 조치(actionable)를 취할 수 없습니다.

다음 사항들을 반드시 알아야 합니다:

• 잘못된 페이지가 선택되었는지
• OCR이 실패했는지
• 모델이 차트(chart)를 아예 받지 못했는지
• 제공자가 텍스트 추출만 사용했는지
• 이미지가 너무 공격적으로 크기 조정(resized)되었는지
• 프롬프트가 이미지가 지원할 수 없는 정확한 값을 요구했는지
• 모델이 "보이지 않음"이라고 말하는 대신 추측했는지

멀티모달 버그는 종종 모델 주변의 파이프라인 (pipeline)에서 발생합니다.

네이티브 멀티모달 입력 (native multimodal input)을 사용하는 경우

다음과 같은 경우에 네이티브 이미지 또는 PDF 입력을 사용할 것입니다:

• 사용자가 하나의 이미지 또는 소수의 이미지 세트에 대해 질문할 때
• 문서가 짧을 때
• 시각적 레이아웃 (visual layout)이 질문의 일부일 때
• 작업이 탐색적 (exploratory)이거나 보조적 (assistive)일 때
• 정확한 추출 (exact extraction)만이 유일한 성공 기준이 아닐 때
• 해당 기능에 대해 제공자 종속 (provider lock-in)이 허용될 때
• 실제 파일로 테스트한 후 지연 시간 (latency)과 비용이 허용 가능한 수준일 때

예시:

• 이 배포 스크린샷에서 무엇이 잘못되었는지 설명하세요.
• 이 두 개의 UI 스크린샷을 비교하세요.
• 이 아키텍처 다이어그램 (architecture diagram)에서 보이는 변경 사항을 요약하세요.
• 이 짧은 PDF의 어느 페이지에 승인 서명이 있는지 식별하세요.
• 사람이 검토할 수 있도록 단일 스캔된 양식에서 초안 필드를 추출하세요.

네이티브 멀티모달 입력 (Native multimodal input)은 결과물(artifact)을 보는 것 자체가 목적일 때 가장 강력합니다.

수동으로 전처리(preprocess)를 수행하는 경우

다음과 같은 경우에 수동으로 전처리를 수행할 것입니다: