Quickstart

로그인이나 회원가입 없이 무료로 Office를 설치하고 문서를 편집해 보세요. Editor SDK를 사용해 웹브라우저에 열린 문서를 JavaScript로 직접 제어해 보세요. AI Agent를 개발하고 계신가요? Editor AI SDK를 이용하면 여러분의 AI Agent에 문서 편집 기능을 추가할 수 있습니다.

Office 준비하기

1. 컨테이너 실행

Docker를 설치하고 최소 CPU 2코어와 메모리 4 GB를 확보합니다. 터미널에서 아래 명령으로 30일간 유효한 Trial 라이선스가 포함된 Office 컨테이너를 실행합니다.

상업적으로 사용 가능한 무료 라이선스

상업적으로 사용할 수 있는 Free Commercial 라이선스도 무료로 제공합니다. 자세한 내용은 Free Commercial 라이선스 안내를 참고하세요.

docker run --name thinkfree-office-trial \
  -p 8080:8070 \
  thinkfree/office-single-node-trial:latest

Office 초기화에는 약 2분이 걸리며, 실행 환경에 따라 달라질 수 있습니다. 실행 로그가 표시되는 터미널을 켜 둔 채 웹브라우저에서 다음 단계를 진행합니다.

2. 샘플 열기

컨테이너 안에 샘플 문서와 미리 연결된 host-storage 어댑터가 준비되어 있습니다. Office 초기화가 완료되면 바로 문서를 열어 볼 수 있습니다.

아래 주소를 웹브라우저에서 엽니다. 링크를 클릭하면 새 탭에서 샘플 문서가 열립니다.

http://localhost:8080/cloud-office/api/host-storage/sample.docx/open?app=WORD_EDITOR&user_id=local-user&docId=quickstart01 ↗

Word 편집기가 열리면 샘플 문서의 내용을 편집할 수 있습니다.

3. 문서 디렉토리 연결하기

기존에 실행 중인 컨테이너를 중지합니다. 아래 명령과 같이 -v 옵션으로 내 컴퓨터의 문서 디렉터리를 컨테이너의 /home/thinkfree/docs에 연결합니다.

docker run --name thinkfree-office-documents \
  -p 8080:8070 \
  -v "/absolute/path/to/documents:/home/thinkfree/docs" \
  thinkfree/office-single-node-trial:latest

문서를 여는 URL은 다음 형식입니다. {relative-file-path}에는 문서 디렉터리를 기준으로 한 파일의 상대 경로를 넣습니다.

http://localhost:8080/cloud-office/api/host-storage/{relative-file-path}/open?app=WORD_EDITOR&user_id=local-user&docId=quickstart01

예를 들어 내 컴퓨터의 /absolute/path/to/documents/reports/proposal.docx를 열려면 상대 경로 reports/proposal.docx를 넣어 다음 URL을 만듭니다.

http://localhost:8080/cloud-office/api/host-storage/reports/proposal.docx/open?app=WORD_EDITOR&user_id=local-user&docId=quickstart01 ↗

파일명이나 폴더명에 공백이나 URL 인코딩이 필요한 문자가 있으면 /로 구분된 각 이름을 인코딩합니다.

Editor SDK

Editor SDK를 사용하면 웹브라우저에 열려 있는 문서를 제어할 수 있습니다.

애플리케이션 페이지에 다음 iframe을 추가합니다.

<iframe
  id="office-frame"
  title="Thinkfree Office document"
  src="http://localhost:8080/cloud-office/api/host-storage/sample.docx/open?app=WORD_EDITOR&user_id=local-user&docId=quickstart01"
  style="width: 100%; height: 600px; border: 0;"
></iframe>

Editor SDK는 npm에 공개된 @thinkfree.dev/tfo-sdk 패키지로 제공합니다. 프로젝트 디렉터리에서 다음 명령으로 설치합니다.

npm install @thinkfree.dev/tfo-sdk

설치가 완료되면 위 iframe을 추가한 페이지에서 아래 JavaScript 코드를 실행합니다.

import { Office } from "@thinkfree.dev/tfo-sdk";

// Connect to the already-open Word editor.
const word = Office.word(document.querySelector("#office-frame"));
await word.whenReady();

// Read the document body.
const doc = word.getDocument();
const body = await doc.getBody();
console.log(await body.getText());

웹브라우저 콘솔에 문서 본문이 출력되면 SDK 연결과 Editor SDK 함수 호출이 정상적으로 동작한 것입니다. 이어서 아래 코드로 문단을 추가하고 저장할 수 있습니다.

// Append a paragraph without replacing existing text, then save.
await body.insertParagraph("Hello from Editor SDK", { position: "end" });
await doc.save();

데스크톱 Chrome/Edge에서는 아래 코드를 실행하면 웹브라우저의 인쇄 창이 열립니다.

// Open printing. In desktop Chrome/Edge, choose "Save as PDF".
// This does not return PDF bytes or confirm that a file was saved.
await doc.print();

애플리케이션을 종료하거나 편집 화면을 떠날 때 word.disconnect()를 호출해 SDK 연결을 해제해 주세요.

Editor SDK Playground에서는 Office를 설치하지 않고도 SDK 기능을 직접 실행해 볼 수 있습니다. SDK에 대한 자세한 내용은 Editor SDK 가이드에서 확인하세요.

Editor AI SDK

Editor AI SDK는 npm에 공개된 @thinkfree.dev/tfo-ai-sdk 패키지로 제공합니다. Editor SDK가 필요하므로 두 패키지를 함께 설치합니다.

npm install @thinkfree.dev/tfo-sdk @thinkfree.dev/tfo-ai-sdk

Editor AI SDK는 AI Agent가 Office 편집기를 쉽게 사용할 수 있도록 여러 기능을 제공합니다. bridgeToolsViaSdk()로 Editor SDK의 Tool을 AI Agent의 연결부에 등록할 수 있습니다. 각 Tool에는 이름, 설명, 입력 스키마와 execute(args)가 포함됩니다. AI Agent가 상황에 맞는 Tool을 선택한 뒤 해당 Tool의 execute(args)를 호출하면 Editor SDK로 연결된 Office 문서를 읽거나 편집할 수 있습니다.

AI Agent가 모델 연결, 대화 이력 관리, Tool 선택, 권한 검증 등을 수행하고, Editor AI SDK는 Office 문서의 기능을 조회하고 실행하는 부분을 담당합니다.

아래 코드의 askAgent, validateAndApprove, returnToolResult는 AI Agent 쪽에서 구현해야 할 함수입니다. AI Agent의 흐름에 맞춰 Editor AI SDK 함수를 연결할 수 있습니다. 아래 연결부는 등록된 Tool 중 insert_text만 보관해 AI Agent에 제공합니다. Tool 정의와 응답 형식은 코드 주석을 참고하세요.

import { bridgeToolsViaSdk } from "@thinkfree.dev/tfo-ai-sdk";

// Continue with the connected word handle from the Editor SDK section.
await word.whenReady();

const agentTools = new Map();
const toolBridge = await bridgeToolsViaSdk(word, {
  registerTool(tool) {
    // Expose only the tool approved for this task.
    if (tool.name === "insert_text") agentTools.set(tool.name, tool);
  },
  unregisterTool(name) { agentTools.delete(name); },
});
window.addEventListener("pagehide", () => toolBridge.unregisterAll());

// Customer-owned integration hooks, NOT Editor AI SDK methods:
// askAgent: send tools to your agent/model in its required schema format;
// normalize its response to { toolCalls: [{ id, name, args }] }.
// validateAndApprove: validate args against inputSchema, check permissions,
// and obtain any required user confirmation; reject by throwing an error.
// returnToolResult: return the result to the same agent conversation by call ID.
async function runAgentTurn({ askAgent, validateAndApprove, returnToolResult }) {
  const tools = [...agentTools.values()];
  const definitions = tools.map(({ name, description, inputSchema }) => ({
    name, description, inputSchema,
  }));

  // Your agent receives schemas, not JavaScript execute functions.
  // Its model chooses a tool and arguments; the SDK does not choose them.
  const response = await askAgent({
    instruction: "Insert a paragraph saying Hello from the agent.",
    tools: definitions,
  });

  for (const call of response.toolCalls ?? []) {
    const tool = tools.find((item) => item.name === call.name);
    if (!tool) throw new Error("Tool is not allowed: " + call.name);
    await validateAndApprove({ call, inputSchema: tool.inputSchema });

    // For an insert_text selection, this is that tool object's execute(args).
    // Editor AI SDK dispatches the call to the connected Office editor.
    const result = await tool.execute(call.args);

    // Preserve content/isError and the call ID so your agent can continue.
    await returnToolResult({ toolCallId: call.id, result });
  }
}
// Call runAgentTurn with your own three implementations.
// This example defines one turn; it does not create or run an AI agent.

예를 들어 AI Agent가 insert_text와 인자를 반환하면, 허용된 Tool인지 확인하고 인자를 검증한 뒤 해당 Tool의 execute(args)를 호출합니다. 결과에 isError가 있으면 성공으로 처리하지 않고 AI Agent에 그대로 전달합니다.

Editor AI SDK를 연결한 AI Agent의 동작을 직접 확인할 수 있도록 Editor AI SDK Playground를 준비했습니다. 지금 실행해 보세요. 자세한 내용은 Editor AI SDK 가이드를 참고하세요.

Free Commercial 라이선스 안내

Free Commercial 라이선스를 사용하면 Office를 상용 서비스에 무료로 사용할 수 있습니다. 동시 연결 20개(MCC 20)를 지원합니다. 라이선스는 180일 동안 유효하며, 계속해서 연장할 수도 있습니다. 신청·다운로드·설치 방법은 Office 준비하기에서 확인하세요.