멀티모달 입력과 출력

멀티모달 입력과 출력 (Multimodal inputs and outputs)

모델이 멀티모달 입력과 도구 결과를 지원할 때 Deep Agents와 함께 이미지, 오디오, 비디오, 문서를 사용하세요.

Deep Agents는 멀티모달 입력과 도구 결과를 받아들이거나 멀티모달 출력을 반환하는 Large Language Model을 사용할 때 멀티모달 워크플로를 지원합니다. 사용자 메시지에 이미지와 기타 미디어를 첨부하고, 내장 read_file 도구로 비텍스트 파일을 읽고, 커스텀 도구에서 멀티모달 콘텐츠를 반환할 수 있어요.

내장 컨텍스트 압축은 주로 텍스트 중심입니다. 그에 따라 멀티모달 워크로드를 계획하세요: 대용량 미디어를 백엔드에 저장하고 가능하면 참조를 전달하세요.

출처: 문서

본문

멀티모달 사용자 입력 (Multimodal user input)

에이전트에 보내는 messages에 LangChain 채팅 모델과 같은 표준 콘텐츠 블록을 사용해 멀티모달 콘텐츠를 전달하세요:

const result = await agent.invoke({
  messages: [
    {
      role: "user",
      content: [
        { type: "text", text: "What is in this screenshot?" },
        { type: "image", url: "https://example.com/screenshot.png" },
      ],
    },
  ],
});

블록 유형, 프로바이더별 요구 사항, 추가 예시(PDF, 오디오, 비디오)는 멀티모달 메시지를 참고하세요.

내장 read_file 도구

하네스 read_file 도구는 지원되는 멀티모달 파일에 대해 일반 텍스트 대신 표준 콘텐츠 블록을 반환합니다. 선택한 모델이 해당 양식을 지원하면 에이전트가 파일시스템에 저장된 이미지, 문서, 미디어를 검사할 수 있습니다. 모델의 지원 MIME 유형은 프로바이더 문서를 확인하세요.

지원되는 멀티모달 파일 확장자:

유형 확장자
이미지 .png, .jpg, .jpeg, .gif, .webp, .heic, .heif
비디오 .mp4, .mpeg, .mov, .avi, .flv, .mpg, .webm, .wmv, .3gpp
오디오 .wav, .mp3, .aiff, .aac, .ogg, .flac
파일 .pdf, .ppt, .pptx

커스텀 도구 출력 (Custom tool outputs)

커스텀 도구는 이미지 같은 멀티모달 파일을 포함할 수 있습니다:

import { tool } from "langchain";
import { z } from "zod";

const captureScreenshot = tool(
  async () => [
    { type: "text", text: "Screenshot of the current page:" },
    { type: "image", url: "https://example.com/page.png" },
  ],
  {
    name: "capture_screenshot",
    description: "Capture a screenshot of the current page.",
    schema: z.object({}),
  },
);

반환 값은 다음 턴에 모델이 읽는 ToolMessage로 변환됩니다. 결과 메시지의 content_blocks로 정규화된 표현에 접근하세요.

도구가 이미지나 다른 대용량 바이너리 데이터를 생성하면 산출물을 [백엔드](/oss/javascript/deepagents/backends)에 저장하고 간결한 텍스트 설명과 경로 또는 URL을 반환하세요. 이렇게 하면 메시지 기록을 작게 유지하고 [컨텍스트 압축](/oss/javascript/deepagents/context-engineering#context-compression)과 더 잘 작동합니다.

컨텍스트 압축과 멀티모달 콘텐츠

내장 오프로딩과 요약은 텍스트와 메시지 기록에 최적화되어 있습니다:

  • 오프로딩(Offloading) 은 텍스트 토큰만 측정합니다. 비텍스트 블록(이미지 포함)은 압축되지 않고 대체 메시지에 보존됩니다. 이미지만 포함된 메시지는 이미지 크기만으로 오프로딩되지 않습니다.

  • 요약(Summarization) 은 오래된 메시지를 텍스트 전용 요약으로 압축합니다. 해당 범위의 이미지, 오디오, 비디오, 파일 블록은 이월되지 않습니다 — 모델은 요약기가 그들에 대해 쓴 것만 봅니다. 유지 임계값 아래의 최근 메시지는 그대로 유지됩니다.

    요약이 실행되면 이전 턴의 미디어 블록이 활성 컨텍스트에서 빠집니다:

    // Before — model receives image blocks in older turns
void {
  role: "user",
  content: [
    { type: "text", text: "What trends do you see in this chart?" },
    { type: "image", url: "https://example.com/chart.png" },
  ],
};
void {
  role: "tool",
  content: [
    { type: "text", text: "Updated chart:" },
    { type: "image", url: "https://example.com/chart-v2.png" },
  ],
};

// After — those turns collapse to text; image blocks are gone
void {
  content:
    "User asked about trends in a chart screenshot. " +
    "Tool returned an updated chart. Agent identified Q3 revenue growth.",
};

    원래 대화는 여전히 파일시스템에 텍스트로 기록됩니다. 트리거, 유지 임계값, 전체 흐름은 요약을 참고하세요.

멀티모달이 많은 워크로드의 경우:

  • 이미지, 스크린샷, 차트를 파일시스템 백엔드나 외부 객체 스토어에 저장한 다음 파일 경로나 URL을 메시지로 전달하세요.
  • 장기 대화에서는 base64 인코딩 이미지 블록보다 참조를 선호하세요.
  • 이미지가 많은 검사에는 서브에이전트를 사용해 메인 에이전트가 간결한 텍스트 결과를 받게 하세요.
  • 프로바이더가 이미지에 많은 토큰을 청구할 때는 요약 임계값을 조정하거나 커스텀 토큰 카운터를 제공하세요.

오프로딩 임계값, 요약 트리거, 커스터마이즈 옵션은 컨텍스트 압축을 참고하세요.

더 알아보기