Documentation

Agent SDK

AgentBuilder Class

The AgentBuilder class is the core of the SDK. It takes a configuration, registers tools, and builds an executable handler function.

createAgent(config)

The recommended way to create an agent. Returns an AgentBuilder instance:

TypeScript
import { createAgent } from "@skillswarm/agent-sdk";

const agent = createAgent({
  name: "My Agent",
  systemPrompt: "You are a helpful assistant.",
});

Constructor

TypeScript
class AgentBuilder {
  constructor(config: AgentConfig)
}

Creates a new AgentBuilder with the given configuration. Initializes with defaults:

  • model: "gemini-3-flash-preview"
  • temperature: 0.7
  • maxTokens: 4096

registerTool(tool)

TypeScript
registerTool(tool: ToolDefinition): this

Registers a tool by storing it in an internal Map keyed by tool name. Returns this for chaining:

TypeScript
import { createAgent, tools } from "@skillswarm/agent-sdk";

const agent = createAgent({ name: "Agent", systemPrompt: "..." })
  .registerTool(tools.webSearch)
  .registerTool(tools.csvParse)
  .registerTool(tools.statistics);

Alternatively, pass tools via the tools array in the config — they are registered automatically:

TypeScript
const agent = createAgent({
  name: "Agent",
  systemPrompt: "...",
  tools: [tools.webSearch, tools.csvParse, tools.statistics],
});

build()

TypeScript
build(): AgentHandler

Compiles the agent into an executable handler function. The returned AgentHandler is an async function:

TypeScript
type AgentHandler = (input: AgentInput) => Promise<AgentOutput>;

Build Pipeline

When build() is called, the builder:

  1. Converts tools to Gemini format — Each ToolDefinition's Zod schema is converted to a Gemini FunctionDeclaration.
  2. Initializes the LLM client — Creates a GeminiClient with the configured model, temperature, and max tokens.
  3. Returns the handler — An async function that processes inputs through the LLM with tool calling.

Execution Flow

When the handler is invoked with an input:

  1. Constructs a chat session with the systemPrompt and any context messages
  2. Sends the user message to the LLM
  3. Tool calling loop — If the LLM requests tool calls:
    • Executes each tool with the provided arguments
    • Sends tool results back to the LLM
    • Repeats until the LLM produces a final text response
  4. Returns an AgentOutput with the response, tool calls made, and token usage

AgentInput

TypeScript
interface AgentInput<T = unknown> {
  taskId: string;           // Unique task identifier
  userId: string;           // User who initiated the task
  userEmail: string;        // User's email address
  data: T;                  // Task-specific input data
  integrations: {           // Enabled third-party integrations
    googleDrive?: boolean;
    googleCalendar?: boolean;
    gmail?: boolean;
    notion?: boolean;
    slack?: boolean;
  };
  context?: {               // Conversation context
    messages: Message[];    // Previous messages
    metadata?: Record<string, unknown>;
  };
}

AgentOutput

TypeScript
interface AgentOutput {
  success: boolean;                    // Whether execution succeeded
  message: string;                     // The agent's response text
  data?: Record<string, unknown>;      // Structured output data
  artifacts?: Artifact[];              // Files, links, images etc.
  toolCalls?: ToolCall[];              // Tools that were executed
  usage?: TokenUsage;                  // LLM token consumption
}

ToolCall

TypeScript
interface ToolCall {
  name: string;                        // Tool identifier (e.g., "web_search")
  args: Record<string, unknown>;       // Arguments passed to the tool
  result: unknown;                     // Tool's return value
  durationMs: number;                  // Execution time in milliseconds
}

Artifact

TypeScript
interface Artifact {
  type: "file" | "link" | "text" | "image";
  name: string;
  url?: string;
  content?: string;
  mimeType?: string;
}

TokenUsage

TypeScript
interface TokenUsage {
  promptTokens: number;
  completionTokens: number;
  totalTokens: number;
}

ToolDefinition

TypeScript
interface ToolDefinition {
  name: string;                               // Unique tool ID (e.g., "web_search")
  description: string;                        // What the tool does (shown to LLM)
  parameters: z.ZodObject<any>;               // Zod schema for input validation
  execute: (args: unknown) => Promise<unknown>; // Execution function
}

The Zod schema is converted to JSON Schema for the LLM and used to validate arguments at runtime. See Tools Reference for all 17 built-in tool definitions.

Complete Example

TypeScript
import { createAgent, tools } from "@skillswarm/agent-sdk";
import type { AgentInput, AgentOutput } from "@skillswarm/agent-sdk";

// 1. Create and configure
const agent = createAgent({
  name: "Data Analyst Pro",
  systemPrompt: `You are an expert data analyst.
    Analyze CSV data, compute statistics, and generate charts.`,
  model: "gemini-3-flash-preview",
  temperature: 0.3,
  tools: [
    tools.csvParse,
    tools.statistics,
    tools.generateChart,
    tools.markdownTable,
  ],
});

// 2. Build the handler
const handler = agent.build();

// 3. Execute
const result: AgentOutput = await handler({
  taskId: "task-001",
  userId: "user-001",
  userEmail: "analyst@example.com",
  data: {
    csv: "name,revenue\nAlpha,50000\nBeta,75000\nGamma,30000",
  },
  integrations: {},
  context: {
    messages: [
      { role: "user", content: "Analyze this revenue data" },
    ],
  },
});

// result.success === true
// result.message === "Here's your analysis..."
// result.toolCalls === [{ name: "csv_parse", ... }, { name: "statistics", ... }]

Next Steps