chai-ai API Reference

This page provides the API reference for the core chai-ai package.

Functions

generateText(options)

A low-level utility to generate a single text response from a language model without any agent loop, tools, or session management.

• Parameters:
  • options: GenerateTextOptions
    • model: LanguageModel — The provider model instance (e.g. google(...) or openai(...)).
    • messages: Message[] — Array of chat messages in the format { role: 'user' | 'assistant' | 'system' | 'tool', content: string }.
    • signal?: AbortSignal — Optional cancellation signal.
• Returns: Promise<GenerateTextResult>
  • { text: string, usage?: TokenUsage }

import { generateText } from "chai-ai";
import { google } from "@chai-ai/google";

const result = await generateText({
  model: google("gemini-3.1-pro-preview"),
  messages: [{ role: "user", content: "Hello!" }],
});

tool(options)

A type-inference identity helper for defining tools. Ensures that the execute argument is correctly inferred from the provided Zod inputSchema.

• Parameters:
  • options: ToolOptions
    • description: string — A description of the tool (used by models to understand when to invoke it).
    • inputSchema: ZodSchema — A Zod schema validating input arguments.
    • execute: (input: T) => Promise<unknown> | unknown — The execution callback.
• Returns: Tool object.

import { tool } from "chai-ai";
import { z } from "zod";

const calculator = tool({
  description: "Adds two numbers",
  inputSchema: z.object({ a: z.number(), b: z.number() }),
  execute: ({ a, b }) => a + b,
});

createSession(options)

Initializes a persistent or in-memory session wrapper bound to a specific session ID.

• Parameters:
  • options
    • id: string — Unique identifier for the session.
    • store?: SessionStore — Custom session storage implementation. If omitted, defaults to InMemorySessionStore.
• Returns: Session

Classes

Agent

The main class representing an AI agent. Manages system instructions, models, custom tools, session persistence, guardrails, and timeouts.

Constructor

new Agent(options: AgentOptions)

• Options:
  • name: string — Name of the agent.
  • instructions: string — System prompt guiding the agent's behavior.
  • model: LanguageModel — The language model instance.
  • tools?: Record<string, Tool> — Optional lookup map of tools.
  • maxSteps?: number — Step budget limit (default: 5).
  • handoffs?: Agent[] — Array of agents this agent can transfer execution to.
  • maxHandoffs?: number — Handoff cap (default: 5).
  • inputGuardrails?: InputGuardrail[] — Pre-run verification checks.
  • toolGuardrails?: ToolGuardrail[] — Pre-tool-call checks.
  • outputGuardrails?: OutputGuardrail[] — Final-response checks and text transformations.
  • onApprovalRequired?: (args: { toolName: string, reason: string }) => Promise<boolean> | boolean — Callback handling tool approval gates.
  • modelTimeoutMs?: number — Model API timeout (default: 60000).
  • toolTimeoutMs?: number — Tool execution timeout (default: 30000).

Methods

• generate(options): Promise<GenerateResult<Output>> Drains the agent execution loop and returns the final response.
  • options: GenerateOptions
    • prompt: string — The user input prompt.
    • session?: Session — Optional persistent chat session.
    • outputSchema?: ZodSchema — Optional schema validating the final returned JSON structure.
• stream(options): AsyncGenerator<AgentEvent> Executes the agent loop and streams incremental tokens, tool activities, handoff events, and guardrail warnings as they occur. Same options as .generate().

InMemorySessionStore

The default session storage implementation. Stores session history records in an in-memory Map. Resets on process restarts.

FileSessionStore

A Node-specific file-system-based session storage adapter. Saves each session's history as a JSON file named <directory>/<sessionId>.json.

• Constructor: new FileSessionStore(directory: string)

AgentError

An error thrown when the agent loop fails (e.g., timeout, steps budget exceeded, or blocked by an input guardrail).

• Properties:
  • runId: string — The identifier of the failed execution.
  • trace: TraceEntry[] — Chronological log of steps executed prior to failure.

Key Interfaces and Types

AgentEvent

A union type for events emitted by Agent.stream():

• { type: 'run_started', runId: string }
• { type: 'text_delta', delta: string }
• { type: 'tool_started', toolName: string, args: unknown }
• { type: 'tool_completed', toolName: string, result: unknown, error?: string }
• { type: 'handoff_started', fromAgent: string, toAgent: string, reason?: string }
• { type: 'guardrail_triggered', guardrailName: string, action: string }
• { type: 'run_completed', runId: string, text: string, output?: unknown, totalUsage?: TokenUsage }
• { type: 'run_failed', runId: string, error: string }

TraceEntry

Entries recorded during execution tracking:

• model_call: Records details of model requests.
• tool_call: Records argument details and outputs of executed tools.
• handoff: Logs agent control transfers.
• guardrail: Logs guardrail actions (allow, block, approved, denied).
• output_validation: Logs Zod output validation parse outcomes.
• run_completed: Logs final metrics on successful completion.
• run_failed: Logs details of execution crashes.