API Reference

Complete API documentation for AgentKit. Learn how to create AI agents, define tools, and build powerful applications.

Installation

Install the AgentKit SDK via npm to get started building AI agents:

npm install @agentage/sdk

Core Functions

AgentKit provides two primary functions for building AI agents:

agent() - Creates an AI agent that can process messages and execute tools
tool() - Creates a tool with type-safe input validation

`agent()`

Creates an AI agent that can process messages and execute tools.

Signature

function agent(name: string): Agent
function agent(config: AgentConfig): Agent

Parameters

Pattern 1: Builder

name (string) - Name identifier for the agent

Pattern 2: Config Object

config (AgentConfig) - Complete agent configuration object

Examples

Builder Pattern:

import { agent } from '@agentage/sdk';

const assistant = agent('my-assistant')
  .model('gpt-4')
  .instructions('You are helpful');

const response = await assistant.send('Hello');
console.log(response.content);

Config Object Pattern:

const assistant = agent({
  name: 'my-assistant',
  model: 'gpt-4',
  instructions: 'You are helpful'
});

await assistant.send('Hello');

`tool()`

Creates a tool that agents can execute with type-safe input validation.

Signature

function tool<TSchema, TResult>(
  config: CreateToolConfig<TSchema>,
  execute: ToolExecuteFunction<TSchema, TResult>
): Tool<InferSchemaType<TSchema>, TResult>

Parameters

config (CreateToolConfig) - Tool configuration
- name - Unique tool identifier
- description - What the tool does
- inputSchema - Zod schema for validation
- title (optional) - Display name
execute (ToolExecuteFunction) - Async function that executes the tool

Example

import { tool } from '@agentage/sdk';
import { z } from 'zod';

const calculator = tool(
  {
    name: 'calculator',
    description: 'Performs basic math operations',
    inputSchema: z.object({
      operation: z.enum(['add', 'subtract', 'multiply', 'divide']),
      a: z.number(),
      b: z.number(),
    }),
  },
  async (params) => {
    const { operation, a, b } = params;
    switch (operation) {
      case 'add': return a + b;
      case 'subtract': return a - b;
      case 'multiply': return a * b;
      case 'divide': return a / b;
    }
  }
);

Agent Interface

The Agent interface provides methods for configuring and using agents.

interface Agent {
  model(modelName: string, config?: ModelConfig): Agent;
  instructions(text: string): Agent;
  tools(toolList: Tool[]): Agent;
  config(configEntries: ConfigEntry[]): Agent;
  send(message: string): Promise<AgentResponse>;
  stream(message: string): AsyncIterableIterator<AgentResponse>;
}

Methods

`.model(modelName, config?)`

Set the AI model to use.

Returns: Agent (for chaining)

`.instructions(text)`

Set the system instructions for the agent.

Returns: Agent (for chaining)

`.tools(toolList)`

Provide tools the agent can execute.

Returns: Agent (for chaining)

`.send(message)`

Send a message to the agent and get a response.

Returns: Promise<AgentResponse>

Types & Interfaces

AgentConfig

Configuration object for creating agents.

interface AgentConfig {
  name: string;
  model: string | ModelDefinition;
  instructions?: string;
  tools?: Tool[];
}

AgentResponse

Response from agent execution.

interface AgentResponse<T = unknown> {
  content: string;
  metadata?: Record<string, unknown>;
  data?: T;
  toolCalls?: ToolCall[];
}

ModelConfig

Configuration options for AI models.

interface ModelConfig {
  temperature?: number;      // 0.0-1.0
  maxTokens?: number;
  topP?: number;            // 0.0-1.0
  frequencyPenalty?: number; // -2.0-2.0
  presencePenalty?: number;  // -2.0-2.0
}

Note: Temperature controls randomness: 0.0 = deterministic, 1.0 = creative

Error Classes

MissingApiKeyError

Thrown when OpenAI API key is not configured.

Solution: Set OPENAI_API_KEY environment variable or use .config()

UnsupportedModelError

Thrown when using an unsupported model.

Solution: Use supported models (gpt-4, gpt-3.5-turbo)

ToolNotFoundError

Thrown when agent tries to execute a tool that doesn't exist.

Complete Examples

Basic Agent

import { agent } from '@agentage/sdk';

const assistant = agent('assistant')
  .model('gpt-4')
  .instructions('Be helpful and concise');

const response = await assistant.send('What is Node.js?');
console.log(response.content);

Agent with Tools

import { agent, tool } from '@agentage/sdk';
import { z } from 'zod';

const weatherTool = tool(
  {
    name: 'get_weather',
    description: 'Get current weather for a city',
    inputSchema: z.object({
      city: z.string(),
    }),
  },
  async ({ city }) => {
    return `Weather in ${city}: Sunny, 72°F`;
  }
);

const assistant = agent('weather-bot')
  .model('gpt-4')
  .instructions('Help users with weather information')
  .tools([weatherTool]);

const response = await assistant.send('What is the weather in London?');
console.log(response.content);

Error Handling

import { MissingApiKeyError } from '@agentage/sdk';

try {
  const response = await agent('test')
    .model('gpt-4')
    .send('Hello');
  console.log(response.content);
} catch (error) {
  if (error instanceof MissingApiKeyError) {
    console.error('Please set OPENAI_API_KEY');
  }
}

Next Steps

Now that you understand the API, explore these resources:

View on GitHub

See the source code

Browse Examples

Learn from code samples