API Reference

This document provides complete API documentation for all public functions, interfaces, and configuration options in the agent-swarm-kit library. It covers the primary APIs developers use to build multi-agent AI systems, including agent creation, session management, tool integration, and system configuration.

For implementation details and usage patterns, see Building Multi-Agent Systems. For configuration best practices, see Configuration and Global Settings.

Agent and Tool APIs

Agent Definition

Agents are defined using addAgent() with an IAgentSchemaInternal configuration. Each agent has a prompt, optional tools, completion model, and lifecycle callbacks.

interface IAgentSchemaInternal {
  agentName: AgentName;
  prompt?: string | ((clientId: string, agentName: AgentName) => Promise<string> | string);
  completion?: CompletionName;
  tools?: ToolName[];
  system?: string[];
  systemStatic?: string[];
  systemDynamic?: (clientId: string, agentName: AgentName) => Promise<string[]> | string[];
  operator?: boolean;
  connectOperator?: (clientId: string, agentName: AgentName) => (message: string, next: (answer: string) => void) => DisposeFn;
  maxToolCalls?: number;
  keepMessages?: number;
  validate?: (output: string) => Promise<string | null>;
  transform?: (input: string, clientId: string, agentName: AgentName) => Promise<string> | string;
  map?: (message: IModelMessage, clientId: string, agentName: AgentName) => IModelMessage | Promise<IModelMessage>;
  mapToolCalls?: (tool: IToolCall[], clientId: string, agentName: AgentName) => IToolCall[] | Promise<IToolCall[]>;
  storages?: StorageName[];
  states?: StateName[];
  mcp?: MCPName[];
  dependsOn?: AgentName[];
  // Lifecycle callbacks
  callbacks?: Partial<IAgentSchemaInternalCallbacks>;
}

Tool Definition

Tools are defined using addTool() with an IAgentTool interface that specifies execution logic, validation, and OpenAI-compatible function metadata.

interface IAgentTool<T = Record<string, ToolValue>> {
  toolName: ToolName;
  type: ITool['type'];
  function: ITool['function'] | ((clientId: string, agentName: AgentName) => ITool['function'] | Promise<ITool['function']>);
  call(dto: {
    toolId: string;
    clientId: string;
    agentName: AgentName;
    params: T;
    toolCalls: IToolCall[];
    abortSignal: TAbortSignal;
    callReason: string;
    isLast: boolean;
  }): Promise<void>;
  validate?: (dto: {
    clientId: string;
    agentName: AgentName;
    toolCalls: IToolCall[];
    params: T;
  }) => Promise<boolean> | boolean;
  callbacks?: Partial<IAgentToolCallbacks>;
}

Agent Execution Flow

Mermaid Diagram

Session and Swarm APIs

Session Management

Sessions are created using session() and provide the primary interface for client interactions with the swarm system.

interface ISession {
  notify(message: string): Promise<void>;
  emit(message: string): Promise<void>;
  run(content: string): Promise<string>;
  execute(content: string, mode: ExecutionMode): Promise<string>;
  connect(connector: SendMessageFn, ...args: unknown[]): ReceiveMessageFn<string>;
  commitUserMessage(content: string): Promise<void>;
  commitAssistantMessage(content: string): Promise<void>;
  commitSystemMessage(content: string): Promise<void>;
  commitToolOutput(toolId: string, content: string): Promise<void>;
  commitFlush(): Promise<void>;
  commitStopTools(): Promise<void>;
  commitToolRequest(request: IToolRequest[]): Promise<void>;
  cancelOutput(): Promise<void>;
  dispose(): Promise<void>;
}

Swarm Configuration

Swarms are configured using addSwarm() with an ISwarmSchema that defines agents, default agent, policies, and navigation behavior.

interface ISwarmSchema {
  swarmName: SwarmName;
  agents: AgentName[];
  defaultAgent: AgentName;
  policies?: PolicyName[];
  callbacks?: Partial<ISwarmCallbacks>;
}

Storage and State APIs

Storage Interface

The IStorage interface provides embedding-based storage with similarity search capabilities.

interface IStorage<T extends IStorageData = IStorageData> {
  take(search: string, total: number, score?: number): Promise<T[]>;
  upsert(item: T): Promise<void>;
  remove(itemId: IStorageData["id"]): Promise<void>;
  get(itemId: IStorageData["id"]): Promise<T | null>;
  list(filter?: (item: T) => boolean): Promise<T[]>;
  clear(): Promise<void>;
}

State Interface

The IState interface provides key-value state management with middleware support.

interface IState<T extends IStateData = IStateData> {
  read(): Promise<T>;
  write(state: T): Promise<void>;
  clear(): Promise<void>;
}

Configuration APIs

Global Configuration

The system behavior is controlled through GLOBAL_CONFIG which can be modified using setConfig().

interface IGlobalConfig {
  CC_TOOL_CALL_EXCEPTION_FLUSH_PROMPT: string;
  CC_TOOL_CALL_EXCEPTION_RECOMPLETE_PROMPT: string;
  CC_EMPTY_OUTPUT_PLACEHOLDERS: string[];
  CC_KEEP_MESSAGES: number;
  CC_MAX_TOOL_CALLS: number;
  CC_LOGGER_ENABLE_INFO: boolean;
  CC_LOGGER_ENABLE_DEBUG: boolean;
  CC_LOGGER_ENABLE_LOG: boolean;
  CC_RESQUE_STRATEGY: "flush" | "recomplete" | "custom";
  CC_STORAGE_SEARCH_SIMILARITY: number;
  CC_STORAGE_SEARCH_POOL: number;
  // ... additional configuration options
}

// Usage
import { setConfig } from 'agent-swarm-kit';

setConfig({
  CC_LOGGER_ENABLE_DEBUG: true,
  CC_MAX_TOOL_CALLS: 3,
  CC_RESQUE_STRATEGY: "recomplete"
});

Event System APIs

Event Bus

The IBus interface provides event-driven communication across the system.

interface IBus {
  emit<T extends IBaseEvent = IBusEvent>(clientId: string, event: T): Promise<void>;
  subscribe<T extends IBaseEvent = IBusEvent>(
    clientId: string,
    eventType: EventSource,
    listener: (event: T) => void
  ): Subject<void>;
}

Event Types

interface IBusEvent extends IBaseEvent {
  type: "run" | "emit" | "execute" | "push" | "pop" | "init" | "dispose" | "connect" | "disconnect";
  source: EventSource;
  input: Record<string, unknown>;
  output: Record<string, unknown>;
  context: IBusEventContext;
  clientId: string;
}

Function Reference

Setup Functions

Function	Purpose	Returns
`addAgent(schema: IAgentSchemaInternal)`	Define an agent with prompt, tools, and completion model	`void`
`addSwarm(schema: ISwarmSchema)`	Define a swarm with agents and navigation rules	`void`
`addTool(tool: IAgentTool)`	Register a tool for agent use	`void`
`addCompletion(schema: ICompletionSchema)`	Register an AI completion provider	`void`
`addStorage(schema: IStorageSchema)`	Define embedding-based storage	`void`
`addState(schema: IStateSchema)`	Define stateful data management	`void`
`addPolicy(schema: IPolicySchema)`	Define access control policies	`void`
`addEmbedding(schema: IEmbeddingSchema)`	Register embedding provider	`void`

Target Functions

Function	Purpose	Returns
`session(clientId: string, swarmName: string)`	Create session connection	`ReceiveMessageFn<string>`
`complete(message: string)`	Execute message and return response	`Promise<string>`
`execute(message: string, mode?: ExecutionMode)`	Execute with specific mode	`Promise<string>`
`emit(message: string)`	Emit message to session listeners	`Promise<void>`
`runStateless(message: string)`	Run without updating history	`Promise<string>`
`fork(fn: () => Promise<T>)`	Execute in isolated context	`Promise<T>`
`scope(overrides: Partial<ISchemaContext>, fn: () => Promise<T>)`	Execute with schema overrides	`Promise<T>`

Commit Functions

Function	Purpose	Returns
`commitUserMessage(content: string)`	Add user message to history	`Promise<void>`
`commitAssistantMessage(content: string)`	Add assistant response to history	`Promise<void>`
`commitSystemMessage(content: string)`	Add system message to history	`Promise<void>`
`commitToolOutput(toolId: string, content: string)`	Add tool execution result	`Promise<void>`
`commitFlush()`	Clear conversation history	`Promise<void>`
`cancelOutput()`	Cancel current output emission	`Promise<void>`