@igniter-js/agents 0.1.0

package/dist/index.d.ts

@@ -0,0 +1,3170 @@
+import { ToolSet, LanguageModel, ToolLoopAgent, AgentCallParameters, AgentStreamParameters, Tool } from 'ai';
+import { IgniterLogger, IgniterError } from '@igniter-js/core';
+import { IgniterTelemetryManager } from '@igniter-js/telemetry';
+import { I as IgniterAgentMemoryConfig, a as IgniterAgentMemoryRuntime, b as IgniterAgentWorkingMemoryParams, c as IgniterAgentWorkingMemory, d as IgniterAgentUpdateWorkingMemoryParams, e as IgniterAgentConversationMessage, f as IgniterAgentUIMessage, g as IgniterAgentGetMessagesParams, h as IgniterAgentChatSession, i as IgniterAgentGetChatsParams } from './index-CX4IgrRt.js';
+export { z as IgniterAgentAdapterBatchResult, y as IgniterAgentAdapterFactory, u as IgniterAgentAdapterOptions, A as IgniterAgentAdapterStats, s as IgniterAgentChatsConfig, p as IgniterAgentGenerateSuggestionsConfig, o as IgniterAgentGenerateTitleConfig, r as IgniterAgentHistoryConfig, j as IgniterAgentInMemoryAdapter, v as IgniterAgentInMemoryAdapterOptions, l as IgniterAgentJSONFileAdapter, k as IgniterAgentJSONFileAdapterOptions, x as IgniterAgentMemoryAdapter, t as IgniterAgentMemoryProvider, n as IgniterAgentMemoryScope, m as IgniterAgentMessageRole, w as IgniterAgentRedisAdapterOptions, q as IgniterAgentWorkingMemoryConfig } from './index-CX4IgrRt.js';
+import { z } from 'zod';
+export { IgniterAgentTelemetryEvents, IgniterAgentTelemetryEventsType } from './telemetry/index.js';
+
+/**
+ * @fileoverview Prompt types for IgniterAgent instructions.
+ * @module types/prompt
+ */
+/**
+ * Represents a prompt template that can be built with context.
+ *
+ * @public
+ */
+interface IgniterAgentPromptTemplate<TContext extends Record<string, unknown> = Record<string, unknown>> {
+    /**
+     * Builds the prompt string with the provided context.
+     *
+     * @param context - Context data used for interpolation
+     * @returns The built prompt string
+     */
+    build(context: TContext): string;
+    /**
+     * Returns the raw prompt template.
+     */
+    getTemplate(): string;
+}
+
+/**
+ * @fileoverview Hook types for IgniterAgent lifecycle and execution events.
+ * @module types/hooks
+ */
+/**
+ * Hooks emitted by IgniterAgent runtime.
+ *
+ * @public
+ */
+interface IgniterAgentHooks {
+    /**
+     * Fired when an agent starts successfully.
+     */
+    onAgentStart?: (name: string) => void;
+    /**
+     * Fired when an agent fails to start or errors.
+     */
+    onAgentError?: (name: string, error: Error) => void;
+    /**
+     * Fired when a tool call begins.
+     */
+    onToolCallStart?: (agentName: string, toolName: string, input: unknown) => void;
+    /**
+     * Fired when a tool call completes successfully.
+     */
+    onToolCallEnd?: (agentName: string, toolName: string, output: unknown) => void;
+    /**
+     * Fired when a tool call fails.
+     */
+    onToolCallError?: (agentName: string, toolName: string, error: Error) => void;
+    /**
+     * Fired before connecting to an MCP server.
+     */
+    onMCPStart?: (agentName: string, mcpName: string) => void;
+    /**
+     * Fired when an MCP connection fails.
+     */
+    onMCPError?: (agentName: string, mcpName: string, error: Error) => void;
+}
+
+/**
+ * @fileoverview Common type definitions used across the IgniterAgent library.
+ * This module contains foundational types that are shared between different parts of the agent system.
+ *
+ * @module types/common
+ * @packageDocumentation
+ */
+
+/**
+ * Represents the connection status of a toolset or MCP client.
+ *
+ * @description
+ * Used to track whether a toolset or MCP server is currently available for use.
+ * This status is automatically updated when connections are established or lost.
+ *
+ * @example
+ * ```typescript
+ * const checkToolsetStatus = (status: IgniterAgentConnectionStatus) => {
+ *   if (status === 'connected') {
+ *     console.log('Ready to use tools');
+ *   } else {
+ *     console.log('Toolset unavailable');
+ *   }
+ * };
+ * ```
+ *
+ * @public
+ */
+type IgniterAgentConnectionStatus = "connected" | "disconnected";
+/**
+ * Represents the type of toolset transport protocol.
+ *
+ * @description
+ * Defines how the agent communicates with external tool providers:
+ * - `stdio`: Standard input/output (local process communication)
+ * - `http`: HTTP/HTTPS transport (remote server communication)
+ * - `custom`: User-defined custom tools (inline JavaScript functions)
+ *
+ * @example
+ * ```typescript
+ * // Using different transport types
+ * const stdioTransport: IgniterAgentToolsetType = 'stdio';   // Local MCP server
+ * const httpTransport: IgniterAgentToolsetType = 'http';     // Remote MCP server
+ * const customTransport: IgniterAgentToolsetType = 'custom'; // Inline tools
+ * ```
+ *
+ * @public
+ */
+type IgniterAgentToolsetType = "stdio" | "http" | "custom";
+/**
+ * Utility type that flattens nested toolsets into a single object with prefixed keys.
+ *
+ * @description
+ * When multiple toolsets are registered with an agent, their tools are flattened
+ * into a single namespace using the pattern `{toolsetName}_{toolName}`.
+ * This ensures tool names are unique and identifiable by their source.
+ *
+ * @typeParam TToolsets - Record of toolset names to toolset configurations
+ *
+ * @example
+ * ```typescript
+ * // Given toolsets:
+ * // - github: { createIssue, listRepos }
+ * // - docker: { buildImage, runContainer }
+ *
+ * // Flattened result:
+ * // {
+ * //   github_createIssue: Tool,
+ * //   github_listRepos: Tool,
+ * //   docker_buildImage: Tool,
+ * //   docker_runContainer: Tool
+ * // }
+ * ```
+ *
+ * @public
+ */
+type IgniterAgentFlattenedToolSet<TToolsets extends Record<string, IgniterAgentToolset$1<IgniterAgentToolsetType, string>>> = {
+    [K in keyof TToolsets as `${K & string}_${keyof TToolsets[K]["tools"] & string}`]: TToolsets[K]["tools"][keyof TToolsets[K]["tools"]];
+};
+/**
+ * Represents a collection of tools with metadata about their source and status.
+ *
+ * @description
+ * A toolset is a logical grouping of related tools that share a common purpose
+ * or source (e.g., all GitHub-related tools, all Docker-related tools).
+ *
+ * @typeParam TType - The transport type for this toolset
+ * @typeParam TName - The unique name identifier for this toolset
+ *
+ * @property name - Unique identifier for the toolset
+ * @property type - Transport protocol used ('stdio', 'http', or 'custom')
+ * @property tools - Collection of tool definitions
+ * @property status - Current connection status
+ *
+ * @example
+ * ```typescript
+ * const githubToolset: IgniterAgentToolset<'custom', 'github'> = {
+ *   name: 'github',
+ *   type: 'custom',
+ *   status: 'connected',
+ *   tools: {
+ *     createIssue: createIssueTool,
+ *     listRepos: listReposTool
+ *   }
+ * };
+ * ```
+ *
+ * @public
+ */
+interface IgniterAgentToolset$1<TType extends IgniterAgentToolsetType = IgniterAgentToolsetType, TName extends string = string> {
+    /** Unique identifier for the toolset */
+    readonly name: TName;
+    /** Transport type used by this toolset */
+    readonly type: TType;
+    /** Collection of available tools */
+    readonly tools: ToolSet;
+    /** Current connection status */
+    readonly status: IgniterAgentConnectionStatus;
+}
+/**
+ * Complete configuration object for an IgniterAgent instance.
+ *
+ * @description
+ * This interface defines all the configuration options available when creating
+ * an agent. It supports strong typing through generics to ensure type safety
+ * when accessing toolsets, context, and other agent properties.
+ *
+ * @typeParam TAgentName - The agent's unique name type
+ * @typeParam TAgentModel - The language model type
+ * @typeParam TAgentInstructions - The prompt template type
+ * @typeParam TAgentToolsets - Record of all registered toolsets
+ * @typeParam TAgentMCPConfigs - Record of all MCP configurations
+ * @typeParam TAgentContextSchema - Zod schema for context validation
+ *
+ * @example
+ * ```typescript
+ * const config: IgniterAgentConfig<
+ *   'assistant',
+ *   LanguageModel,
+ *   IgniterAgentPromptTemplate,
+ *   { github: GitHubToolset },
+ *   { filesystem: FileSystemMCP },
+ *   typeof contextSchema
+ * > = {
+ *   name: 'assistant',
+ *   model: openai('gpt-4'),
+ *   instructions: prompt,
+ *   toolsets: { github: githubToolset },
+ *   configs: { filesystem: filesystemConfig },
+ *   schema: contextSchema
+ * };
+ * ```
+ *
+ * @public
+ */
+interface IgniterAgentConfig<TAgentName extends string = string, TAgentModel extends LanguageModel = LanguageModel, TAgentInstructions extends IgniterAgentPromptTemplate = IgniterAgentPromptTemplate, TAgentToolsets extends Record<string, IgniterAgentToolset$1> = Record<string, IgniterAgentToolset$1>, TAgentMCPConfigs extends Record<string, IgniterAgentMCPConfigUnion> = Record<string, IgniterAgentMCPConfigUnion>, TAgentContextSchema extends z.ZodSchema = z.ZodSchema> {
+    /**
+     * Unique name identifier for the agent.
+     * Used for logging, debugging, and multi-agent orchestration.
+     */
+    name: TAgentName;
+    /**
+     * Registered toolsets available to the agent.
+     * Each toolset contains related tools that the agent can invoke.
+     */
+    toolsets: TAgentToolsets;
+    /**
+     * MCP server configurations for external tool providers.
+     * These are lazily initialized when the agent starts.
+     */
+    configs: TAgentMCPConfigs;
+    /**
+     * Prompt instructions defining the agent's behavior and personality.
+     * Uses the IgniterAgentPrompt pattern for dynamic prompt generation.
+     */
+    instructions: TAgentInstructions;
+    /**
+     * The language model used for inference.
+     * Supports any Vercel AI SDK compatible model provider.
+     */
+    model: TAgentModel;
+    /**
+     * Zod schema for validating context passed to the agent.
+     * Ensures type-safe context access in prompt templates.
+     */
+    schema: TAgentContextSchema;
+    /**
+     * Optional memory configuration.
+     */
+    memory?: IgniterAgentMemoryConfig;
+    /**
+     * Optional logger instance for operational logs.
+     */
+    logger?: IgniterLogger;
+    /**
+     * Optional telemetry manager for observability.
+     */
+    telemetry?: IgniterTelemetryManager;
+    /**
+     * Optional hook callbacks for lifecycle/tool/mcp events.
+     */
+    hooks?: IgniterAgentHooks;
+    /**
+     * Agent instance from AI SDK ToolLoopAgent.
+     * @internal
+     */
+    instance?: ToolLoopAgent;
+}
+/**
+ * Base configuration interface for MCP (Model Context Protocol) clients.
+ *
+ * @description
+ * Contains common properties shared between all MCP transport types.
+ *
+ * @typeParam TName - The unique identifier for this MCP configuration
+ *
+ * @public
+ */
+interface IgniterAgentMCPConfigBase<TName extends string = string> {
+    /** Unique name identifier for the MCP configuration */
+    readonly name: TName;
+}
+/**
+ * Configuration for stdio-based MCP transport.
+ *
+ * @description
+ * Used when connecting to MCP servers via standard input/output streams.
+ * This is typically used for local MCP servers running as child processes.
+ *
+ * @typeParam TName - The unique identifier for this MCP configuration
+ *
+ * @example
+ * ```typescript
+ * const filesystemMCP: IgniterAgentMCPStdioConfig<'filesystem'> = {
+ *   type: 'stdio',
+ *   name: 'filesystem',
+ *   command: 'npx',
+ *   args: ['-y', '@modelcontextprotocol/server-filesystem', '/tmp'],
+ *   env: { DEBUG: 'true' }
+ * };
+ * ```
+ *
+ * @public
+ */
+interface IgniterAgentMCPStdioConfig<TName extends string = string> extends IgniterAgentMCPConfigBase<TName> {
+    /** Transport type identifier */
+    readonly type: "stdio";
+    /**
+     * Command to execute the MCP server.
+     * @example 'npx', 'node', 'python'
+     */
+    readonly command: string;
+    /**
+     * Arguments to pass to the command.
+     * @example ['-y', '@modelcontextprotocol/server-filesystem']
+     */
+    readonly args: string[];
+    /**
+     * Optional environment variables for the child process.
+     * @example { DEBUG: 'true', API_KEY: 'xxx' }
+     */
+    readonly env?: Record<string, string>;
+}
+/**
+ * Configuration for HTTP-based MCP transport.
+ *
+ * @description
+ * Used when connecting to remote MCP servers over HTTP/HTTPS.
+ * Supports custom headers for authentication and other purposes.
+ *
+ * @typeParam TName - The unique identifier for this MCP configuration
+ *
+ * @example
+ * ```typescript
+ * const remoteMCP: IgniterAgentMCPHttpConfig<'remote-tools'> = {
+ *   type: 'http',
+ *   name: 'remote-tools',
+ *   url: 'https://mcp.example.com/tools',
+ *   headers: {
+ *     'Authorization': 'Bearer token123'
+ *   }
+ * };
+ * ```
+ *
+ * @public
+ */
+interface IgniterAgentMCPHttpConfig<TName extends string = string> extends IgniterAgentMCPConfigBase<TName> {
+    /** Transport type identifier */
+    readonly type: "http";
+    /**
+     * URL of the remote MCP server.
+     * Must be a valid HTTP or HTTPS URL.
+     */
+    readonly url: string;
+    /**
+     * Optional HTTP headers to include in requests.
+     * Useful for authentication, API keys, etc.
+     */
+    readonly headers?: Record<string, string>;
+}
+/**
+ * Union type for all supported MCP configuration types.
+ *
+ * @description
+ * Discriminated union based on the `type` property, allowing TypeScript
+ * to narrow the type based on runtime checks.
+ *
+ * @typeParam TName - The unique identifier for this MCP configuration
+ *
+ * @example
+ * ```typescript
+ * function handleMCPConfig(config: IgniterAgentMCPConfigUnion) {
+ *   if (config.type === 'stdio') {
+ *     console.log('Command:', config.command);
+ *   } else if (config.type === 'http') {
+ *     console.log('URL:', config.url);
+ *   }
+ * }
+ * ```
+ *
+ * @public
+ */
+type IgniterAgentMCPConfigUnion<TName extends string = string> = IgniterAgentMCPStdioConfig<TName> | IgniterAgentMCPHttpConfig<TName>;
+/**
+ * Fluent builder interface for MCP client configuration.
+ *
+ * @description
+ * Provides a type-safe fluent API for building MCP configurations.
+ * The interface changes based on the transport type selected.
+ *
+ * @typeParam TType - The transport type ('stdio' or 'http')
+ * @typeParam TName - The configuration name
+ *
+ * @example
+ * ```typescript
+ * // Stdio configuration
+ * const stdioConfig = IgniterAgent
+ *   .mcp('filesystem')
+ *   .withType('stdio')
+ *   .withCommand('npx')
+ *   .withArgs(['-y', '@mcp/server-filesystem'])
+ *   .build();
+ *
+ * // HTTP configuration
+ * const httpConfig = IgniterAgent
+ *   .mcp('remote')
+ *   .withType('http')
+ *   .withURL('https://mcp.example.com')
+ *   .withHeaders({ Authorization: 'Bearer xxx' })
+ *   .build();
+ * ```
+ *
+ * @public
+ */
+type IgniterAgentMCPClientInterface<TType extends IgniterAgentToolsetType, TName extends string> = TType extends "stdio" ? IgniterAgentMCPStdioClientInterface<TName> : IgniterAgentMCPHttpClientInterface<TName>;
+/**
+ * Fluent builder interface for stdio MCP configuration.
+ *
+ * @typeParam TName - The configuration name
+ * @internal
+ */
+interface IgniterAgentMCPStdioClientInterface<TName extends string> {
+    /** Set the command to execute */
+    withCommand(command: string): IgniterAgentMCPStdioClientInterface<TName>;
+    /** Set the command arguments */
+    withArgs(args: string[]): IgniterAgentMCPStdioClientInterface<TName>;
+    /** Set environment variables */
+    withEnv(env: Record<string, string>): IgniterAgentMCPStdioClientInterface<TName>;
+    /** Build and return the configuration object */
+    build(): IgniterAgentMCPStdioConfig<TName>;
+}
+/**
+ * Fluent builder interface for HTTP MCP configuration.
+ *
+ * @typeParam TName - The configuration name
+ * @internal
+ */
+interface IgniterAgentMCPHttpClientInterface<TName extends string> {
+    /** Set the configuration name */
+    withName<TNewName extends string>(name: TNewName): IgniterAgentMCPHttpClientInterface<TNewName>;
+    /** Set the transport type */
+    withType(type: IgniterAgentToolsetType): IgniterAgentMCPHttpClientInterface<TName>;
+    /** Set the server URL */
+    withURL(url: string): IgniterAgentMCPHttpClientInterface<TName>;
+    /** Set HTTP headers */
+    withHeaders(headers: Record<string, string>): IgniterAgentMCPHttpClientInterface<TName>;
+    /** Build and return the configuration object */
+    build(): IgniterAgentMCPHttpConfig<TName>;
+}
+/**
+ * Constructor parameters for creating a new Toolset instance.
+ *
+ * @typeParam TToolsetName - The toolset's unique name
+ * @typeParam TTools - The tools collection type
+ *
+ * @example
+ * ```typescript
+ * const params: IgniterAgentToolsetParams<'github', GithubTools> = {
+ *   name: 'github',
+ *   tools: githubTools
+ * };
+ * ```
+ *
+ * @public
+ */
+interface IgniterAgentToolsetParams<TToolsetName extends string = string, TTools extends ToolSet = ToolSet> {
+    /** Unique name identifier for the toolset */
+    name: TToolsetName;
+    /** Collection of tools in this toolset */
+    tools: TTools;
+}
+/**
+ * Represents a successful tool execution result.
+ *
+ * @typeParam TData - The type of data returned by the tool
+ *
+ * @example
+ * ```typescript
+ * const successResult: IgniterAgentToolSuccessResult<User> = {
+ *   success: true,
+ *   data: { id: '123', name: 'John' }
+ * };
+ * ```
+ *
+ * @public
+ */
+interface IgniterAgentToolSuccessResult<TData = unknown> {
+    /** Indicates the tool executed successfully */
+    readonly success: true;
+    /** The data returned by the tool */
+    readonly data: TData;
+}
+/**
+ * Represents a failed tool execution result.
+ *
+ * @example
+ * ```typescript
+ * const errorResult: IgniterAgentToolErrorResult = {
+ *   success: false,
+ *   error: 'Failed to connect to database'
+ * };
+ * ```
+ *
+ * @public
+ */
+interface IgniterAgentToolErrorResult {
+    /** Indicates the tool execution failed */
+    readonly success: false;
+    /** Error message describing what went wrong */
+    readonly error: string;
+}
+/**
+ * Union type for tool execution results.
+ *
+ * @description
+ * All tools wrapped by IgniterAgent return this type, providing a consistent
+ * error handling pattern across all tool invocations.
+ *
+ * @typeParam TData - The type of data returned on success
+ *
+ * @example
+ * ```typescript
+ * const handleResult = (result: IgniterAgentToolResult<User>) => {
+ *   if (result.success) {
+ *     console.log('User:', result.data);
+ *   } else {
+ *     console.error('Error:', result.error);
+ *   }
+ * };
+ * ```
+ *
+ * @public
+ */
+type IgniterAgentToolResult<TData = unknown> = IgniterAgentToolSuccessResult<TData> | IgniterAgentToolErrorResult;
+
+/**
+ * @fileoverview Type definitions for IgniterAgent Builder pattern classes.
+ * This module contains all interfaces for the fluent builder API.
+ *
+ * @module types/builder
+ * @packageDocumentation
+ */
+
+/**
+ * Interface for the built toolset result.
+ *
+ * @description
+ * Represents the final product of the Toolset builder, containing
+ * all configured tools and metadata.
+ *
+ * @typeParam TName - The toolset's unique name
+ * @typeParam TTools - The tools collection type
+ *
+ * @example
+ * ```typescript
+ * const toolset: IgniterAgentBuiltToolset<'github', GithubTools> = {
+ *   type: 'custom',
+ *   name: 'github',
+ *   toolset: tools,
+ *   status: 'connected',
+ *   tools: tools
+ * };
+ * ```
+ *
+ * @public
+ */
+interface IgniterAgentBuiltToolset<TName extends string = string, TTools extends Record<string, Tool> = Record<string, Tool>> extends IgniterAgentToolset$1<'custom', TName> {
+    /** The raw toolset object */
+    readonly toolset: TTools;
+    /** Typed tools collection */
+    readonly tools: TTools;
+    readonly $Infer: {
+        Name: TName;
+        Tools: TTools;
+    };
+}
+/**
+ * Interface for the built tool result.
+ *
+ * @description
+ * Represents a finalized tool definition with its assigned name.
+ *
+ * @typeParam TName - The tool's unique name
+ * @typeParam TInputSchema - The tool parameters type
+ * @typeParam TOutputSchema - The tool result type
+ * @typeParam TExecute - The tool execute function type
+ *
+ * @public
+ */
+interface IgniterAgentBuiltTool<TName extends string = string, TInputSchema = unknown, TOutputSchema = undefined, TExecute = (params: TInputSchema, options: IgniterAgentToolExecuteOptions) => TOutputSchema extends undefined ? Promise<unknown> : Promise<TOutputSchema>> {
+    /** The tool's unique name */
+    readonly name: TName;
+    /**
+     * Human-readable description of what the tool does.
+     *
+     * @description
+     * This is shown to the AI model to help it decide when to use the tool.
+     * Should be clear, concise, and explain the tool's purpose and capabilities.
+     */
+    description: string;
+    /**
+     * Zod schema defining the tool's input parameters.
+     *
+     * @description
+     * The schema is used for validation and also informs the AI model
+     * about what parameters are available and their types.
+     */
+    inputSchema: z.ZodSchema<TInputSchema>;
+    /**
+     * (Optional) Zod schema defining the tool's output/result.
+     *
+     * @description
+     * If provided, the tool's output will be validated against this schema.
+     * Helps ensure consistent and expected results from tool execution.
+     */
+    outputSchema?: z.ZodSchema<TOutputSchema>;
+    /**
+     * The function that executes the tool's logic.
+     *
+     * @description
+     * Receives the validated parameters and optional execution options.
+     * Can be async for operations that require waiting.
+     *
+     * @param params - The validated input parameters
+     * @param options - Execution options including abort signal
+     * @returns The tool's result
+     */
+    execute: TExecute;
+    $Infer: {
+        Name: TName;
+        Description: string;
+        Input: TInputSchema;
+        Output: TOutputSchema;
+    };
+}
+/**
+ * Partial configuration for MCP client during construction.
+ *
+ * @description
+ * Used internally by the MCP builder to track partial configuration
+ * before all required fields are set.
+ *
+ * @typeParam TType - The transport type
+ * @typeParam TName - The configuration name
+ *
+ * @internal
+ */
+type IgniterAgentMCPPartialConfig<TType extends IgniterAgentToolsetType = IgniterAgentToolsetType, TName extends string = string> = Partial<IgniterAgentMCPConfigUnion<TName>> & {
+    type?: TType;
+};
+/**
+ * Result object returned by the Agent builder's build() method.
+ *
+ * @description
+ * Provides the runtime interface for interacting with a built agent.
+ * Includes methods for starting the agent, generating responses,
+ * and accessing configuration.
+ *
+ * @typeParam TContextSchema - The context schema type
+ * @typeParam TToolsets - The toolsets record type
+ * @typeParam TModel - The language model type
+ * @typeParam TInstructions - The prompt template type
+ *
+ * @example
+ * ```typescript
+ * const agent = IgniterAgent.create('assistant')
+ *   .withModel(openai('gpt-4'))
+ *   .build();
+ *
+ * // Start the agent (initializes MCP connections)
+ * await agent.start();
+ *
+ * // Generate a response
+ * const result = await agent.generate({
+ *   messages: [{ role: 'user', content: 'Hello!' }]
+ * });
+ *
+ * // Stream a response
+ * const stream = await agent.stream({
+ *   messages: [{ role: 'user', content: 'Tell me a story' }]
+ * });
+ * ```
+ *
+ * @public
+ */
+interface IgniterAgentBuiltAgent<TContextSchema extends z.ZodSchema = z.ZodSchema, TToolsets extends Record<string, IgniterAgentToolset$1> = Record<string, IgniterAgentToolset$1>, TModel extends LanguageModel = LanguageModel, TInstructions extends IgniterAgentPromptTemplate = IgniterAgentPromptTemplate> {
+    /**
+     * Attaches a logger instance to the agent.
+     */
+    attachLogger(logger?: IgniterLogger): void;
+    /**
+     * Attaches a telemetry manager to the agent.
+     */
+    attachTelemetry(telemetry?: IgniterTelemetryManager): void;
+    /**
+     * Attaches hook callbacks to the agent.
+     */
+    attachHooks(hooks?: IgniterAgentHooks): void;
+    /**
+     * Returns the agent name.
+     */
+    getName(): string;
+    /**
+     * Starts the agent and initializes all MCP connections.
+     *
+     * @description
+     * Must be called before using the agent if MCP toolsets are configured.
+     * Establishes connections to all configured MCP servers and populates
+     * the toolsets with available tools.
+     *
+     * @returns The initialized toolsets record
+     *
+     * @example
+     * ```typescript
+     * const toolsets = await agent.start();
+     * console.log('Connected toolsets:', Object.keys(toolsets));
+     * ```
+     */
+    start(): Promise<void>;
+    /**
+     * Stops the agent and disconnects MCP toolsets.
+     */
+    stop(): Promise<void>;
+    /**
+     * Generates a single response from the agent.
+     *
+     * @description
+     * Sends messages to the agent and waits for a complete response.
+     * Supports context options for dynamic prompt generation.
+     *
+     * @param input - The call parameters including messages and options
+     * @returns The generation result with response and tool calls
+     *
+     * @example
+     * ```typescript
+     * const result = await agent.generate({
+     *   messages: [
+     *     { role: 'user', content: 'What is TypeScript?' }
+     *   ],
+     *   options: { userId: 'user_123' }
+     * });
+     *
+     * console.log('Response:', result.text);
+     * ```
+     */
+    generate(input: AgentCallParameters<z.infer<TContextSchema>>): Promise<unknown>;
+    /**
+     * Streams a response from the agent.
+     *
+     * @description
+     * Sends messages to the agent and returns a stream of response chunks.
+     * Ideal for real-time UI updates and long responses.
+     *
+     * @param input - The stream parameters including messages and options
+     * @returns A stream of response chunks
+     *
+     * @example
+     * ```typescript
+     * const stream = await agent.stream({
+     *   messages: [
+     *     { role: 'user', content: 'Write a poem about coding' }
+     *   ]
+     * });
+     *
+     * for await (const chunk of stream) {
+     *   process.stdout.write(chunk);
+     * }
+     * ```
+     */
+    stream(input: AgentStreamParameters<z.infer<TContextSchema>, ToolSet>): Promise<unknown>;
+    /**
+     * Gets all registered toolsets.
+     *
+     * @returns The toolsets record
+     */
+    getToolsets(): TToolsets;
+    /**
+     * Gets the configured language model.
+     *
+     * @returns The language model instance
+     */
+    getModel(): TModel;
+    /**
+     * Gets the configured instructions.
+     *
+     * @returns The prompt template instance
+     */
+    getInstructions(): TInstructions;
+    /**
+     * Gets the context schema.
+     *
+     * @returns The Zod schema for context validation
+     */
+    getContextSchema(): TContextSchema;
+    /**
+     * Optional memory runtime for persistence operations.
+     */
+    memory?: IgniterAgentMemoryRuntime;
+}
+/**
+ * Options passed to tool execution handlers.
+ *
+ * @description
+ * Contains metadata and utilities available during tool execution.
+ *
+ * @public
+ */
+interface IgniterAgentToolExecuteOptions {
+    /**
+     * Abort signal for cancellation support.
+     *
+     * @description
+     * Can be used to abort long-running operations when the
+     * agent request is cancelled.
+     */
+    abortSignal?: AbortSignal;
+    /**
+     * Additional context from the agent runtime.
+     */
+    [key: string]: unknown;
+}
+/**
+ * Tool definition for adding to a Toolset.
+ *
+ * @description
+ * Defines the structure of a tool that can be built with
+ * {@link IgniterAgentToolBuilder} and added to a toolset.
+ *
+ * @typeParam TInputSchema - The parameters schema type
+ * @typeParam TOutputSchema - The return type of the tool
+ *
+ * @example
+ * ```typescript
+ * const weatherTool: IgniterAgentToolDefinition = {
+ *   description: 'Gets current weather for a city',
+ *   inputSchema: z.object({
+ *     city: z.string().describe('City name'),
+ *     units: z.enum(['celsius', 'fahrenheit']).optional()
+ *   }),
+ *   execute: async ({ city, units }) => {
+ *     const weather = await fetchWeather(city, units);
+ *     return { temperature: weather.temp, conditions: weather.desc };
+ *   }
+ * };
+ * ```
+ *
+ * @public
+ */
+interface IgniterAgentToolDefinition<TInputSchema = unknown, TOutputSchema = unknown> {
+    /**
+     * Human-readable description of what the tool does.
+     *
+     * @description
+     * This is shown to the AI model to help it decide when to use the tool.
+     * Should be clear, concise, and explain the tool's purpose and capabilities.
+     */
+    description: string;
+    /**
+     * Zod schema defining the tool's input parameters.
+     *
+     * @description
+     * The schema is used for validation and also informs the AI model
+     * about what parameters are available and their types.
+     */
+    inputSchema: z.ZodSchema<TInputSchema>;
+    /**
+     * (Optional) Zod schema defining the tool's output/result.
+     *
+     * @description
+     * If provided, the tool's output will be validated against this schema.
+     * Helps ensure consistent and expected results from tool execution.
+     */
+    outputSchema?: z.ZodSchema<TOutputSchema>;
+    /**
+     * The function that executes the tool's logic.
+     *
+     * @description
+     * Receives the validated parameters and optional execution options.
+     * Can be async for operations that require waiting.
+     *
+     * @param params - The validated input parameters
+     * @param options - Execution options including abort signal
+     * @returns The tool's result
+     */
+    execute: (params: TInputSchema, options?: IgniterAgentToolExecuteOptions) => TOutputSchema | Promise<TOutputSchema>;
+}
+
+/**
+ * Status of an agent in the manager.
+ *
+ * @public
+ */
+type IgniterAgentStatus = "idle" | "starting" | "running" | "stopped" | "error";
+/**
+ * Information about a registered agent.
+ *
+ * @public
+ */
+interface IgniterAgentInfo {
+    /** The agent's unique name */
+    name: string;
+    /** Current status */
+    status: IgniterAgentStatus;
+    /** When the agent was registered */
+    registeredAt: Date;
+    /** When the agent was last started */
+    startedAt?: Date;
+    /** Error if agent failed */
+    error?: Error;
+    /** Number of registered toolsets */
+    toolsetCount: number;
+}
+/**
+ * Options for the agent manager.
+ *
+ * @public
+ */
+interface IgniterAgentManagerOptions<TAgentRegistry extends Record<string, IgniterAgentBuiltAgent> = Record<string, IgniterAgentBuiltAgent>> extends IgniterAgentHooks {
+    /**
+     * Pre-registered agents.
+     * @defaultValue {}
+     */
+    agents: TAgentRegistry;
+    /**
+     * Whether to auto-start agents when registered.
+     * @defaultValue false
+     */
+    autoStart?: boolean;
+    /**
+     * Whether to continue starting other agents if one fails.
+     * @defaultValue true
+     */
+    continueOnError?: boolean;
+    /**
+     * Logger instance for logging.
+     * @defaultValue undefined
+     */
+    logger?: IgniterLogger;
+    /**
+     * Optional telemetry manager for observability.
+     */
+    telemetry?: IgniterTelemetryManager;
+}
+
+/**
+ * Shared type utilities for `@igniter-js/agents`.
+ */
+
+/**
+ * Extracts the inferred type from a Zod schema.
+ *
+ * @public
+ */
+type InferZodSchema<T extends z.ZodSchema> = z.infer<T>;
+/**
+ * Makes all properties in T optional recursively.
+ *
+ * @public
+ */
+type DeepPartial<T> = {
+    [P in keyof T]?: T[P] extends object ? DeepPartial<T[P]> : T[P];
+};
+/**
+ * Makes all properties in T required recursively.
+ *
+ * @public
+ */
+type DeepRequired<T> = {
+    [P in keyof T]-?: T[P] extends object ? DeepRequired<T[P]> : T[P];
+};
+/**
+ * Extracts keys from T that have values of type V.
+ *
+ * @public
+ */
+type KeysOfType<T, V> = {
+    [K in keyof T]: T[K] extends V ? K : never;
+}[keyof T];
+
+/**
+ * @fileoverview Core agent manager for lifecycle and orchestration.
+ * This module provides centralized management for IgniterAgent instances.
+ *
+ * @description
+ * The IgniterAgentManager provides utilities for:
+ * - Managing multiple agent instances
+ * - Coordinating agent lifecycle (start, stop)
+ * - Monitoring agent health and status
+ * - Routing requests to appropriate agents
+ *
+ * @example
+ * ```typescript
+ * import { IgniterAgentManager } from '@igniter-js/agents';
+ *
+ * // Create a manager
+ * const manager = new IgniterAgentManager();
+ *
+ * // Register agents
+ * manager.register('support', supportAgent);
+ * manager.register('sales', salesAgent);
+ *
+ * // Start all agents
+ * await manager.startAll();
+ *
+ * // Route to specific agent
+ * const agent = manager.get('support');
+ * const response = await agent.generate({ messages: [...] });
+ * ```
+ *
+ * @module core/manager
+ * @packageDocumentation
+ */
+
+/**
+ * Manager for coordinating multiple IgniterAgent instances.
+ *
+ * @description
+ * The IgniterAgentManager provides a centralized way to manage multiple
+ * agent instances, handling their lifecycle and providing routing capabilities.
+ *
+ * **Key Features:**
+ * - Register and manage multiple agents
+ * - Batch start/stop operations
+ * - Health monitoring
+ * - Request routing
+ *
+ * @example
+ * ```typescript
+ * import { IgniterAgentManager, IgniterAgent } from '@igniter-js/agents';
+ *
+ * // Create agents
+ * const supportAgent = IgniterAgent.create('support')
+ *   .withModel(openai('gpt-4'))
+ *   .build();
+ *
+ * const codeAgent = IgniterAgent.create('code')
+ *   .withModel(openai('gpt-4-turbo'))
+ *   .addToolset(codeToolset)
+ *   .build();
+ *
+ * // Create manager and register agents
+ * const manager = new IgniterAgentManager({
+ *   continueOnError: true,
+ *   onAgentStart: (name) => console.log(`Agent ${name} started`),
+ *   onAgentError: (name, err) => console.error(`Agent ${name} failed:`, err)
+ * });
+ *
+ * manager.register('support', supportAgent);
+ * manager.register('code', codeAgent);
+ *
+ * // Start all agents
+ * await manager.startAll();
+ *
+ * // Use specific agent
+ * const agent = manager.get('code');
+ * const result = await agent.generate({
+ *   messages: [{ role: 'user', content: 'Write a test' }]
+ * });
+ *
+ * // Get status
+ * console.log(manager.getStatus());
+ * ```
+ *
+ * @public
+ */
+declare class IgniterAgentManagerCore<TAgentRegistry extends Record<string, IgniterAgentBuiltAgent> = Record<string, IgniterAgentBuiltAgent>> {
+    /**
+     * Agent statuses.
+     * @internal
+     */
+    private readonly _statuses;
+    /**
+     * Manager options.
+     * @internal
+     */
+    private readonly _options;
+    /**
+     * Creates a new IgniterAgentManager.
+     *
+     * @param options - Manager configuration options
+     *
+     * @example
+     * ```typescript
+     * const manager = new IgniterAgentManager({
+     *   autoStart: false,
+     *   continueOnError: true
+     * });
+     * ```
+     */
+    constructor(options: IgniterAgentManagerOptions<TAgentRegistry>);
+    private applyManagerContext;
+    /**
+     * Creates a new IgniterAgentManager with default options.
+     * @param options - Manager configuration options
+     * @returns A new IgniterAgentManager instance
+     * @example
+     * ```typescript
+     * const manager = IgniterAgentManager.create({
+     *   autoStart: true
+     * });
+     * ```
+     */
+    static create(): IgniterAgentManagerCore;
+    /**
+     * Registers an agent with the manager.
+     *
+     * @description
+     * Adds an agent to the manager's registry. If `autoStart` is enabled,
+     * the agent will be started immediately after registration.
+     *
+     * @param name - Unique name for the agent
+     * @param agent - The built agent instance
+     * @returns This manager for chaining
+     * @throws {IgniterAgentError} If an agent with the name already exists
+     *
+     * @example
+     * ```typescript
+     * manager
+     *   .register('support', supportAgent)
+     *   .register('sales', salesAgent);
+     * ```
+     */
+    register(name: string, agent: IgniterAgentBuiltAgent): this;
+    /**
+     * Unregisters an agent from the manager.
+     *
+     * @param name - The agent name to unregister
+     * @returns True if the agent was unregistered
+     *
+     * @example
+     * ```typescript
+     * manager.unregister('old-agent');
+     * ```
+     */
+    unregister(name: string): boolean;
+    /**
+     * Checks if an agent is registered.
+     *
+     * @param name - The agent name to check
+     * @returns True if the agent is registered
+     */
+    has(name: string): boolean;
+    /**
+     * Starts a specific agent.
+     *
+     * @description
+     * Initializes the agent's MCP connections and prepares it for use.
+     *
+     * @param name - The agent name to start
+     * @returns The agent's toolsets after initialization
+     * @throws {IgniterAgentError} If the agent is not found
+     *
+     * @example
+     * ```typescript
+     * const toolsets = await manager.start('support');
+     * console.log('Connected toolsets:', Object.keys(toolsets));
+     * ```
+     */
+    start(name: string): Promise<IgniterAgentBuiltAgent>;
+    /**
+     * Starts all registered agents.
+     *
+     * @description
+     * Initializes all agents in parallel. If `continueOnError` is true,
+     * failed agents won't prevent others from starting.
+     *
+     * @returns Map of agent names to their results (toolsets or errors)
+     *
+     * @example
+     * ```typescript
+     * const results = await manager.startAll();
+     *
+     * for (const [name, result] of results) {
+     *   if (result instanceof Error) {
+     *     console.error(`${name} failed:`, result.message);
+     *   } else {
+     *     console.log(`${name} started with ${Object.keys(result).length} toolsets`);
+     *   }
+     * }
+     * ```
+     */
+    startAll(): Promise<Map<string, Record<string, IgniterAgentToolset$1> | Error>>;
+    /**
+     * Gets a registered agent by name.
+     *
+     * @param name - The agent name
+     * @returns The agent instance
+     * @throws {IgniterAgentError} If the agent is not found
+     *
+     * @example
+     * ```typescript
+     * const agent = manager.get('support');
+     * const response = await agent.generate({ messages: [...] });
+     * ```
+     */
+    get<TName extends string>(name: TName): TAgentRegistry[TName];
+    /**
+     * Gets an agent if it exists, undefined otherwise.
+     *
+     * @param name - The agent name
+     * @returns The agent instance or undefined
+     */
+    tryGet<TName extends string>(name: TName): TAgentRegistry[TName] | undefined;
+    /**
+     * Gets all registered agent names.
+     *
+     * @returns Array of agent names
+     */
+    getNames(): string[];
+    /**
+     * Gets the number of registered agents.
+     *
+     * @returns Agent count
+     */
+    get size(): number;
+    /**
+     * Gets information about a specific agent.
+     *
+     * @param name - The agent name
+     * @returns Agent information or undefined
+     */
+    getInfo(name: string): IgniterAgentInfo | undefined;
+    /**
+     * Gets status information for all agents.
+     *
+     * @returns Array of agent information objects
+     *
+     * @example
+     * ```typescript
+     * const status = manager.getStatus();
+     *
+     * for (const info of status) {
+     *   console.log(`${info.name}: ${info.status}`);
+     * }
+     * ```
+     */
+    getStatus(): IgniterAgentInfo[];
+    /**
+     * Checks if all agents are running.
+     *
+     * @returns True if all agents are in 'running' status
+     */
+    isAllRunning(): boolean;
+    /**
+     * Gets agents that are in error state.
+     *
+     * @returns Array of agent info for failed agents
+     */
+    getFailedAgents(): IgniterAgentInfo[];
+}
+
+/**
+ * @fileoverview Memory runtime for IgniterAgent.
+ * @module core/memory
+ */
+
+/**
+ * Memory runtime wrapper that adds logging and telemetry to provider operations.
+ *
+ * @public
+ */
+declare class IgniterAgentMemoryCore implements IgniterAgentMemoryRuntime {
+    private readonly provider;
+    private readonly agentName;
+    private readonly logger?;
+    private readonly telemetry?;
+    constructor(config: IgniterAgentMemoryConfig, agentName: string, logger?: IgniterLogger, telemetry?: IgniterTelemetryManager);
+    private getBaseAttributes;
+    private emitStart;
+    private emitSuccess;
+    private emitError;
+    private runOperation;
+    getWorkingMemory(params: IgniterAgentWorkingMemoryParams): Promise<IgniterAgentWorkingMemory | null>;
+    updateWorkingMemory(params: IgniterAgentUpdateWorkingMemoryParams): Promise<void>;
+    saveMessage(message: IgniterAgentConversationMessage): Promise<void>;
+    getMessages<T = IgniterAgentUIMessage>(params: IgniterAgentGetMessagesParams): Promise<T[]>;
+    saveChat(chat: IgniterAgentChatSession): Promise<void>;
+    getChats(params: IgniterAgentGetChatsParams): Promise<IgniterAgentChatSession[]>;
+    getChat(chatId: string): Promise<IgniterAgentChatSession | null>;
+    updateChatTitle(chatId: string, title: string): Promise<void>;
+    deleteChat(chatId: string): Promise<void>;
+}
+
+declare class IgniterAgentCore<TAgentName extends string = string, TAgentModel extends LanguageModel = LanguageModel, TAgentInstructions extends IgniterAgentPromptTemplate = IgniterAgentPromptTemplate, TAgentToolsets extends Record<string, IgniterAgentToolset$1> = Record<string, IgniterAgentToolset$1>, TAgentMCPConfigs extends Record<string, IgniterAgentMCPConfigUnion> = Record<string, IgniterAgentMCPConfigUnion>, TAgentContextSchema extends z.ZodSchema = z.ZodSchema> {
+    private _agent;
+    private logger?;
+    private telemetry?;
+    private hooks;
+    memory?: IgniterAgentMemoryCore;
+    constructor(agent: IgniterAgentConfig<TAgentName, TAgentModel, TAgentInstructions, TAgentToolsets, TAgentMCPConfigs, TAgentContextSchema>);
+    /**
+     * Attaches a logger instance to the agent.
+     */
+    attachLogger(logger?: IgniterLogger): void;
+    /**
+     * Attaches a telemetry manager to the agent.
+     */
+    attachTelemetry(telemetry?: IgniterTelemetryManager): void;
+    /**
+     * Attaches hook callbacks to the agent.
+     */
+    attachHooks(hooks?: IgniterAgentHooks): void;
+    /**
+     * Returns the agent name.
+     */
+    getName(): string;
+    /**
+     * Starts the agent by initializing all MCP connections.
+     */
+    start(): Promise<void>;
+    /**
+     * Stops the agent by disconnecting MCP toolsets.
+     */
+    stop(): Promise<void>;
+    /**
+     * Generates a response from the agent.
+     */
+    generate(input: AgentCallParameters<z.infer<TAgentContextSchema>>): Promise<any>;
+    /**
+     * Streams a response from the agent.
+     */
+    stream(input: AgentStreamParameters<z.infer<TAgentContextSchema>, ToolSet>): Promise<any>;
+    /**
+     * Gets all registered toolsets.
+     */
+    getToolsets(): TAgentToolsets;
+    /**
+     * Gets the configured model.
+     */
+    getModel(): TAgentModel;
+    /**
+     * Gets the configured instructions.
+     */
+    getInstructions(): TAgentInstructions;
+    /**
+     * Gets the context schema.
+     */
+    getContextSchema(): TAgentContextSchema;
+    /**
+     * Gets all registered tools from all toolsets.
+     */
+    getTools(): ToolSet;
+    private wrapToolExecution;
+    private wrapStreamResult;
+    private getErrorAttributes;
+    private getAgentInstanceWithContext;
+    private initializeMCPClient;
+}
+
+declare class IgniterAgentManagerBuilder<TAgentRegistry extends Record<string, IgniterAgentBuiltAgent> = Record<string, IgniterAgentBuiltAgent>> {
+    private readonly _manager;
+    private constructor();
+    addAgent<TName extends string, TAgent extends IgniterAgentBuiltAgent>(name: TName, agent: TAgent): IgniterAgentManagerBuilder<TAgentRegistry & {
+        [K in TName]: TAgent;
+    }>;
+    withLogger(logger: IgniterLogger): IgniterAgentManagerBuilder<TAgentRegistry>;
+    withTelemetry(telemetry: IgniterTelemetryManager): IgniterAgentManagerBuilder<TAgentRegistry>;
+    withAutoStart(autoStart: boolean): IgniterAgentManagerBuilder<TAgentRegistry>;
+    withContinueOnError(continueOnError: boolean): IgniterAgentManagerBuilder<TAgentRegistry>;
+    onAgentStart(callback: IgniterAgentHooks["onAgentStart"]): IgniterAgentManagerBuilder<TAgentRegistry>;
+    onAgentError(callback: IgniterAgentHooks["onAgentError"]): IgniterAgentManagerBuilder<TAgentRegistry>;
+    onToolCallStart(callback: (agentName: keyof TAgentRegistry, toolName: string, input: unknown) => void): IgniterAgentManagerBuilder<TAgentRegistry>;
+    onToolCallEnd(callback: (agentName: keyof TAgentRegistry, toolName: string, output: unknown) => void): IgniterAgentManagerBuilder<TAgentRegistry>;
+    onToolCallError(callback: (agentName: keyof TAgentRegistry, toolName: string, error: Error) => void): IgniterAgentManagerBuilder<TAgentRegistry>;
+    onMCPStart(callback: (agentName: keyof TAgentRegistry, mcpName: string) => void): IgniterAgentManagerBuilder<TAgentRegistry>;
+    onMCPError(callback: (agentName: string, mcpName: string, error: Error) => void): IgniterAgentManagerBuilder<TAgentRegistry>;
+    static create(): IgniterAgentManagerBuilder<{}>;
+    build(): IgniterAgentManagerCore<TAgentRegistry>;
+}
+/**
+ * Alias for IgniterAgentManager for cleaner API.
+ *
+ * @description
+ * Use `IgniterAgentManager.create()` as the primary entry point for managing agents.
+ *
+ * @example
+ * ```typescript
+ * import { IgniterAgentManager } from '@igniter-js/agents';
+ *
+ * const manager = IgniterAgentManager
+ *   .create()
+ *   .addAgent('assistant', assistantAgent)
+ *   .addAgent('code-helper', codeHelperAgent)
+ *   .withLogger(customLogger)
+ *   .onToolCallStart((agentName, toolName, input) => {
+ *     console.log(`[${agentName}] Tool ${toolName} called with input:`, input);
+ *   })
+ *   .build();
+ * ```
+ *
+ * @public
+ */
+declare const IgniterAgentManager: {
+    create: typeof IgniterAgentManagerBuilder.create;
+};
+/**
+ * Type alias for the IgniterAgent class.
+ * @public
+ */
+type IgniterAgentManager = typeof IgniterAgentManagerBuilder;
+
+/**
+ * @fileoverview Main Agent Builder for creating AI agents with tools and MCP support.
+ * This module provides the primary fluent API for building IgniterAgent instances.
+ *
+ * @description
+ * The IgniterAgentBuilder is the central class for creating AI agents. It provides
+ * a type-safe fluent API for configuring all aspects of an agent including:
+ * - Language model selection
+ * - Custom toolsets
+ * - MCP server connections
+ * - Context schema validation
+ * - Prompt instructions
+ *
+ * @example
+ * ```typescript
+ * import { IgniterAgent } from '@igniter-js/agents';
+ * import { openai } from '@ai-sdk/openai';
+ * import { z } from 'zod';
+ *
+ * const agent = IgniterAgent
+ *   .create('assistant')
+ *   .withModel(openai('gpt-4'))
+ *   .withContextSchema(z.object({
+ *     userId: z.string(),
+ *     chatId: z.string()
+ *   }))
+ *   .addToolset(myCustomToolset)
+ *   .addMCP(filesystemMCP)
+ *   .build();
+ *
+ * // Start the agent (initializes MCP connections)
+ * await agent.start();
+ *
+ * // Generate a response
+ * const result = await agent.generate({
+ *   messages: [{ role: 'user', content: 'Hello!' }],
+ *   options: { userId: 'user_123', chatId: 'chat_456' }
+ * });
+ * ```
+ *
+ * @module builders/agent
+ * @packageDocumentation
+ */
+
+/**
+ * Fluent builder for creating AI agents.
+ *
+ * @description
+ * The IgniterAgentBuilder provides a comprehensive fluent API for creating
+ * AI agents with full TypeScript type inference. It supports:
+ *
+ * - **Multiple Language Models**: Works with any Vercel AI SDK compatible model
+ * - **Custom Toolsets**: Register your own tools with automatic error handling
+ * - **MCP Integration**: Connect to MCP servers for external tool providers
+ * - **Context Schema**: Type-safe context validation with Zod
+ * - **Dynamic Prompts**: Template-based prompt generation
+ *
+ * **Lifecycle:**
+ * 1. Create the builder with `IgniterAgent.create()`
+ * 2. Configure using fluent methods (`withModel`, etc.)
+ * 3. Build with `.build()` to get the runtime agent
+ * 4. Call `.start()` to initialize MCP connections
+ * 5. Use `.generate()` or `.stream()` to interact with the agent
+ *
+ * @typeParam TAgentName - The agent's unique name type
+ * @typeParam TAgentModel - The language model type
+ * @typeParam TAgentInstructions - The prompt template type
+ * @typeParam TAgentToolsets - Record of registered toolsets
+ * @typeParam TAgentMCPConfigs - Record of MCP configurations
+ * @typeParam TAgentContextSchema - The context schema type
+ *
+ * @example
+ * ```typescript
+ * import {
+ *   IgniterAgent,
+ *   IgniterAgentPrompt,
+ *   IgniterAgentToolset,
+ *   IgniterAgentTool,
+ *   IgniterAgentMCPClient,
+ * } from '@igniter-js/agents';
+ * import { openai } from '@ai-sdk/openai';
+ * import { z } from 'zod';
+ *
+ * const runCodeTool = IgniterAgentTool
+ *   .create('runCode')
+ *   .withDescription('Runs code')
+ *   .withInput(z.object({ code: z.string() }))
+ *   .withExecute(async ({ code }) => codeRunner(code))
+ *   .build();
+ *
+ * const searchDocsTool = IgniterAgentTool
+ *   .create('searchDocs')
+ *   .withDescription('Searches docs')
+ *   .withInput(z.object({ query: z.string() }))
+ *   .withExecute(async ({ query }) => docSearcher(query))
+ *   .build();
+ *
+ * // Create a fully-configured agent
+ * const agent = IgniterAgent
+ *   .create('code-assistant')
+ *   .withModel(openai('gpt-4-turbo'))
+ *   .withContextSchema(z.object({
+ *     userId: z.string(),
+ *     projectId: z.string()
+ *   }))
+ *   .withPrompt(
+ *     IgniterAgentPrompt.create('You are a helpful coding assistant...')
+ *   )
+ *   .addToolset(
+ *     IgniterAgentToolset.create('code')
+ *       .addTool(runCodeTool)
+ *       .addTool(searchDocsTool)
+ *       .build()
+ *   )
+ *   .addMCP(
+ *     IgniterAgentMCPClient.create('filesystem')
+ *       .withType('stdio')
+ *       .withCommand('npx')
+ *       .withArgs(['-y', '@mcp/server-filesystem'])
+ *       .build()
+ *   )
+ *   .build();
+ *
+ * // Initialize and use
+ * await agent.start();
+ *
+ * const response = await agent.generate({
+ *   messages: [{ role: 'user', content: 'Help me write a test' }],
+ *   options: { userId: 'user_123', projectId: 'proj_456' }
+ * });
+ * ```
+ *
+ * @public
+ */
+declare class IgniterAgentBuilder<TAgentName extends string = string, TAgentModel extends LanguageModel = LanguageModel, TAgentInstructions extends IgniterAgentPromptTemplate = IgniterAgentPromptTemplate, TAgentToolsets extends Record<string, IgniterAgentToolset$1> = Record<string, IgniterAgentToolset$1>, TAgentMCPConfigs extends Record<string, IgniterAgentMCPConfigUnion> = Record<string, IgniterAgentMCPConfigUnion>, TAgentContextSchema extends z.ZodSchema = z.ZodSchema> {
+    /**
+     * The agent configuration being built.
+     * @internal
+     */
+    private readonly _config;
+    /**
+     * Creates a new IgniterAgentBuilder instance.
+     *
+     * @param config - Initial configuration
+     * @internal
+     */
+    private constructor();
+    /**
+     * Creates a new agent builder.
+     *
+     * @description
+     * Primary entry point for creating an agent. Returns a new builder
+     * instance that can be configured using fluent methods.
+     *
+     * @returns A new IgniterAgentBuilder instance
+     *
+     * @example
+     * ```typescript
+     * const agent = IgniterAgent.create('my-agent')
+     *   .withModel(openai('gpt-4'))
+     *   .build();
+     * ```
+     *
+     * @public
+     */
+    static create<TNewName extends string = string>(name?: TNewName): IgniterAgentBuilder<TNewName, LanguageModel, IgniterAgentPromptTemplate, {}, {}, z.ZodSchema>;
+    /**
+     * Sets the language model.
+     *
+     * @description
+     * Configures the AI model that powers the agent. Supports any model
+     * provider compatible with the Vercel AI SDK.
+     *
+     * @typeParam TNewModel - The new model type
+     * @param model - The language model instance
+     * @returns A new builder with the model set
+     *
+     * @example
+     * ```typescript
+     * import { openai } from '@ai-sdk/openai';
+     * import { anthropic } from '@ai-sdk/anthropic';
+     * import { google } from '@ai-sdk/google';
+     *
+     * // Using OpenAI
+     * const agent1 = IgniterAgent.create()
+     *   .withModel(openai('gpt-4-turbo'))
+     *   .build();
+     *
+     * // Using Anthropic
+     * const agent2 = IgniterAgent.create()
+     *   .withModel(anthropic('claude-3-opus'))
+     *   .build();
+     *
+     * // Using Google
+     * const agent3 = IgniterAgent.create()
+     *   .withModel(google('gemini-pro'))
+     *   .build();
+     * ```
+     *
+     * @public
+     */
+    withModel<TNewModel extends LanguageModel>(model: TNewModel): IgniterAgentBuilder<TAgentName, TNewModel, TAgentInstructions, TAgentToolsets, TAgentMCPConfigs, TAgentContextSchema>;
+    /**
+     * Sets the prompt instructions.
+     *
+     * @description
+     * Configures the agent's system prompt using an IgniterAgentPrompt template.
+     * The prompt defines the agent's behavior, personality, and capabilities.
+     *
+     * @typeParam TNewInstructions - The new instructions type
+     * @param instructions - The prompt template instance
+     * @returns A new builder with the instructions set
+     *
+     * @example
+     * ```typescript
+     * const agent = IgniterAgent.create()
+     *   .withPrompt(
+     *     IgniterAgentPrompt.create(`
+     *       You are a helpful coding assistant specialized in TypeScript.
+     *
+     *       Guidelines:
+     *       - Always provide type-safe code
+     *       - Include JSDoc comments
+     *       - Follow best practices
+     *     `)
+     *   )
+     *   .build();
+     * ```
+     *
+     * @public
+     */
+    withPrompt<TNewInstructions extends IgniterAgentPromptTemplate>(instructions: TNewInstructions): IgniterAgentBuilder<TAgentName, TAgentModel, TNewInstructions, TAgentToolsets, TAgentMCPConfigs, TAgentContextSchema>;
+    /**
+     * Attaches a logger instance for operational logs.
+     */
+    withLogger(logger: IgniterLogger): IgniterAgentBuilder<TAgentName, TAgentModel, TAgentInstructions, TAgentToolsets, TAgentMCPConfigs, TAgentContextSchema>;
+    /**
+     * Attaches a telemetry manager for observability.
+     */
+    withTelemetry(telemetry: IgniterTelemetryManager): IgniterAgentBuilder<TAgentName, TAgentModel, TAgentInstructions, TAgentToolsets, TAgentMCPConfigs, TAgentContextSchema>;
+    /**
+     * Configures persistent memory for the agent.
+     */
+    withMemory(memory: IgniterAgentMemoryConfig): IgniterAgentBuilder<TAgentName, TAgentModel, TAgentInstructions, TAgentToolsets, TAgentMCPConfigs, TAgentContextSchema>;
+    /**
+     * Callback when the agent starts.
+     */
+    onAgentStart(callback: IgniterAgentHooks["onAgentStart"]): IgniterAgentBuilder<TAgentName, TAgentModel, TAgentInstructions, TAgentToolsets, TAgentMCPConfigs, TAgentContextSchema>;
+    /**
+     * Callback when the agent errors.
+     */
+    onAgentError(callback: IgniterAgentHooks["onAgentError"]): IgniterAgentBuilder<TAgentName, TAgentModel, TAgentInstructions, TAgentToolsets, TAgentMCPConfigs, TAgentContextSchema>;
+    /**
+     * Callback when a tool call starts.
+     */
+    onToolCallStart(callback: IgniterAgentHooks["onToolCallStart"]): IgniterAgentBuilder<TAgentName, TAgentModel, TAgentInstructions, TAgentToolsets, TAgentMCPConfigs, TAgentContextSchema>;
+    /**
+     * Callback when a tool call completes.
+     */
+    onToolCallEnd(callback: IgniterAgentHooks["onToolCallEnd"]): IgniterAgentBuilder<TAgentName, TAgentModel, TAgentInstructions, TAgentToolsets, TAgentMCPConfigs, TAgentContextSchema>;
+    /**
+     * Callback when a tool call fails.
+     */
+    onToolCallError(callback: IgniterAgentHooks["onToolCallError"]): IgniterAgentBuilder<TAgentName, TAgentModel, TAgentInstructions, TAgentToolsets, TAgentMCPConfigs, TAgentContextSchema>;
+    /**
+     * Callback when an MCP connection starts.
+     */
+    onMCPStart(callback: IgniterAgentHooks["onMCPStart"]): IgniterAgentBuilder<TAgentName, TAgentModel, TAgentInstructions, TAgentToolsets, TAgentMCPConfigs, TAgentContextSchema>;
+    /**
+     * Callback when an MCP connection fails.
+     */
+    onMCPError(callback: IgniterAgentHooks["onMCPError"]): IgniterAgentBuilder<TAgentName, TAgentModel, TAgentInstructions, TAgentToolsets, TAgentMCPConfigs, TAgentContextSchema>;
+    /**
+     * Sets the context schema.
+     *
+     * @description
+     * Configures a Zod schema for validating context passed to the agent.
+     * The context is available in prompt templates and can be used to
+     * customize agent behavior per-request.
+     *
+     * @typeParam TNewSchema - The new schema type
+     * @param schema - The Zod schema for context validation
+     * @returns A new builder with the schema set
+     *
+     * @example
+     * ```typescript
+     * import { z } from 'zod';
+     *
+     * const contextSchema = z.object({
+     *   userId: z.string(),
+     *   chatId: z.string(),
+     *   userRole: z.enum(['admin', 'user', 'guest']),
+     *   preferences: z.object({
+     *     language: z.string().default('en'),
+     *     theme: z.string().optional()
+     *   })
+     * });
+     *
+     * const agent = IgniterAgent.create()
+     *   .withContextSchema(contextSchema)
+     *   .build();
+     *
+     * // Context is type-safe when calling generate
+     * await agent.generate({
+     *   messages: [...],
+     *   options: {
+     *     userId: 'user_123',
+     *     chatId: 'chat_456',
+     *     userRole: 'admin',
+     *     preferences: { language: 'pt' }
+     *   }
+     * });
+     * ```
+     *
+     * @public
+     */
+    withContextSchema<TNewSchema extends z.ZodSchema>(schema: TNewSchema): IgniterAgentBuilder<TAgentName, TAgentModel, TAgentInstructions, TAgentToolsets, TAgentMCPConfigs, TNewSchema>;
+    /**
+     * Adds a toolset to the agent.
+     *
+     * @description
+     * Registers a toolset with the agent. The toolset's tools become available
+     * for the AI to invoke. Multiple toolsets can be added to a single agent.
+     *
+     * Tool names are prefixed with the toolset name to avoid collisions:
+     * `{toolsetName}_{toolName}`
+     *
+     * @typeParam TNewToolset - The toolset type
+     * @param toolset - The toolset to register
+     * @returns A new builder with the toolset added
+     *
+     * @example
+     * ```typescript
+   * const githubToolset = IgniterAgentToolset.create('github')
+   *   .addTool(createIssueTool)
+   *   .addTool(listReposTool)
+     *   .build();
+     *
+   * const dockerToolset = IgniterAgentToolset.create('docker')
+   *   .addTool(buildImageTool)
+   *   .addTool(runContainerTool)
+     *   .build();
+     *
+     * const agent = IgniterAgent.create()
+     *   .addToolset(githubToolset)  // Adds github_createIssue, github_listRepos
+     *   .addToolset(dockerToolset)  // Adds docker_build, docker_run
+     *   .build();
+     * ```
+     *
+     * @public
+     */
+    addToolset<TNewToolset extends IgniterAgentToolset$1>(toolset: TNewToolset): IgniterAgentBuilder<TAgentName, TAgentModel, TAgentInstructions, TAgentToolsets & {
+        [K in TNewToolset["name"]]: TNewToolset;
+    }, TAgentMCPConfigs, TAgentContextSchema>;
+    /**
+     * Adds an MCP configuration to the agent.
+     *
+     * @description
+     * Registers an MCP server configuration with the agent. The MCP server
+     * will be connected when `agent.start()` is called, and its tools will
+     * become available for the AI to invoke.
+     *
+     * @typeParam TMCPType - The MCP transport type
+     * @typeParam TMCPName - The MCP configuration name
+     * @param config - The MCP configuration
+     * @returns A new builder with the MCP config added
+     *
+     * @example
+     * ```typescript
+     * const filesystemMCP = IgniterAgentMCPClient.create('filesystem')
+     *   .withType('stdio')
+     *   .withCommand('npx')
+     *   .withArgs(['-y', '@modelcontextprotocol/server-filesystem', '/tmp'])
+     *   .build();
+     *
+     * const remoteMCP = IgniterAgentMCPClient.create('remote-api')
+     *   .withType('http')
+     *   .withURL('https://api.example.com/mcp')
+     *   .withHeaders({ 'Authorization': 'Bearer xxx' })
+     *   .build();
+     *
+     * const agent = IgniterAgent.create()
+     *   .addMCP(filesystemMCP)
+     *   .addMCP(remoteMCP)
+     *   .build();
+     *
+     * // MCP connections are established here
+     * await agent.start();
+     * ```
+     *
+     * @public
+     */
+    addMCP<TMCPName extends string>(config: IgniterAgentMCPConfigUnion<TMCPName>): IgniterAgentBuilder<TAgentName, TAgentModel, TAgentInstructions, TAgentToolsets, TAgentMCPConfigs & {
+        [K in TMCPName]: typeof config;
+    }, TAgentContextSchema>;
+    /**
+     * Builds and returns the completed agent.
+     *
+     * @description
+     * Finalizes the agent configuration and returns a runtime agent object.
+     * The agent provides methods for:
+     * - `start()`: Initialize MCP connections
+     * - `generate()`: Generate a single response
+     * - `stream()`: Stream a response
+     * - Accessors for configuration
+     *
+     * @returns The built agent runtime object
+     *
+     * @example
+     * ```typescript
+     * const agent = IgniterAgent.create('assistant')
+     *   .withModel(openai('gpt-4'))
+     *   .addToolset(myToolset)
+     *   .build();
+     *
+     * // Start the agent
+     * await agent.start();
+     *
+     * // Generate a response
+     * const result = await agent.generate({
+     *   messages: [{ role: 'user', content: 'Hello!' }]
+     * });
+     *
+     * // Access configuration
+     * console.log('Model:', agent.getModel());
+     * console.log('Toolsets:', agent.getToolsets());
+     * ```
+     *
+     * @public
+     */
+    build(): IgniterAgentBuiltAgent<TAgentContextSchema, TAgentToolsets, TAgentModel, TAgentInstructions>;
+    /**
+     * Gets the current configuration (partial).
+     *
+     * @returns The current configuration state
+     * @public
+     */
+    getConfig(): Partial<IgniterAgentConfig<TAgentName, TAgentModel, TAgentInstructions, TAgentToolsets, TAgentMCPConfigs, TAgentContextSchema>>;
+    /**
+     * Gets the agent name.
+     *
+     * @returns The agent's name
+     * @public
+     */
+    getName(): TAgentName;
+}
+/**
+ * Alias for IgniterAgentBuilder for cleaner API.
+ *
+ * @description
+ * Use `IgniterAgent.create()` as the primary entry point for building agents.
+ *
+ * @example
+ * ```typescript
+ * import { IgniterAgent } from '@igniter-js/agents';
+ *
+ * const agent = IgniterAgent.create('assistant')
+ *   .withModel(openai('gpt-4'))
+ *   .build();
+ * ```
+ *
+ * @public
+ */
+declare const IgniterAgent: {
+    create: typeof IgniterAgentBuilder.create;
+};
+/**
+ * Type alias for the IgniterAgent class.
+ * @public
+ */
+type IgniterAgent = typeof IgniterAgentBuilder;
+
+/**
+ * @fileoverview Toolset Builder for creating custom tool collections.
+ * This module provides a fluent API for building toolsets with type safety.
+ *
+ * @description
+ * The IgniterAgentToolsetBuilder allows you to create collections of related
+ * tools that can be registered with an agent. Each toolset has a unique name
+ * and contains one or more tools that the AI can invoke.
+ *
+ * @example
+ * ```typescript
+ * import { IgniterAgentToolsetBuilder, IgniterAgentTool } from '@igniter-js/agents/builders';
+ * import { z } from 'zod';
+ *
+ * const createIssue = IgniterAgentTool
+ *   .create('createIssue')
+ *   .withDescription('Creates a new issue in a GitHub repository')
+ *   .withInput(z.object({
+ *     repo: z.string().describe('Repository name (owner/repo)'),
+ *     title: z.string().describe('Issue title'),
+ *     body: z.string().optional().describe('Issue body')
+ *   }))
+ *   .withExecute(async ({ repo, title, body }) => {
+ *     return await github.createIssue(repo, title, body);
+ *   })
+ *   .build();
+ *
+ * const listRepos = IgniterAgentTool
+ *   .create('listRepos')
+ *   .withDescription('Lists repositories for a user')
+ *   .withInputect({
+ *     username: z.string().describe('GitHub username')
+ *   }))
+ *   .withExecute(async ({ username }) => {
+ *     return await github.listRepos(username);
+ *   })
+ *   .build();
+ *
+ * const githubToolset = IgniterAgentToolsetBuilder
+ *   .create('github')
+ *   .addTool(createIssue)
+ *   .addTool(listRepos)
+ *   .build();
+ * ```
+ *
+ * @module builders/toolset
+ * @packageDocumentation
+ */
+
+/**
+ * Fluent builder for creating custom toolsets.
+ *
+ * @description
+ * The IgniterAgentToolsetBuilder provides a type-safe fluent API for creating
+ * collections of related tools. Tools are wrapped with error handling and
+ * result normalization to ensure consistent behavior.
+ *
+ * **Key Features:**
+ * - Fluent chainable API
+ * - Full TypeScript type inference for tool parameters
+ * - Automatic error handling and result wrapping
+ * - Tool execution logging
+ *
+ * @typeParam TToolsetName - The unique name for this toolset
+ * @typeParam TTools - The accumulated tools collection type
+ *
+ * @example
+ * ```typescript
+ * // Create tools
+ * const getCurrent = IgniterAgentTool
+ *   .create('getCurrent')
+ *   .withDescription('Gets current weather for a location')
+ *   .withInputect({
+ *     city: z.string(),
+ *     units: z.enum(['celsius', 'fahrenheit']).default('celsius')
+ *   }))
+ *   .withExecute(async ({ city, units }) => {
+ *     const weather = await weatherApi.getCurrent(city, units);
+ *     return {
+ *       temperature: weather.temp,
+ *       conditions: weather.description,
+ *       humidity: weather.humidity
+ *     };
+ *   })
+ *   .build();
+ *
+ * const getForecast = IgniterAgentTool
+ *   .create('getForecast')
+ *   .withDescription('Gets 5-day weather forecast')
+ *   .withInputect({
+ *     city: z.string(),
+ *     days: z.number().min(1).max(7).default(5)
+ *   }))
+ *   .withExecute(async ({ city, days }) => {
+ *     return await weatherApi.getForecast(city, days);
+ *   })
+ *   .build();
+ *
+ * // Create a toolset with multiple tools
+ * const weatherToolset = IgniterAgentToolsetBuilder
+ *   .create('weather')
+ *   .addTool(getCurrent)
+ *   .addTool(getForecast)
+ *   .build();
+ *
+ * // Register with an agent
+ * const agent = IgniterAgent.create('assistant')
+ *   .addToolset(weatherToolset)
+ *   .build();
+ * ```
+ *
+ * @public
+ */
+declare class IgniterAgentToolsetBuilder<TToolsetName extends string = string, TTools extends ToolSet = Record<string, never>> {
+    /**
+     * The toolset's unique name.
+     * @internal
+     */
+    private readonly _name;
+    /**
+     * The accumulated tools collection.
+     * @internal
+     */
+    private readonly _tools;
+    /**
+     * Creates a new IgniterAgentToolsetBuilder instance.
+     *
+     * @param params - The toolset name and initial tools
+     * @internal
+     */
+    constructor(params: IgniterAgentToolsetParams<TToolsetName, TTools>);
+    /**
+     * Creates a new toolset builder with the given name.
+     *
+     * @description
+     * This is the primary entry point for creating a new toolset.
+     * The name must be unique within an agent and is used as a prefix
+     * for tool names when the toolset is registered.
+     *
+     * @typeParam TName - The toolset name type
+     * @param name - Unique name for the toolset
+     * @returns A new IgniterAgentToolsetBuilder instance
+     *
+     * @example
+     * ```typescript
+   * const tool = IgniterAgentTool
+   *   .create('doSomething')
+   *   .withDescription('Does something')
+   *   .withInputect({}))
+   *   .withExecute(async () => ({ ok: true }))
+   *   .build();
+   *
+   * const toolset = IgniterAgentToolset
+   *   .create('myTools')
+   *   .addTool(tool)
+   *   .build();
+     * ```
+     *
+     * @public
+     */
+    static create<TName extends string>(name: TName): IgniterAgentToolsetBuilder<TName, {}>;
+    /**
+     * Changes the toolset name.
+     *
+     * @description
+     * Allows renaming the toolset during the building process.
+     * This creates a new builder instance with the new name.
+     *
+     * @typeParam TNewName - The new name type
+     * @param name - The new name for the toolset
+     * @returns A new builder with the updated name
+     *
+     * @example
+     * ```typescript
+   * const toolset = IgniterAgentToolset
+   *   .create('temp')
+   *   .withName('production')  // Rename to 'production'
+   *   .addTool(myTool)
+   *   .build();
+     * ```
+     *
+     * @public
+     */
+    withName<TNewName extends string>(name: TNewName): IgniterAgentToolsetBuilder<TNewName, TTools>;
+    /**
+     * Adds a tool to the toolset.
+     *
+     * @description
+     * Adds a built tool definition to the toolset. The tool is automatically
+     * wrapped with error handling that returns a consistent result format
+     * (`{ success: true, data: ... }` or `{ success: false, error: ... }`).
+     *
+     * @typeParam TToolName - The tool name type
+     * @param dto - The built tool definition
+     * @returns A new builder with the tool added
+     *
+     * @example
+     * ```typescript
+     * const greetTool = IgniterAgentTool.create('greet')
+     *   .withDescription('Greets a user')
+     *   .withInputect({ name: z.string() }))
+     *   .withExecute(async ({ name }) => `Hello, ${name}!`)
+     *   .build();
+     *
+     * const toolset = IgniterAgentToolset.create('utils')
+     *   .addTool(greetTool)
+     *   .build();
+     * ```
+     *
+     * @public
+     */
+    addTool<TTool extends IgniterAgentBuiltTool<any, any, any>>(dto: TTool): IgniterAgentToolsetBuilder<TToolsetName, TTools & {
+        [K in TTool['$Infer']['Name']]: Tool<TTool['$Infer']['Input'], TTool['$Infer']['Output']>;
+    }>;
+    /**
+     * Builds and returns the completed toolset.
+     *
+     * @description
+     * Finalizes the toolset configuration and returns an object that can
+     * be registered with an agent using `addToolset()`.
+     *
+     * The returned object includes:
+     * - `name`: The toolset's unique identifier
+     * - `type`: Always `'custom'` for user-defined toolsets
+     * - `status`: Always `'connected'` for custom toolsets
+     * - `tools`: The tools collection
+     * - `toolset`: Reference to the raw tools object
+     *
+     * @returns The completed toolset configuration
+     *
+     * @example
+     * ```typescript
+   * const toolset = IgniterAgentToolset
+   *   .create('utils')
+   *   .addTool(formatDateTool)
+   *   .addTool(parseJsonTool)
+   *   .build();
+     *
+     * console.log(toolset.name);   // 'utils'
+     * console.log(toolset.type);   // 'custom'
+     * console.log(toolset.status); // 'connected'
+     * console.log(Object.keys(toolset.tools)); // ['formatDate', 'parseJSON']
+     * ```
+     *
+     * @public
+     */
+    build(): IgniterAgentBuiltToolset<TToolsetName, TTools>;
+    /**
+     * Gets the current toolset name.
+     *
+     * @returns The toolset's name
+     * @public
+     */
+    getName(): TToolsetName;
+    /**
+     * Gets the current tools collection.
+     *
+     * @returns The tools object
+     * @public
+     */
+    getTools(): TTools;
+    /**
+     * Gets the number of tools in the toolset.
+     *
+     * @returns The tool count
+     * @public
+     */
+    getToolCount(): number;
+}
+/**
+ * Factory function to create a new toolset builder.
+ *
+ * @description
+ * Convenience function that wraps `IgniterAgentToolsetBuilder.create()`.
+ * Useful for more concise code or functional programming patterns.
+ *
+ * @typeParam TName - The toolset name type
+ * @param name - Unique name for the toolset
+ * @returns A new IgniterAgentToolsetBuilder instance
+ *
+ * @example
+ * ```typescript
+ * import { IgniterAgentToolset, IgniterAgentTool } from '@igniter-js/agents';
+ *
+ * const sayHello = IgniterAgentTool
+ *   .create('sayHello')
+ *   .withDescription('Says hello')
+ *   .withInputect({ name: z.string() }))
+ *   .withExecute(async ({ name }) => `Hello, ${name}!`)
+ *   .build();
+ *
+ * const myToolset = IgniterAgentToolset.create('myTools')
+ *   .addTool(sayHello)
+ *   .build();
+ * ```
+ *
+ * @public
+ */
+declare const IgniterAgentToolset: {
+    create: typeof IgniterAgentToolsetBuilder.create;
+};
+
+/**
+ * @fileoverview Tool Builder for creating individual tool definitions.
+ * This module provides a fluent API for building single tools with type safety.
+ *
+ * @description
+ * The IgniterAgentToolBuilder allows you to define a single tool using a
+ * fluent builder pattern. The resulting tool definition can be added to a
+ * toolset builder for registration with an agent.
+ *
+ * @example
+ * ```typescript
+ * import { IgniterAgentTool } from '@igniter-js/agents';
+ * import { z } from 'zod';
+ *
+ * const greetTool = IgniterAgentTool
+ *   .create('greet')
+ *   .withDescription('Greets a user by name')
+ *   .withInput(z.object({ name: z.string() }))
+ *   .withExecute(async ({ name }) => `Hello, ${name}!`)
+ *   .build();
+ * ```
+ *
+ * @module builders/tool
+ * @packageDocumentation
+ */
+
+/**
+ * Fluent builder for creating a single tool definition.
+ *
+ * @description
+ * The IgniterAgentToolBuilder provides a type-safe fluent API for defining
+ * a tool's metadata, input schema, and execution handler.
+ *
+ * @typeParam TName - The tool's unique name
+ * @typeParam TInputSchema - The tool parameters type
+ * @typeParam TOutputSchema - The tool result type
+ *
+ * @public
+ */
+declare class IgniterAgentToolBuilder<TName extends string = string, TInputSchema = unknown, TOutputSchema = undefined, TExecute extends (params: TInputSchema, options: IgniterAgentToolExecuteOptions) => Promise<unknown> = any> {
+    /**
+     * The accumulated tool definition.
+     * @internal
+     */
+    private readonly _definition;
+    /**
+     * Creates a new IgniterAgentToolBuilder instance.
+     *
+     * @param name - The tool name
+     * @param definition - Partial tool definition
+     * @internal
+     */
+    private constructor();
+    /**
+     * Creates a new tool builder with the given name.
+     *
+     * @description
+     * The name must be unique within a toolset.
+     *
+     * @typeParam TNewName - The tool name type
+     * @param name - Unique name for the tool
+     * @returns A new IgniterAgentToolBuilder instance
+     *
+     * @public
+     */
+    static create<TNewName extends string>(name: TNewName): IgniterAgentToolBuilder<TNewName, unknown, unknown>;
+    /**
+     * Sets the tool description.
+     *
+     * @param description - Human-readable description shown to the AI
+     * @returns A new builder with the description set
+     *
+     * @public
+     */
+    withDescription(description: string): IgniterAgentToolBuilder<TName, TInputSchema, TOutputSchema>;
+    /**
+     * Sets the tool parameters schema.
+     *
+     * @typeParam TNewParams - The new parameters type
+     * @param parameters - Zod schema defining input parameters
+     * @returns A new builder with the parameters set
+     *
+     * @public
+     */
+    withInput<TNewParams>(inputSchema: z.ZodSchema<TNewParams>): IgniterAgentToolBuilder<TName, TNewParams, TOutputSchema>;
+    /**
+     * Sets the tool output schema.
+     *
+     * @typeParam TNewResult - The new result type
+     * @param outputSchema - Zod schema defining the tool's output
+     * @returns A new builder with the output schema set
+     *
+     * @public
+     */
+    withOutput<TNewResult>(outputSchema: z.ZodSchema<TNewResult>): IgniterAgentToolBuilder<TName, TInputSchema, TNewResult>;
+    /**
+     * Sets the tool execution handler.
+     *
+     * @typeParam TNewResult - The new result type
+     * @param execute - Function that performs the tool's logic
+     * @returns A new builder with the execute handler set
+     *
+     * @public
+     */
+    withExecute<TNewExecute extends (params: TInputSchema, options: IgniterAgentToolExecuteOptions) => TOutputSchema extends undefined ? Promise<unknown> : Promise<TOutputSchema>, TNewResult = Awaited<ReturnType<TNewExecute>>>(execute: TNewExecute): IgniterAgentToolBuilder<TName, TInputSchema, TNewResult, TNewExecute>;
+    /**
+     * Builds and returns the completed tool definition.
+     *
+     * @returns The completed tool definition with its name
+     *
+     * @public
+     */
+    build(): IgniterAgentBuiltTool<TName, TInputSchema, TOutputSchema>;
+}
+/**
+ * Factory function to create a new tool builder.
+ *
+ * @description
+ * Convenience function that wraps `IgniterAgentTool.create('toolName')`.
+ *
+ * @typeParam TName - The tool name type
+ * @param name - Unique name for the tool
+ * @returns A new IgniterAgentToolBuilder instance
+ *
+ * @public
+ */
+declare const IgniterAgentTool: {
+    create: typeof IgniterAgentToolBuilder.create;
+};
+
+/**
+ * @fileoverview MCP (Model Context Protocol) Client Builder.
+ * This module provides a fluent API for configuring MCP server connections.
+ *
+ * @description
+ * The IgniterAgentMCPBuilder allows you to configure connections to MCP servers
+ * using either stdio (local process) or HTTP (remote server) transport.
+ *
+ * MCP servers provide tools that the agent can invoke, similar to custom toolsets,
+ * but the tools are hosted externally and discovered at runtime.
+ *
+ * @see {@link https://modelcontextprotocol.io/ | Model Context Protocol}
+ *
+ * @example
+ * ```typescript
+ * import { IgniterAgentMCPBuilder } from '@igniter-js/agents/builders';
+ *
+ * // Configure a stdio MCP server (local process)
+ * const filesystemMCP = IgniterAgentMCPBuilder
+ *   .create('filesystem')
+ *   .withType('stdio')
+ *   .withCommand('npx')
+ *   .withArgs(['-y', '@modelcontextprotocol/server-filesystem', '/tmp'])
+ *   .withEnv({ DEBUG: 'true' })
+ *   .build();
+ *
+ * // Configure an HTTP MCP server (remote)
+ * const remoteMCP = IgniterAgentMCPBuilder
+ *   .create('remote-tools')
+ *   .withType('http')
+ *   .withURL('https://mcp.example.com/api')
+ *   .withHeaders({ 'Authorization': 'Bearer token123' })
+ *   .build();
+ * ```
+ *
+ * @module builders/mcp
+ * @packageDocumentation
+ */
+
+/**
+ * Fluent builder for configuring MCP server connections.
+ *
+ * @description
+ * The IgniterAgentMCPBuilder provides a type-safe fluent API for creating
+ * MCP server configurations. The builder adapts its available methods based
+ * on the transport type selected.
+ *
+ * **Transport Types:**
+ * - `stdio`: For local MCP servers running as child processes
+ * - `http`: For remote MCP servers accessed over HTTP/HTTPS
+ *
+ * **Key Features:**
+ * - Type-safe configuration based on transport type
+ * - Validation of required fields
+ * - Environment variable support for stdio
+ * - Header support for HTTP authentication
+ *
+ * @typeParam TType - The transport type ('stdio' | 'http')
+ * @typeParam TName - The unique configuration name
+ *
+ * @example
+ * ```typescript
+ * // Stdio transport (local process)
+ * const localMCP = IgniterAgentMCPBuilder
+ *   .create('github')
+ *   .withType('stdio')
+ *   .withCommand('npx')
+ *   .withArgs(['-y', '@modelcontextprotocol/server-github'])
+ *   .withEnv({ GITHUB_TOKEN: process.env.GITHUB_TOKEN! })
+ *   .build();
+ *
+ * // HTTP transport (remote server)
+ * const remoteMCP = IgniterAgentMCPBuilder
+ *   .create('opencode')
+ *   .withType('http')
+ *   .withURL('https://sandbox.example.com/mcp')
+ *   .withHeaders({
+ *     'X-API-Key': process.env.API_KEY!,
+ *     'Content-Type': 'application/json'
+ *   })
+ *   .build();
+ *
+ * // Register with an agent
+ * const agent = IgniterAgent.create('my-agent')
+ *   .addMCP(localMCP)
+ *   .addMCP(remoteMCP)
+ *   .build();
+ * ```
+ *
+ * @public
+ */
+declare class IgniterAgentMCPBuilder<TType extends IgniterAgentToolsetType = IgniterAgentToolsetType, TName extends string = string> {
+    /**
+     * The configuration being built.
+     * @internal
+     */
+    private readonly _config;
+    /**
+     * Creates a new IgniterAgentMCPBuilder instance.
+     *
+     * @param config - Initial configuration
+     * @internal
+     */
+    private constructor();
+    /**
+     * Creates a new MCP builder with the given name.
+     *
+     * @description
+     * This is the primary entry point for creating an MCP configuration.
+     * The name must be unique within an agent and is used to identify
+     * the MCP server and its tools.
+     *
+     * After calling `create()`, you must call `withType()` to specify
+     * the transport type before configuring transport-specific options.
+     *
+     * @typeParam TNewName - The configuration name type
+     * @param name - Unique name for the MCP configuration
+     * @returns A new IgniterAgentMCPBuilder instance
+     *
+     * @example
+     * ```typescript
+     * const mcpConfig = IgniterAgentMCPBuilder
+     *   .create('my-mcp')
+     *   .withType('stdio')  // or 'http'
+     *   .withCommand('...')  // available after withType('stdio')
+     *   .build();
+     * ```
+     *
+     * @public
+     */
+    static create<TNewName extends string>(name: TNewName): IgniterAgentMCPBuilder<IgniterAgentToolsetType, TNewName>;
+    /**
+     * Sets the configuration name.
+     *
+     * @description
+     * Allows changing the configuration name during the building process.
+     *
+     * @typeParam TNewName - The new name type
+     * @param name - The new name for the configuration
+     * @returns A new builder with the updated name
+     *
+     * @public
+     */
+    withName<TNewName extends string>(name: TNewName): IgniterAgentMCPBuilder<TType, TNewName>;
+    /**
+     * Sets the transport type for the MCP connection.
+     *
+     * @description
+     * Specifies how the agent will communicate with the MCP server:
+     * - `stdio`: Spawns a local process and communicates via stdin/stdout
+     * - `http`: Connects to a remote server via HTTP/HTTPS
+     *
+     * After calling this method, transport-specific methods become available:
+     * - For `stdio`: `withCommand()`, `withArgs()`, `withEnv()`
+     * - For `http`: `withURL()`, `withHeaders()`
+     *
+     * @typeParam TNewType - The transport type
+     * @param type - The transport type to use
+     * @returns A new builder configured for the specified transport
+     *
+     * @example
+     * ```typescript
+     * // Stdio transport
+     * const stdioConfig = IgniterAgentMCPBuilder
+     *   .create('local')
+     *   .withType('stdio')
+     *   .withCommand('python')
+     *   .withArgs(['mcp_server.py'])
+     *   .build();
+     *
+     * // HTTP transport
+     * const httpConfig = IgniterAgentMCPBuilder
+     *   .create('remote')
+     *   .withType('http')
+     *   .withURL('https://api.example.com/mcp')
+     *   .build();
+     * ```
+     *
+     * @public
+     */
+    withType<TNewType extends IgniterAgentToolsetType>(type: TNewType): IgniterAgentMCPBuilder<TNewType, TName>;
+    /**
+     * Sets the command to execute for stdio transport.
+     *
+     * @description
+     * Specifies the executable to run when starting the MCP server process.
+     * Common values include `npx`, `node`, `python`, `deno`, etc.
+     *
+     * @param command - The command to execute
+     * @returns A new builder with the command set
+     * @throws {IgniterAgentConfigError} If transport type is not 'stdio'
+     *
+     * @example
+     * ```typescript
+     * const config = IgniterAgentMCPBuilder
+     *   .create('filesystem')
+     *   .withType('stdio')
+     *   .withCommand('npx')
+     *   .withArgs(['-y', '@modelcontextprotocol/server-filesystem'])
+     *   .build();
+     * ```
+     *
+     * @public
+     */
+    withCommand(command: string): IgniterAgentMCPBuilder<TType, TName>;
+    /**
+     * Sets the arguments to pass to the command.
+     *
+     * @description
+     * Specifies command-line arguments for the MCP server process.
+     *
+     * @param args - Array of command arguments
+     * @returns A new builder with the arguments set
+     * @throws {IgniterAgentConfigError} If transport type is not 'stdio'
+     *
+     * @example
+     * ```typescript
+     * const config = IgniterAgentMCPBuilder
+     *   .create('filesystem')
+     *   .withType('stdio')
+     *   .withCommand('npx')
+     *   .withArgs([
+     *     '-y',
+     *     '@modelcontextprotocol/server-filesystem',
+     *     '/home/user/documents',
+     *     '--read-only'
+     *   ])
+     *   .build();
+     * ```
+     *
+     * @public
+     */
+    withArgs(args: string[]): IgniterAgentMCPBuilder<TType, TName>;
+    /**
+     * Sets environment variables for the command process.
+     *
+     * @description
+     * Specifies environment variables to pass to the MCP server process.
+     * Useful for passing API keys, configuration, or feature flags.
+     *
+     * @param env - Record of environment variable names to values
+     * @returns A new builder with the environment variables set
+     * @throws {IgniterAgentConfigError} If transport type is not 'stdio'
+     *
+     * @example
+     * ```typescript
+     * const config = IgniterAgentMCPBuilder
+     *   .create('github')
+     *   .withType('stdio')
+     *   .withCommand('npx')
+     *   .withArgs(['-y', '@modelcontextprotocol/server-github'])
+     *   .withEnv({
+     *     GITHUB_TOKEN: process.env.GITHUB_TOKEN!,
+     *     GITHUB_ORG: 'my-organization',
+     *     DEBUG: 'mcp:*'
+     *   })
+     *   .build();
+     * ```
+     *
+     * @public
+     */
+    withEnv(env: Record<string, string>): IgniterAgentMCPBuilder<TType, TName>;
+    /**
+     * Sets the URL for HTTP transport.
+     *
+     * @description
+     * Specifies the endpoint URL for the remote MCP server.
+     * Must be a valid HTTP or HTTPS URL.
+     *
+     * @param url - The MCP server URL
+     * @returns A new builder with the URL set
+     * @throws {IgniterAgentConfigError} If transport type is not 'http' or URL is invalid
+     *
+     * @example
+     * ```typescript
+     * const config = IgniterAgentMCPBuilder
+     *   .create('opencode')
+     *   .withType('http')
+     *   .withURL('https://sandbox.example.com/mcp/v1')
+     *   .build();
+     * ```
+     *
+     * @public
+     */
+    withURL(url: string): IgniterAgentMCPBuilder<TType, TName>;
+    /**
+     * Sets HTTP headers for requests to the MCP server.
+     *
+     * @description
+     * Specifies headers to include in all HTTP requests to the MCP server.
+     * Commonly used for authentication, API keys, or content type.
+     *
+     * @param headers - Record of header names to values
+     * @returns A new builder with the headers set
+     * @throws {IgniterAgentConfigError} If transport type is not 'http'
+     *
+     * @example
+     * ```typescript
+     * const config = IgniterAgentMCPBuilder
+     *   .create('authenticated-mcp')
+     *   .withType('http')
+     *   .withURL('https://api.example.com/mcp')
+     *   .withHeaders({
+     *     'Authorization': `Bearer ${process.env.API_TOKEN}`,
+     *     'X-Client-ID': 'my-app',
+     *     'Content-Type': 'application/json'
+     *   })
+     *   .build();
+     * ```
+     *
+     * @public
+     */
+    withHeaders(headers: Record<string, string>): IgniterAgentMCPBuilder<TType, TName>;
+    /**
+     * Builds and returns the completed MCP configuration.
+     *
+     * @description
+     * Validates the configuration and returns a typed configuration object
+     * that can be registered with an agent using `addMCP()`.
+     *
+     * @returns The completed MCP configuration
+     * @throws {IgniterAgentConfigError} If required fields are missing
+     *
+     * @example
+     * ```typescript
+     * const mcpConfig = IgniterAgentMCPBuilder
+     *   .create('filesystem')
+     *   .withType('stdio')
+     *   .withCommand('npx')
+     *   .withArgs(['-y', '@modelcontextprotocol/server-filesystem', '/tmp'])
+     *   .build();
+     *
+     * // Use with an agent
+     * const agent = IgniterAgent.create()
+     *   .addMCP(mcpConfig)
+     *   .build();
+     * ```
+     *
+     * @public
+     */
+    build(): TType extends "stdio" ? IgniterAgentMCPStdioConfig<TName> : TType extends "http" ? IgniterAgentMCPHttpConfig<TName> : IgniterAgentMCPConfigUnion<TName>;
+    /**
+     * Asserts that the current transport type is 'stdio'.
+     * @internal
+     */
+    private _assertStdioType;
+    /**
+     * Asserts that the current transport type is 'http'.
+     * @internal
+     */
+    private _assertHttpType;
+}
+/**
+ * Factory function to create a new MCP builder.
+ *
+ * @description
+ * Convenience function that wraps `IgniterAgentMCPBuilder.create()`.
+ *
+ * @typeParam TName - The configuration name type
+ * @param name - Unique name for the MCP configuration
+ * @returns A new IgniterAgentMCPBuilder instance
+ *
+ * @example
+ * ```typescript
+ * import { IgniterAgentMCPClient } from '@igniter-js/agents';
+ *
+ * const filesystemMCP = IgniterAgentMCPClient.create('filesystem')
+ *   .withType('stdio')
+ *   .withCommand('npx')
+ *   .withArgs(['-y', '@modelcontextprotocol/server-filesystem', '/tmp'])
+ *   .build();
+ * ```
+ *
+ * @public
+ */
+declare const IgniterAgentMCPClient: {
+    create: typeof IgniterAgentMCPBuilder.create;
+};
+
+/**
+ * @fileoverview Prompt builder for IgniterAgent instructions.
+ *
+ * @description
+ * Provides a lightweight template interpolation utility to build
+ * prompt strings with context data.
+ *
+ * @module builders/prompt
+ * @packageDocumentation
+ */
+
+/**
+ * Fluent prompt builder for agent instructions.
+ *
+ * @example
+ * ```typescript
+ * const prompt = IgniterAgentPrompt.create(
+ *   "You are {{agentName}}. User: {{user.name}}"
+ * );
+ *
+ * const result = prompt.build({ agentName: "assistant", user: { name: "Ada" } });
+ * // "You are assistant. User: Ada"
+ * ```
+ *
+ * @public
+ */
+declare class IgniterAgentPromptBuilder<TTemplate extends string = string, TContext extends Record<string, unknown> = Record<string, unknown>> implements IgniterAgentPromptTemplate<TContext> {
+    private readonly template;
+    private constructor();
+    /**
+     * Creates a new prompt builder.
+     *
+     * @param template - Prompt template string with {{placeholders}}
+     * @returns A new prompt builder instance
+     */
+    static create<TNewTemplate extends string>(template: TNewTemplate): IgniterAgentPromptBuilder<TNewTemplate, Record<string, unknown>>;
+    /**
+     * Builds the prompt string with the provided context.
+     *
+     * @param context - Context data used for interpolation
+     * @returns The resolved prompt string
+     */
+    build(context: TContext): string;
+    /**
+     * Returns the raw prompt template string.
+     */
+    getTemplate(): string;
+}
+/**
+ * Alias for IgniterAgentPromptBuilder for cleaner API.
+ *
+ * @public
+ */
+declare const IgniterAgentPrompt: typeof IgniterAgentPromptBuilder;
+/**
+ * Type alias for the prompt builder constructor.
+ *
+ * @public
+ */
+type IgniterAgentPrompt = typeof IgniterAgentPromptBuilder;
+
+/**
+ * @fileoverview Custom error classes for the IgniterAgent library.
+ * This module provides a hierarchy of error types for precise error handling.
+ *
+ * @description
+ * The error system in IgniterAgent follows these principles:
+ * - All errors extend IgniterError from @igniter-js/core for consistency
+ * - Errors include rich context for debugging
+ * - Error codes enable programmatic error handling
+ * - Stack traces are preserved for debugging
+ *
+ * @example
+ * ```typescript
+ * import {
+ *   IgniterAgentError,
+ *   IgniterAgentMCPError,
+ *   IgniterAgentToolError,
+ *   isIgniterAgentError
+ * } from '@igniter-js/agents';
+ *
+ * try {
+ *   await agent.generate({ messages: [] });
+ * } catch (error) {
+ *   if (isIgniterAgentError(error)) {
+ *     console.error(`[${error.code}] ${error.message}`);
+ *   }
+ * }
+ * ```
+ *
+ * @module errors
+ * @packageDocumentation
+ */
+
+/**
+ * Error codes for categorizing IgniterAgent errors.
+ *
+ * @description
+ * Each error code represents a specific type of failure.
+ * Use these codes for programmatic error handling.
+ *
+ * @example
+ * ```typescript
+ * if (error.code === IgniterAgentErrorCode.MCP_CONNECTION_FAILED) {
+ *   // Handle MCP connection failure
+ *   await retryMCPConnection();
+ * }
+ * ```
+ *
+ * @public
+ */
+declare enum IgniterAgentErrorCode {
+    /** Generic/unknown error */
+    UNKNOWN = "IGNITER_AGENT_UNKNOWN_ERROR",
+    /** Invalid configuration provided */
+    INVALID_CONFIG = "IGNITER_AGENT_INVALID_CONFIG",
+    /** Required value is missing */
+    MISSING_REQUIRED = "IGNITER_AGENT_MISSING_REQUIRED",
+    /** Agent not initialized */
+    AGENT_NOT_INITIALIZED = "IGNITER_AGENT_NOT_INITIALIZED",
+    /** Model not configured */
+    AGENT_MODEL_MISSING = "IGNITER_AGENT_MODEL_MISSING",
+    /** Agent build failed */
+    AGENT_BUILD_FAILED = "IGNITER_AGENT_BUILD_FAILED",
+    /** MCP connection failed */
+    MCP_CONNECTION_FAILED = "IGNITER_AGENT_MCP_CONNECTION_FAILED",
+    /** MCP client not found */
+    MCP_CLIENT_NOT_FOUND = "IGNITER_AGENT_MCP_CLIENT_NOT_FOUND",
+    /** MCP tool execution failed */
+    MCP_TOOL_ERROR = "IGNITER_AGENT_MCP_TOOL_ERROR",
+    /** Invalid MCP configuration */
+    MCP_INVALID_CONFIG = "IGNITER_AGENT_MCP_INVALID_CONFIG",
+    /** Tool execution failed */
+    TOOL_EXECUTION_FAILED = "IGNITER_AGENT_TOOL_EXECUTION_FAILED",
+    /** Tool not found */
+    TOOL_NOT_FOUND = "IGNITER_AGENT_TOOL_NOT_FOUND",
+    /** Tool validation failed */
+    TOOL_VALIDATION_FAILED = "IGNITER_AGENT_TOOL_VALIDATION_FAILED",
+    /** Invalid agent context schema */
+    AGENT_CONTEXT_SCHEMA_INVALID = "IGNITER_AGENT_CONTEXT_SCHEMA_INVALID",
+    /** Memory provider error */
+    MEMORY_PROVIDER_ERROR = "IGNITER_AGENT_MEMORY_PROVIDER_ERROR",
+    /** Memory not found */
+    MEMORY_NOT_FOUND = "IGNITER_AGENT_MEMORY_NOT_FOUND",
+    /** Memory update failed */
+    MEMORY_UPDATE_FAILED = "IGNITER_AGENT_MEMORY_UPDATE_FAILED",
+    /** Adapter connection failed */
+    ADAPTER_CONNECTION_FAILED = "IGNITER_AGENT_ADAPTER_CONNECTION_FAILED",
+    /** Adapter operation failed */
+    ADAPTER_OPERATION_FAILED = "IGNITER_AGENT_ADAPTER_OPERATION_FAILED",
+    /** Adapter not initialized */
+    ADAPTER_NOT_INITIALIZED = "IGNITER_AGENT_ADAPTER_NOT_INITIALIZED"
+}
+/**
+ * Options for creating an IgniterAgentError.
+ *
+ * @public
+ */
+interface IgniterAgentErrorOptions {
+    /** Human-readable error message */
+    message: string;
+    /** Error code for categorization */
+    code: IgniterAgentErrorCode;
+    /** HTTP status code (defaults to 500) */
+    statusCode?: number;
+    /** The component that threw the error */
+    causer?: string;
+    /** Additional details about the error */
+    details?: unknown;
+    /** Additional metadata */
+    metadata?: Record<string, unknown>;
+    /** Logger instance for automatic logging */
+    logger?: IgniterLogger;
+    /** Original error if this wraps another error */
+    cause?: Error;
+}
+/**
+ * Base error class for all IgniterAgent errors.
+ *
+ * @description
+ * All custom errors in the IgniterAgent library extend this class,
+ * which itself extends IgniterError from @igniter-js/core.
+ * It provides a consistent interface for error handling, including
+ * error codes, context, and cause tracking.
+ *
+ * @example
+ * ```typescript
+ * // Throwing a base error
+ * throw new IgniterAgentError({
+ *   message: 'Something went wrong',
+ *   code: IgniterAgentErrorCode.UNKNOWN,
+ *   causer: 'Agent',
+ *   metadata: { operation: 'generate' }
+ * });
+ *
+ * // Catching and handling
+ * try {
+ *   await agent.start();
+ * } catch (error) {
+ *   if (error instanceof IgniterAgentError) {
+ *     logger.error({
+ *       code: error.code,
+ *       message: error.message,
+ *       details: error.details
+ *     });
+ *   }
+ * }
+ * ```
+ *
+ * @public
+ */
+declare class IgniterAgentError extends IgniterError {
+    /**
+     * Creates a new IgniterAgentError.
+     *
+     * @param options - Error configuration options
+     */
+    constructor(options: IgniterAgentErrorOptions);
+}
+/**
+ * Error thrown when agent configuration is invalid.
+ *
+ * @example
+ * ```typescript
+ * throw new IgniterAgentConfigError({
+ *   message: 'Model is required but was not provided',
+ *   field: 'model'
+ * });
+ * ```
+ *
+ * @public
+ */
+declare class IgniterAgentConfigError extends IgniterAgentError {
+    /**
+     * The configuration field that caused the error.
+     */
+    readonly field?: string;
+    constructor(options: Omit<IgniterAgentErrorOptions, "code"> & {
+        field?: string;
+    });
+}
+/**
+ * Error thrown when an MCP operation fails.
+ *
+ * @description
+ * Covers all MCP-related failures including connection errors,
+ * tool execution errors, and configuration errors.
+ *
+ * @example
+ * ```typescript
+ * throw new IgniterAgentMCPError({
+ *   message: 'Failed to connect to MCP server',
+ *   code: IgniterAgentErrorCode.MCP_CONNECTION_FAILED,
+ *   mcpName: 'filesystem'
+ * });
+ * ```
+ *
+ * @public
+ */
+declare class IgniterAgentMCPError extends IgniterAgentError {
+    /**
+     * The name of the MCP configuration that caused the error.
+     */
+    readonly mcpName?: string;
+    constructor(options: IgniterAgentErrorOptions & {
+        mcpName?: string;
+    });
+}
+/**
+ * Error thrown when a tool execution fails.
+ *
+ * @example
+ * ```typescript
+ * throw new IgniterAgentToolError({
+ *   message: 'Tool execution timed out',
+ *   toolName: 'github_createIssue',
+ *   metadata: { timeout: 30000 }
+ * });
+ * ```
+ *
+ * @public
+ */
+declare class IgniterAgentToolError extends IgniterAgentError {
+    /**
+     * The name of the tool that caused the error.
+     */
+    readonly toolName: string;
+    constructor(options: Omit<IgniterAgentErrorOptions, "code"> & {
+        toolName: string;
+    });
+}
+/**
+ * Error thrown when a memory operation fails.
+ *
+ * @example
+ * ```typescript
+ * throw new IgniterAgentMemoryError({
+ *   message: 'Failed to save message to history',
+ *   code: IgniterAgentErrorCode.MEMORY_UPDATE_FAILED,
+ *   metadata: { chatId: 'chat_123' }
+ * });
+ * ```
+ *
+ * @public
+ */
+declare class IgniterAgentMemoryError extends IgniterAgentError {
+    constructor(options: IgniterAgentErrorOptions);
+}
+/**
+ * Error thrown when an adapter operation fails.
+ *
+ * @example
+ * ```typescript
+ * throw new IgniterAgentAdapterError({
+ *   message: 'Redis connection lost',
+ *   code: IgniterAgentErrorCode.ADAPTER_CONNECTION_FAILED,
+ *   adapterName: 'redis'
+ * });
+ * ```
+ *
+ * @public
+ */
+declare class IgniterAgentAdapterError extends IgniterAgentError {
+    /**
+     * The name of the adapter that caused the error.
+     */
+    readonly adapterName?: string;
+    constructor(options: IgniterAgentErrorOptions & {
+        adapterName?: string;
+    });
+}
+/**
+ * Type guard to check if an error is an IgniterAgentError.
+ *
+ * @description
+ * Use this function to safely narrow error types in catch blocks.
+ *
+ * @param error - The error to check
+ * @returns True if the error is an IgniterAgentError
+ *
+ * @example
+ * ```typescript
+ * try {
+ *   await agent.generate({ messages: [] });
+ * } catch (error) {
+ *   if (isIgniterAgentError(error)) {
+ *     // TypeScript knows error is IgniterAgentError
+ *     console.log(error.code, error.details);
+ *   }
+ * }
+ * ```
+ *
+ * @public
+ */
+declare function isIgniterAgentError(error: unknown): error is IgniterAgentError;
+/**
+ * Type guard to check if an error is an MCP error.
+ *
+ * @param error - The error to check
+ * @returns True if the error is an IgniterAgentMCPError
+ *
+ * @public
+ */
+declare function isIgniterAgentMCPError(error: unknown): error is IgniterAgentMCPError;
+/**
+ * Type guard to check if an error is a tool error.
+ *
+ * @param error - The error to check
+ * @returns True if the error is an IgniterAgentToolError
+ *
+ * @public
+ */
+declare function isIgniterAgentToolError(error: unknown): error is IgniterAgentToolError;
+/**
+ * Wraps an unknown error in an IgniterAgentError.
+ *
+ * @description
+ * Useful for normalizing errors from external sources into
+ * the IgniterAgent error format.
+ *
+ * @param error - The error to wrap
+ * @param options - Additional options to add
+ * @returns An IgniterAgentError wrapping the original
+ *
+ * @example
+ * ```typescript
+ * try {
+ *   await externalService.call();
+ * } catch (error) {
+ *   throw wrapError(error, { causer: 'ExternalService' });
+ * }
+ * ```
+ *
+ * @public
+ */
+declare function wrapError(error: unknown, options?: Partial<IgniterAgentErrorOptions>): IgniterAgentError;
+
+/**
+ * String utilities for `@igniter-js/agents`.
+ */
+declare class IgniterAgentStringUtils {
+    /**
+     * Generates a unique identifier.
+     */
+    static generateId(prefix?: string): string;
+    /**
+     * Truncates a string to a maximum length.
+     */
+    static truncate(str: string, maxLength: number, suffix?: string): string;
+    /**
+     * Converts a string to snake_case.
+     */
+    static toSnakeCase(str: string): string;
+    /**
+     * Converts a string to camelCase.
+     */
+    static toCamelCase(str: string): string;
+}
+
+/**
+ * Object utilities for `@igniter-js/agents`.
+ */
+declare class IgniterAgentObjectUtils {
+    /**
+     * Deep merges two objects.
+     */
+    static deepMerge<T extends Record<string, unknown>>(target: T, source: Partial<T>): T;
+    /**
+     * Picks specified keys from an object.
+     */
+    static pick<T extends Record<string, unknown>, K extends keyof T>(obj: T, keys: K[]): Pick<T, K>;
+    /**
+     * Omits specified keys from an object.
+     */
+    static omit<T extends Record<string, unknown>, K extends keyof T>(obj: T, keys: K[]): Omit<T, K>;
+}
+
+/**
+ * Async utilities for `@igniter-js/agents`.
+ */
+declare class IgniterAgentAsyncUtils {
+    /**
+     * Delays execution for a specified duration.
+     */
+    static delay(ms: number): Promise<void>;
+    /**
+     * Retries an async function with exponential backoff.
+     */
+    static retry<T>(fn: () => Promise<T>, options?: {
+        maxAttempts?: number;
+        baseDelay?: number;
+        maxDelay?: number;
+        onRetry?: (attempt: number, error: Error) => void;
+    }): Promise<T>;
+}
+
+/**
+ * Validation utilities for `@igniter-js/agents`.
+ */
+declare class IgniterAgentValidationUtils {
+    /**
+     * Checks if a value is defined (not null or undefined).
+     */
+    static isDefined<T>(value: T | null | undefined): value is T;
+    /**
+     * Checks if a value is a non-empty string.
+     */
+    static isNonEmptyString(value: unknown): value is string;
+    /**
+     * Checks if a value is a plain object.
+     */
+    static isPlainObject(value: unknown): value is Record<string, unknown>;
+}
+
+export { type DeepPartial, type DeepRequired, IgniterAgent, IgniterAgentAdapterError, IgniterAgentAsyncUtils, IgniterAgentBuilder, type IgniterAgentBuiltAgent, type IgniterAgentBuiltTool, type IgniterAgentBuiltToolset, IgniterAgentChatSession, type IgniterAgentConfig, IgniterAgentConfigError, type IgniterAgentConnectionStatus, IgniterAgentConversationMessage, IgniterAgentCore, IgniterAgentError, IgniterAgentErrorCode, type IgniterAgentErrorOptions, type IgniterAgentFlattenedToolSet, IgniterAgentGetChatsParams, IgniterAgentGetMessagesParams, type IgniterAgentHooks, type IgniterAgentInfo, IgniterAgentMCPBuilder, IgniterAgentMCPClient, type IgniterAgentMCPClientInterface, type IgniterAgentMCPConfigBase, type IgniterAgentMCPConfigUnion, IgniterAgentMCPError, type IgniterAgentMCPHttpClientInterface, type IgniterAgentMCPHttpConfig, type IgniterAgentMCPPartialConfig, type IgniterAgentMCPStdioClientInterface, type IgniterAgentMCPStdioConfig, IgniterAgentManager, IgniterAgentManagerBuilder, IgniterAgentManagerCore, type IgniterAgentManagerOptions, IgniterAgentMemoryConfig, IgniterAgentMemoryCore, IgniterAgentMemoryError, IgniterAgentMemoryRuntime, IgniterAgentObjectUtils, IgniterAgentPrompt, IgniterAgentPromptBuilder, type IgniterAgentPromptTemplate, type IgniterAgentStatus, IgniterAgentStringUtils, IgniterAgentTool, IgniterAgentToolBuilder, type IgniterAgentToolDefinition, IgniterAgentToolError, type IgniterAgentToolErrorResult, type IgniterAgentToolExecuteOptions, type IgniterAgentToolResult, type IgniterAgentToolSuccessResult, IgniterAgentToolset, IgniterAgentToolsetBuilder, type IgniterAgentToolsetParams, type IgniterAgentToolsetType, IgniterAgentUIMessage, IgniterAgentUpdateWorkingMemoryParams, IgniterAgentValidationUtils, IgniterAgentWorkingMemory, IgniterAgentWorkingMemoryParams, type InferZodSchema, type KeysOfType, isIgniterAgentError, isIgniterAgentMCPError, isIgniterAgentToolError, wrapError };