Agent SDK

Configuration Reference

Complete reference for the AgentConfig interface and all available configuration options.

AgentConfig Interface

interface AgentConfig {
  name: string;
  systemPrompt: string;
  model?: "gemini-3-flash-preview" | "gemini-1.5-pro" | "claude-sonnet" | "gpt-4o";
  temperature?: number;
  maxTokens?: number;
  tools?: ToolDefinition[];
  knowledgeBaseId?: string;
}

Properties

name required

string — The display name of the agent. Shown on the marketplace, search results, and agent detail page.

name: "Tax Document Analyzer"

Best practices: Use a descriptive, unique name. Include the primary function. Avoid generic names like "My Agent".

systemPrompt required

string — Instructions that define the agent's personality, behavior, and expertise. This is sent to the LLM as the system message before every conversation.

systemPrompt: `You are an expert tax document analyzer.

Your responsibilities:
- Parse uploaded tax documents (W-2, 1099, etc.)
- Extract key financial figures
- Identify potential deductions
- Summarize findings in a structured format

Rules:
- Always cite specific document sections
- Flag any inconsistencies
- Do NOT provide tax advice — only analysis`

See the Prompt Builder guide for tips on writing effective system prompts.

model

string — The LLM model to use. Default: "gemini-3-flash-preview".

temperature

number — Controls randomness in responses. Range: 0–1. Default: 0.7.

• 0.0–0.3 — Focused, deterministic. Best for data analysis, code, factual Q&A.
• 0.4–0.7 — Balanced. Good default for most agents.
• 0.8–1.0 — Creative, varied. Best for brainstorming, creative writing, ideation.

maxTokens

number — Maximum number of tokens in the response. Default: 4096.

Set higher (8192+) for agents that generate long-form content like reports or articles. Set lower (1024–2048) for concise, chat-style responses.

tools

ToolDefinition[] — Array of tools the agent can use. See Tools Reference for all 17 built-in tools.

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

// Select specific tools
tools: [tools.webSearch, tools.csvParse, tools.statistics]

// Or register tools individually via the builder
agent.registerTool(tools.webSearch);

Tools are organized into tiers (free, standard, premium) which affect the agent's marketplace tier badge.

knowledgeBaseId

string — Optional ID for a RAG (Retrieval-Augmented Generation) knowledge base. When set, the agent can retrieve relevant context from the knowledge base before responding.

Execution Context

The runtime provides an ExecutionContext to each agent execution:

interface ExecutionContext {
  env: Record<string, string>;  // Environment variables
  timeout: number;               // Execution timeout (ms)
  maxMemory: number;             // Memory limit (bytes)
}

Default timeout is 60 seconds, maximum 600 seconds. Configure via themaxExecutionTime field when creating the agent through the API.

Message Interface

interface Message {
  role: "user" | "assistant" | "system";
  content: string;
  timestamp?: Date;
}

Messages are passed in context.messages to provide conversation history. The last 20 messages are typically included as context.

Helper: renderTemplate

function renderTemplate(
  template: string,
  variables: Record<string, string>
): string;

Utility function for rendering templates with variable substitution. Uses {{variable}} syntax:

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

const result = renderTemplate(
  "Hello {{name}}, your order #{{orderId}} is ready.",
  { name: "Alice", orderId: "12345" }
);
// "Hello Alice, your order #12345 is ready."

Next Steps

• AgentBuilder Class — Builder methods and execution flow
• Event Handlers — onMessage and lifecycle
• Tools Reference — All 17 tools