Extensions

What is an Extension?

An Extension is a function (or module) that receives an ExtensionAPI and can:

• Register additional tools
• Subscribe to agent events
• Access the agent’s name for context

Extensions let you package reusable agent capabilities as modules.

Inline 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,
});

Module Extension

Extensions can also be loaded from file paths. The module must export a default or init function:

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

Method / Property	Description
registerTool(tool)	Register a tool available to the agent
on(type, handler)	Subscribe to agent events. Returns unsubscribe function
off(type, handler)	Unsubscribe from an event
agentName	The agent’s display name (readonly)

Extensions are loaded once during the first agent.run() call. Tools registered by extensions are available for the entire agent lifetime.