Extensions

Extension이란?

Extension은 ExtensionAPI를 받아서 다음을 할 수 있는 함수(또는 모듈)입니다:

• 추가 도구 등록
• 에이전트 이벤트 구독
• 에이전트 이름에 접근

Extension을 사용하면 재사용 가능한 에이전트 기능을 모듈로 패키징할 수 있습니다.

인라인 Extension

import { Agent } from "@schift-io/sdk";
import type { ExtensionAPI } from "@schift-io/sdk";

const loggingExtension = (api: ExtensionAPI) => {
  api.on("tool_call", (event) => {
    console.log(`[${api.agentName}] calling ${event.toolName}`);
  });

  api.on("agent_end", (event) => {
    console.log(`[${api.agentName}] done in ${event.totalDurationMs}ms`);
  });
};

const agent = new Agent({
  name: "My Agent",
  instructions: "...",
  extensions: [loggingExtension],
  transport: schift.transport,
});

모듈 Extension

Extension을 파일 경로에서 로드할 수도 있습니다. 모듈은 default 또는 init 함수를 export해야 합니다:

extensions/analytics.ts

import type { ExtensionAPI } from "@schift-io/sdk";

export default function init(api: ExtensionAPI) {
  api.registerTool({
    name: "track_event",
    description: "Track an analytics event",
    parameters: {
      type: "object",
      properties: {
        event: { type: "string", description: "Event name" },
      },
      required: ["event"],
    },
    handler: async (args) => {
      await sendToAnalytics(String(args.event));
      return { success: true, data: { tracked: true } };
    },
  });
}

const agent = new Agent({
  extensions: ["./extensions/analytics.ts"],
  ...
});

ExtensionAPI

메서드 / 속성	설명
registerTool(tool)	에이전트에서 사용할 도구 등록
on(type, handler)	에이전트 이벤트 구독. 구독 해제 함수 반환
off(type, handler)	이벤트 구독 해제
agentName	에이전트의 표시 이름 (읽기 전용)

Extension은 첫 agent.run() 호출 시 한 번 로드됩니다. Extension이 등록한 도구는 에이전트 전체 수명 동안 사용 가능합니다.