문서 도구 사용 및 오류 처리

각 Office 모듈은 구조화된 문서 도구 카탈로그를 제공합니다. getTools()는 이름·설명·입력 스키마와 실행 함수를 반환합니다. 사용할 모델 API나 프레임워크의 형식에 맞춰 스키마와 실행 결과를 변환해야 합니다.

실행 가능한 도구 얻기

const tools = await word.getTools({ include: ["insert_text"] });   // omit `include` to get every tool

각 항목은 OfficeTool입니다 - name, description, inputSchema(JSON Schema), execute(args). execute는 편집기에 위임하며 기본적으로 편집기의 결과를 그대로 반환합니다(MCP CallToolResult: { content, isError? }).

include(이름 배열 또는 predicate)로 도구 집합을 작고 작업에 맞게 유지하십시오. 도구가 적을수록 모델의 선택 품질이 올라가고 잘못된 판단의 영향이 줄어듭니다.

LLM 프레임워크에 연결

아래 코드는 스키마 변환 예제입니다. 앞에서 얻은 tools를 사용합니다. OpenAI 부분은 Chat Completions 형식이며 Responses API와 구분합니다. Vercel 예제는 ai 패키지가 설치된 프로젝트에서 사용합니다. 실제 실행 함수에는 애플리케이션의 권한·인자 검증과 사용자 승인을 적용해야 합니다.

// OpenAI
const openaiTools = tools.map((t) => ({
  type: "function",
  function: { name: t.name, description: t.description, parameters: t.inputSchema },
}));

// Anthropic
const anthropicTools = tools.map((t) => ({ name: t.name, description: t.description, input_schema: t.inputSchema }));

// Vercel AI SDK
import { tool, jsonSchema } from "ai";
const aiTools = Object.fromEntries(tools.map((t) => [
  t.name,
  tool({ description: t.description, inputSchema: jsonSchema(t.inputSchema), execute: t.execute }),
]));

모델 응답의 도구 호출 형식과 실행 결과를 반환하는 메시지 형식은 제공자마다 다릅니다. Anthropic Messages는 assistant의 tool_use를 대화에 보존한 뒤 같은 ID의 tool_result를 user 메시지로 반환합니다. 허용 목록·인자 검증·사용자 승인·실행 제한을 포함한 예제는 Editor AI SDK 빠른 시작을 따릅니다. 사용할 프레임워크 버전의 반복 종료 조건도 명시적으로 설정합니다.

`registerTool` 콜백에 등록

도구 배열 대신 레지스트리 콜백을 노출하는 프레임워크에는 registerTools()가 카탈로그 전체를 등록합니다. getTools() 위에 구현되어 있으며, 기본 포맷터는 결과를 MCP 텍스트 형태로 감쌉니다.

const schemas = await word.registerTools(modelContext, {
  formatResult: (result) => result,                       // pass the editor result through
  formatError: (error) => ({ isError: true, content: [{ type: "text", text: error.message }] }),
});

modelContext는 애플리케이션이 사용하는 프레임워크의 registerTool 콜백 객체입니다. 이 예제는 해당 객체가 준비된 상태를 전제로 합니다. 스택 추적, 내부 URL, 스토리지 경로, 자격 증명을 모델에 반환하지 않습니다.

스키마와 모듈 프롬프트 조회

const schemas = await word.getToolSchemas();          // name, description, inputSchema - no executors
const prompt = await word.getSystemPrompt();          // module-provided system prompt; "" when not provided

파괴적인 작업 확인

광범위하거나 파괴적인 변경, 특히 AI 에이전트를 통해 Editor SDK를 호출할 때는:

현재 상태를 읽습니다.
변경 계획을 만들어 표시합니다.
사용자 확인을 요구합니다.
가장 작은 작업 집합을 적용합니다.
명시적으로 저장합니다.
영향을 받은 상태를 다시 읽어 결과를 확인합니다.

SDK 오류

SDK가 소유한 모든 실패는 SDKError(code, message, 선택적 data)로 거부됩니다.

코드	상수	의미	일반적인 복구
1001	`INVALID_ARGUMENT`	잘못된 모듈·origin·iframe 대상, 또는 다른 모듈에 이미 바인딩된 iframe	재시도 전에 구성을 수정
1002	`TIMEOUT`	편집기가 제한 시간 안에 응답하지 않음	`whenReady()`로 대기, origin 확인 후 의도적으로 재시도
1003	`DESTROYED`	`disconnect()` 이후 핸들 사용	`Office.word(iframe)`으로 새 핸들 획득
1004	`INVALID_RESPONSE`	응답 envelope를 파싱할 수 없음	편집기/SDK 호환성 확인
1005	`NETWORK_ERROR`	`postMessage` 전송 실패	대상 창 수명 주기 확인
2000	`FRAMEWORK_ERROR`	편집기 작업 실패	`error.data.error.code`와 사용자 입력 검사

문서 작업이 실패하면 error.data는 편집기의 구조화된 응답 { success: false, error: { code, message } }입니다. 메시지를 파싱하지 말고 error.data.error.code(예: SHEET_NOT_FOUND)로 분기하십시오.

import { SDKError, SDK_ERROR_CODE } from "@thinkfree.dev/tfo-sdk";

try {
  await word.getDocument().save();
} catch (error) {
  if (error instanceof SDKError && error.code === SDK_ERROR_CODE.TIMEOUT) {
    showRetryMessage();
  } else if (error instanceof SDKError && error.data?.success === false) {
    showDocumentOperationError(error.data.error.code);
  } else {
    throw error;
  }
}

showRetryMessage와 showDocumentOperationError는 애플리케이션에서 구현할 오류 안내 함수입니다. 시간 초과 후에도 편집이 반영됐을 수 있으므로 문서 상태를 먼저 확인합니다. 작업이 멱등하다고 확인되지 않는 한 쓰기 작업을 자동 재시도하지 않습니다.

이 가이드로 복구 동작을 정합니다. 메서드 지원 여부와 정확한 매개변수, 반환 타입은 Word, Spreadsheet, Presentation API 레퍼런스에서 확인합니다.

실행 가능한 도구 얻기​

LLM 프레임워크에 연결​

registerTool 콜백에 등록​

스키마와 모듈 프롬프트 조회​

파괴적인 작업 확인​

SDK 오류​