@igniter-js/agents 0.1.13 → 0.1.14

package/dist/index.d.mts

@@ -1,8 +1,9 @@
-import { ToolSet, LanguageModel, ToolLoopAgent, AgentCallParameters, GenerateTextResult, AgentStreamParameters, StreamTextResult, Tool } from 'ai';
-import { IgniterLogger, IgniterError } from '@igniter-js/core';
+import * as ai from 'ai';
+import { ToolSet, LanguageModel, ToolLoopAgent, LanguageModelResponseMetadata, LanguageModelUsage, FinishReason, ModelMessage, AgentCallParameters, AgentStreamParameters, GenerateTextResult, StreamTextResult, Tool, UIMessageStreamWriter } from 'ai';
+import { IgniterLogger, IgniterError } from '@igniter-js/common';
 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.mjs';
-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.mjs';
+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-CqUbHeyY.mjs';
+export { B as IgniterAgentAdapterBatchResult, A as IgniterAgentAdapterFactory, w as IgniterAgentAdapterOptions, C as IgniterAgentAdapterStats, s as IgniterAgentChatsConfig, p as IgniterAgentGenerateSuggestionsConfig, o as IgniterAgentGenerateTitleConfig, r as IgniterAgentHistoryConfig, j as IgniterAgentInMemoryAdapter, x as IgniterAgentInMemoryAdapterOptions, l as IgniterAgentJSONFileAdapter, k as IgniterAgentJSONFileAdapterOptions, z as IgniterAgentMemoryAdapter, v as IgniterAgentMemoryProvider, n as IgniterAgentMemoryScope, m as IgniterAgentMessageRole, y as IgniterAgentRedisAdapterOptions, t as IgniterAgentSearchParams, u as IgniterAgentSearchResult, q as IgniterAgentWorkingMemoryConfig } from './index-CqUbHeyY.mjs';
 import { z } from 'zod';
 
 /**
@@ -14,7 +15,7 @@ import { z } from 'zod';
  *
  * @public
  */
-interface IgniterAgentPromptTemplate<TContext extends Record<string, unknown> = Record<string, unknown>> {
+interface IgniterAgentPromptTemplate<TContext extends Record<string, unknown> = Record<string, unknown>, TAppended extends Record<string, IgniterAgentPromptTemplate<TContext, {}> | string> = {}> {
     /**
      * Builds the prompt string with the provided context.
      *
@@ -22,6 +23,18 @@ interface IgniterAgentPromptTemplate<TContext extends Record<string, unknown> =
      * @returns The built prompt string
      */
     build(context: TContext): string;
+    /**
+     * Appends another prompt template to this one.
+     */
+    addAppended<K extends string>(key: K, prompt: IgniterAgentPromptTemplate<TContext, TAppended> | string): IgniterAgentPromptTemplate<TContext, TAppended & Record<K, IgniterAgentPromptTemplate<TContext, TAppended> | string>>;
+    /**
+     * Removes an appended prompt template from this one.
+     */
+    removeAppended<K extends string>(key: K): IgniterAgentPromptTemplate<TContext, Omit<TAppended, K>>;
+    /**
+     * Returns the appended prompts.
+     */
+    getAppended(): TAppended;
     /**
      * Returns the raw prompt template.
      */
@@ -117,6 +130,29 @@ type IgniterAgentConnectionStatus = "connected" | "disconnected";
  * @public
  */
 type IgniterAgentToolsetType = "stdio" | "http" | "custom";
+/**
+ * Type alias for a single agent tool.
+ *
+ * @description
+ * Represents any tool that can be registered with the agent. Tools are functions
+ * that the AI model can invoke to perform actions or retrieve information.
+ *
+ * @see {@link https://sdk.vercel.ai/docs/ai-sdk-core/tools-and-tool-calling | Vercel AI SDK Tools}
+ *
+ * @example
+ * ```typescript
+ * const myTool: IgniterAgentTool = {
+ *   description: 'Fetches weather data for a given city',
+ *   inputSchema: z.object({ city: z.string() }),
+ *   execute: async ({ city }) => {
+ *     return await fetchWeather(city);
+ *   }
+ * };
+ * ```
+ *
+ * @public
+ */
+type IgniterAgentTool$1 = ToolSet[string];
 /**
  * Utility type that flattens nested toolsets into a single object with prefixed keys.
  *
@@ -177,7 +213,7 @@ type IgniterAgentFlattenedToolSet<TToolsets extends Record<string, IgniterAgentT
  *
  * @public
  */
-interface IgniterAgentToolset$1<TType extends IgniterAgentToolsetType = IgniterAgentToolsetType, TName extends string = string> {
+interface IgniterAgentToolset$1<TType extends IgniterAgentToolsetType = IgniterAgentToolsetType, TName extends string = string, ToolSet extends Record<string, IgniterAgentTool$1> = Record<string, IgniterAgentTool$1>> {
     /** Unique identifier for the toolset */
     readonly name: TName;
     /** Transport type used by this toolset */
@@ -223,7 +259,7 @@ interface IgniterAgentToolset$1<TType extends IgniterAgentToolsetType = IgniterA
  *
  * @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 = never> {
+interface IgniterAgentConfig<TAgentName extends string = string, TAgentModel extends LanguageModel = LanguageModel, TAgentInstructions extends IgniterAgentPromptTemplate<any, any> = IgniterAgentPromptTemplate<any, any>, TAgentToolsets extends Record<string, IgniterAgentToolset$1<any, any>> = Record<string, IgniterAgentToolset$1<any, any>>, TAgentMCPConfigs extends Record<string, IgniterAgentMCPConfigUnion> = Record<string, IgniterAgentMCPConfigUnion>, TAgentContextSchema extends z.ZodSchema = never> {
     /**
      * Unique name identifier for the agent.
      * Used for logging, debugging, and multi-agent orchestration.
@@ -543,6 +579,66 @@ interface IgniterAgentToolErrorResult {
  */
 type IgniterAgentToolResult<TData = unknown> = IgniterAgentToolSuccessResult<TData> | IgniterAgentToolErrorResult;
 
+interface IgniterAgentOutput<OUTPUT = any, PARTIAL = any> {
+    /**
+     * The response format to use for the model.
+     */
+    responseFormat: PromiseLike<any>;
+    /**
+     * Parses the complete output of the model.
+     */
+    parseCompleteOutput(options: {
+        text: string;
+    }, context: {
+        response: LanguageModelResponseMetadata;
+        usage: LanguageModelUsage;
+        finishReason: FinishReason;
+    }): Promise<OUTPUT>;
+    /**
+     * Parses the partial output of the model.
+     */
+    parsePartialOutput(options: {
+        text: string;
+    }): Promise<{
+        partial: PARTIAL;
+    } | undefined>;
+}
+type IgniterAgentToolsetParsed<ToolSet extends Record<string, IgniterAgentToolset$1>> = {
+    [toolKey in keyof ToolSet[keyof ToolSet]['tools']]: ToolSet[keyof ToolSet]['tools'][toolKey];
+};
+/**
+ * Message input for agent calls.
+ *
+ * @description
+ * Accepts either a single `message` or an array of `messages`.
+ * When both are provided, `message` takes precedence.
+ */
+type IgniterAgentMessageInput = {
+    message: ModelMessage;
+    messages?: ModelMessage[];
+} | {
+    message?: ModelMessage;
+    messages: ModelMessage[];
+};
+/**
+ * Public call options for `generate`.
+ */
+type IgniterAgentCallOptions<CALL_OPTIONS = never, ToolSet extends Record<string, IgniterAgentToolset$1> = Record<string, IgniterAgentToolset$1>, OUTPUT extends IgniterAgentOutput = never> = {
+    chatId: string;
+    userId: string;
+    context: Record<string, any>;
+} & IgniterAgentMessageInput & Omit<AgentCallParameters<CALL_OPTIONS>, "messages">;
+/**
+ * Public call options for `stream`.
+ */
+type IgniterAgentStreamCallOptions<CALL_OPTIONS = never, ToolSet extends Record<string, IgniterAgentToolset$1> = Record<string, IgniterAgentToolset$1>, OUTPUT extends IgniterAgentOutput = never> = {
+    chatId: string;
+    userId: string;
+    context: Record<string, any>;
+} & IgniterAgentMessageInput & Omit<AgentStreamParameters<CALL_OPTIONS, IgniterAgentToolsetParsed<ToolSet>>, "messages">;
+type IgniterAgentStreamOptions<CALL_OPTIONS = never, ToolSet extends Record<string, IgniterAgentToolset$1> = Record<string, IgniterAgentToolset$1>, OUTPUT extends IgniterAgentOutput = never> = IgniterAgentStreamCallOptions<CALL_OPTIONS, ToolSet, OUTPUT>;
+type IgniterAgentGenerateOptions<CALL_OPTIONS = never, ToolSet extends Record<string, IgniterAgentToolset$1> = Record<string, IgniterAgentToolset$1>, OUTPUT extends IgniterAgentOutput = never> = IgniterAgentCallOptions<CALL_OPTIONS, ToolSet, OUTPUT>;
+
 /**
  * @fileoverview Type definitions for IgniterAgent Builder pattern classes.
  * This module contains all interfaces for the fluent builder API.
@@ -682,12 +778,18 @@ type IgniterAgentMCPPartialConfig<TType extends IgniterAgentToolsetType = Ignite
  *
  * // Generate a response
  * const result = await agent.generate({
- *   messages: [{ role: 'user', content: 'Hello!' }]
+ *   chatId: 'chat_123',
+ *   userId: 'user_123',
+ *   context: { locale: 'pt' },
+ *   message: { role: 'user', content: 'Hello!' }
  * });
  *
  * // Stream a response
  * const stream = await agent.stream({
- *   messages: [{ role: 'user', content: 'Tell me a story' }]
+ *   chatId: 'chat_123',
+ *   userId: 'user_123',
+ *   context: { locale: 'pt' },
+ *   message: { role: 'user', content: 'Tell me a story' }
  * });
  * ```
  *
@@ -735,41 +837,44 @@ interface IgniterAgentBuiltAgent<TContextSchema extends z.ZodSchema = never, TTo
      * Generates a single response from the agent.
      *
      * @description
-     * Sends messages to the agent and waits for a complete response.
+     * Sends a message (or messages) to the agent and waits for a complete response.
+     * When both are provided, `message` takes precedence.
      * Supports context options for dynamic prompt generation.
      *
-     * @param input - The call parameters including messages and options
+     * @param input - The call parameters including `chatId`, `userId`, `context`, and message or messages
      * @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' }
+     *   chatId: 'chat_123',
+     *   userId: 'user_123',
+     *   context: { locale: 'pt' },
+     *   message: { role: 'user', content: 'What is TypeScript?' }
      * });
      *
      * console.log('Response:', result.text);
      * ```
      */
-    generate(input: AgentCallParameters<z.infer<TContextSchema>>): Promise<GenerateTextResult<any, any>>;
+    generate<CALL_OPTIONS = never, OUTPUT extends IgniterAgentOutput = never>(params: IgniterAgentGenerateOptions<CALL_OPTIONS, TToolsets, OUTPUT>): Promise<GenerateTextResult<IgniterAgentToolsetParsed<TToolsets>, OUTPUT>>;
     /**
      * Streams a response from the agent.
      *
      * @description
-     * Sends messages to the agent and returns a stream of response chunks.
+     * Sends a message (or messages) to the agent and returns a stream of response chunks.
+     * When both are provided, `message` takes precedence.
      * Ideal for real-time UI updates and long responses.
      *
-     * @param input - The stream parameters including messages and options
+     * @param input - The stream parameters including `chatId`, `userId`, `context`, and message or messages
      * @returns A stream of response chunks
      *
      * @example
      * ```typescript
      * const stream = await agent.stream({
-     *   messages: [
-     *     { role: 'user', content: 'Write a poem about coding' }
-     *   ]
+     *   chatId: 'chat_123',
+     *   userId: 'user_123',
+     *   context: { locale: 'pt' },
+     *   message: { role: 'user', content: 'Write a poem about coding' }
      * });
      *
      * for await (const chunk of stream) {
@@ -777,7 +882,7 @@ interface IgniterAgentBuiltAgent<TContextSchema extends z.ZodSchema = never, TTo
      * }
      * ```
      */
-    stream(input: AgentStreamParameters<TContextSchema, any>): Promise<StreamTextResult<any, any>>;
+    stream<CALL_OPTIONS = never, OUTPUT extends IgniterAgentOutput = never>(params: IgniterAgentStreamOptions<CALL_OPTIONS, TToolsets, OUTPUT>): Promise<StreamTextResult<IgniterAgentToolsetParsed<TToolsets>, OUTPUT>>;
     /**
      * Gets all registered toolsets.
      *
@@ -901,6 +1006,96 @@ interface IgniterAgentToolDefinition<TInputSchema = unknown, TOutputSchema = unk
     execute: (params: TInputSchema, options?: IgniterAgentToolExecuteOptions) => TOutputSchema | Promise<TOutputSchema>;
 }
 
+/**
+ * Context types for AI SDK's experimental_context integration.
+ *
+ * @module @igniter-js/agents/types/context
+ */
+
+/**
+ * Core execution context that flows through tools via AI SDK.
+ *
+ * This merges your custom context with required system fields.
+ * Your context fields are available at the top level alongside writer and metadata.
+ *
+ * @template TContext - Your custom context type (must be an object)
+ *
+ * @example Basic usage
+ * ```typescript
+ * // Define your context type
+ * interface MyAppContext {
+ *   userId: string;
+ *   db: Database;
+ * }
+ *
+ * // Access in tools
+ * const ctx: IgniterAgentExecutionContext<MyAppContext> = {
+ *   userId: '123',
+ *   db: database,
+ *   writer: streamWriter,
+ *   metadata: { agent: 'my-agent' }
+ * };
+ * ```
+ */
+type IgniterAgentExecutionContext<TContext extends Record<string, unknown> = Record<string, unknown>> = TContext & {
+    /** Stream writer for real-time updates and artifacts */
+    writer: UIMessageStreamWriter;
+    /** Metadata about the current execution */
+    metadata?: IgniterAgentExecutionContextMetadata;
+    /** Memory configuration for persistent context */
+    memory?: IgniterAgentMemoryConfig;
+};
+/**
+ * Metadata about the current agent execution.
+ *
+ * @example
+ * ```typescript
+ * const metadata: IgniterAgentExecutionContextMetadata = {
+ *   agent: 'reports-agent',
+ *   requestId: 'req_123',
+ *   startTime: new Date()
+ * };
+ * ```
+ */
+interface IgniterAgentExecutionContextMetadata {
+    /** Current agent name */
+    agent?: string;
+    /** Execution start time */
+    startTime?: Date;
+    /** Request ID for tracing */
+    requestId?: string;
+    /** Chat ID for memory scope */
+    chatId?: string;
+    /** User ID for memory scope */
+    userId?: string;
+    /** Any custom metadata */
+    [key: string]: unknown;
+}
+/**
+ * Type-safe context creator options.
+ *
+ * @template TContext - Your custom context type (must be an object)
+ *
+ * @example
+ * ```typescript
+ * const options: IgniterAgentContextOptions<MyAppContext> = {
+ *   context: { userId: '123', db: database },
+ *   writer: streamWriter,
+ *   metadata: { agent: 'reports' }
+ * };
+ * ```
+ */
+interface IgniterAgentContextOptions<TContext extends Record<string, unknown> = Record<string, unknown>> {
+    /** Your custom application context - spread at the top level */
+    context?: TContext;
+    /** Stream writer (required in streaming mode) */
+    writer?: UIMessageStreamWriter;
+    /** Memory configuration for persistent context */
+    memory?: IgniterAgentMemoryConfig;
+    /** Metadata for tracing and scope */
+    metadata: IgniterAgentExecutionContextMetadata;
+}
+
 /**
  * Status of an agent in the manager.
  *
@@ -1020,7 +1215,12 @@ type KeysOfType<T, V> = {
  *
  * // Route to specific agent
  * const agent = manager.get('support');
- * const response = await agent.generate({ messages: [...] });
+ * const response = await agent.generate({
+ *   chatId: 'chat_123',
+ *   userId: 'user_123',
+ *   context: {},
+ *   message: { role: 'user', content: 'Hello!' }
+ * });
  * ```
  *
  * @module core/manager
@@ -1070,7 +1270,10 @@ type KeysOfType<T, V> = {
  * // Use specific agent
  * const agent = manager.get('code');
  * const result = await agent.generate({
- *   messages: [{ role: 'user', content: 'Write a test' }]
+ *   chatId: 'chat_123',
+ *   userId: 'user_123',
+ *   context: {},
+ *   message: { role: 'user', content: 'Write a test' }
  * });
  *
  * // Get status
@@ -1206,7 +1409,12 @@ declare class IgniterAgentManagerCore<TAgentRegistry extends Record<string, Igni
      * @example
      * ```typescript
      * const agent = manager.get('support');
-     * const response = await agent.generate({ messages: [...] });
+     * const response = await agent.generate({
+     *   chatId: 'chat_123',
+     *   userId: 'user_123',
+     *   context: {},
+     *   message: { role: 'user', content: 'Hello!' }
+     * });
      * ```
      */
     get<TName extends string>(name: TName): TAgentRegistry[TName];
@@ -1297,7 +1505,7 @@ declare class IgniterAgentMemoryCore implements IgniterAgentMemoryRuntime {
     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> {
+declare class IgniterAgentCore<TAgentName extends string = string, TAgentModel extends LanguageModel = LanguageModel, TAgentInstructions extends IgniterAgentPromptTemplate = IgniterAgentPromptTemplate, TAgentToolsets extends Record<string, IgniterAgentToolset$1<any, any>> = Record<string, IgniterAgentToolset$1<any, any>>, TAgentMCPConfigs extends Record<string, IgniterAgentMCPConfigUnion> = Record<string, IgniterAgentMCPConfigUnion>, TAgentContextSchema extends z.ZodSchema = z.ZodSchema> {
     private _agent;
     private logger?;
     private telemetry?;
@@ -1329,13 +1537,27 @@ declare class IgniterAgentCore<TAgentName extends string = string, TAgentModel e
      */
     stop(): Promise<void>;
     /**
-     * Generates a response from the agent.
+     * Generates a response for the given message or messages.
+     *
+     * @description
+     * Accepts either a single `message` or an array of `messages`.
+     * When both are provided, `message` takes precedence.
+     *
+     * @param params - The parameters for the generate call.
+     * @returns The generated response.
      */
-    generate(input: AgentCallParameters<any>): Promise<any>;
+    generate<CALL_OPTIONS = never, OUTPUT extends IgniterAgentOutput = never>(params: IgniterAgentGenerateOptions<CALL_OPTIONS, TAgentToolsets, OUTPUT>): Promise<ai.GenerateTextResult<IgniterAgentToolsetParsed<TAgentToolsets>, IgniterAgentOutput<any, any>>>;
     /**
-     * Streams a response from the agent.
+     * Streams a response for the given message or messages.
+     *
+     * @description
+     * Accepts either a single `message` or an array of `messages`.
+     * When both are provided, `message` takes precedence.
+     *
+     * @param params - The parameters for the stream call.
+     * @returns The streaming response.
      */
-    stream(input: AgentStreamParameters<any, any>): Promise<any>;
+    stream<CALL_OPTIONS = never, OUTPUT extends IgniterAgentOutput = never>(params: IgniterAgentStreamOptions<CALL_OPTIONS, TAgentToolsets, OUTPUT>): Promise<ai.StreamTextResult<IgniterAgentToolsetParsed<TAgentToolsets>, IgniterAgentOutput<any, any>>>;
     /**
      * Gets all registered toolsets.
      */
@@ -1356,10 +1578,17 @@ declare class IgniterAgentCore<TAgentName extends string = string, TAgentModel e
      * Gets all registered tools from all toolsets.
      */
     getTools(): ToolSet;
-    private wrapToolExecution;
-    private wrapStreamResult;
+    /**
+     * Gets error attributes for telemetry.
+     */
     private getErrorAttributes;
-    private getAgentInstanceWithContext;
+    /**
+     * Gets an agent instance with the given context.
+     */
+    private prepare;
+    private initializeChatMemory;
+    private resolveMessageInput;
+    private initializeTools;
     private initializeMCPClient;
 }
 
@@ -1450,8 +1679,10 @@ type IgniterAgentManager = typeof IgniterAgentManagerBuilder;
  *
  * // Generate a response
  * const result = await agent.generate({
- *   messages: [{ role: 'user', content: 'Hello!' }],
- *   options: { userId: 'user_123', chatId: 'chat_456' }
+ *   chatId: 'chat_456',
+ *   userId: 'user_123',
+ *   context: { locale: 'pt' },
+ *   message: { role: 'user', content: 'Hello!' }
  * });
  * ```
  *
@@ -1542,14 +1773,16 @@ type IgniterAgentManager = typeof IgniterAgentManagerBuilder;
  * await agent.start();
  *
  * const response = await agent.generate({
- *   messages: [{ role: 'user', content: 'Help me write a test' }],
- *   options: { userId: 'user_123', projectId: 'proj_456' }
+ *   chatId: 'chat_456',
+ *   userId: 'user_123',
+ *   context: { projectId: 'proj_456' },
+ *   message: { role: 'user', content: 'Help me write a test' }
  * });
  * ```
  *
  * @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> {
+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 = never> {
     /**
      * The agent configuration being built.
      * @internal
@@ -1719,13 +1952,13 @@ declare class IgniterAgentBuilder<TAgentName extends string = string, TAgentMode
      *
      * // Context is type-safe when calling generate
      * await agent.generate({
-     *   messages: [...],
-     *   options: {
-     *     userId: 'user_123',
-     *     chatId: 'chat_456',
+     *   chatId: 'chat_456',
+     *   userId: 'user_123',
+     *   context: {
      *     userRole: 'admin',
      *     preferences: { language: 'pt' }
-     *   }
+     *   },
+     *   message: { role: 'user', content: 'Hello!' }
      * });
      * ```
      *
@@ -1835,7 +2068,10 @@ declare class IgniterAgentBuilder<TAgentName extends string = string, TAgentMode
      *
      * // Generate a response
      * const result = await agent.generate({
-     *   messages: [{ role: 'user', content: 'Hello!' }]
+     *   chatId: 'chat_123',
+     *   userId: 'user_123',
+     *   context: {},
+     *   message: { role: 'user', content: 'Hello!' }
      * });
      *
      * // Access configuration
@@ -2724,8 +2960,9 @@ declare const IgniterAgentMCPClient: {
  *
  * @public
  */
-declare class IgniterAgentPromptBuilder<TTemplate extends string = string, TContext extends Record<string, unknown> = Record<string, unknown>> implements IgniterAgentPromptTemplate<TContext> {
+declare class IgniterAgentPromptBuilder<TTemplate extends string = string, TContext extends Record<string, unknown> = Record<string, unknown>, TAppended extends Record<string, IgniterAgentPromptTemplate<TContext, {}> | string> = {}> implements IgniterAgentPromptTemplate<TContext, TAppended> {
     private readonly template;
+    private readonly appended;
     private constructor();
     /**
      * Creates a new prompt builder.
@@ -2733,7 +2970,7 @@ declare class IgniterAgentPromptBuilder<TTemplate extends string = string, TCont
      * @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>>;
+    static create<TNewTemplate extends string>(template: TNewTemplate, appended?: Record<string, IgniterAgentPromptTemplate<{}, {}> | string>): IgniterAgentPromptBuilder<TNewTemplate, Record<string, unknown>>;
     /**
      * Builds the prompt string with the provided context.
      *
@@ -2741,6 +2978,18 @@ declare class IgniterAgentPromptBuilder<TTemplate extends string = string, TCont
      * @returns The resolved prompt string
      */
     build(context: TContext): string;
+    /**
+     * Appends another prompt template to this one.
+     */
+    addAppended<K extends string>(key: K, prompt: IgniterAgentPromptTemplate<TContext, TAppended> | string): IgniterAgentPromptTemplate<TContext, TAppended & Record<K, IgniterAgentPromptTemplate<TContext, TAppended> | string>>;
+    /**
+     * Removes an appended prompt template from this one.
+     */
+    removeAppended<K extends string>(key: K): IgniterAgentPromptTemplate<TContext, Omit<TAppended, K>>;
+    /**
+     * Returns the appended prompts.
+     */
+    getAppended(): TAppended;
     /**
      * Returns the raw prompt template string.
      */
@@ -2765,7 +3014,7 @@ type IgniterAgentPrompt = typeof IgniterAgentPromptBuilder;
  *
  * @description
  * The error system in IgniterAgent follows these principles:
- * - All errors extend IgniterError from @igniter-js/core for consistency
+ * - All errors extend IgniterError from @igniter-js/common for consistency
  * - Errors include rich context for debugging
  * - Error codes enable programmatic error handling
  * - Stack traces are preserved for debugging
@@ -2776,11 +3025,16 @@ type IgniterAgentPrompt = typeof IgniterAgentPromptBuilder;
  *   IgniterAgentError,
  *   IgniterAgentMCPError,
  *   IgniterAgentToolError,
- *   isIgniterAgentError
- * } from '@igniter-js/agents';
+ *   isIgniterAgentError,
+ * } from "@igniter-js/agents";
  *
  * try {
- *   await agent.generate({ messages: [] });
+ *   await agent.generate({
+ *     chatId: 'chat_123',
+ *     userId: 'user_123',
+ *     context: {},
+ *     messages: []
+ *   });
  * } catch (error) {
  *   if (isIgniterAgentError(error)) {
  *     console.error(`[${error.code}] ${error.message}`);
@@ -2879,7 +3133,7 @@ interface IgniterAgentErrorOptions {
  *
  * @description
  * All custom errors in the IgniterAgent library extend this class,
- * which itself extends IgniterError from @igniter-js/core.
+ * which itself extends IgniterError from @igniter-js/common.
  * It provides a consistent interface for error handling, including
  * error codes, context, and cause tracking.
  *
@@ -3041,7 +3295,12 @@ declare class IgniterAgentAdapterError extends IgniterAgentError {
  * @example
  * ```typescript
  * try {
- *   await agent.generate({ messages: [] });
+ *   await agent.generate({
+ *     chatId: 'chat_123',
+ *     userId: 'user_123',
+ *     context: {},
+ *     messages: []
+ *   });
  * } catch (error) {
  *   if (isIgniterAgentError(error)) {
  *     // TypeScript knows error is IgniterAgentError
@@ -3172,4 +3431,138 @@ declare class IgniterAgentValidationUtils {
     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 };
+/**
+ * Context Management using AI SDK's experimental_context
+ *
+ * This provides type-safe context that flows through tools via AI SDK's
+ * built-in experimental_context parameter.
+ *
+ * Key features:
+ * - Uses AI SDK's official context mechanism
+ * - Fully flexible user context - pass ANY type you want (object, string, class instance, etc.)
+ * - Stream writer for artifacts and real-time updates
+ * - Type-safe with full TypeScript support
+ * - Available in all tools via executionOptions.experimental_context
+ *
+ * @module @igniter-js/agents/utils/context
+ */
+
+/**
+ * Static utility class for managing Agent execution context.
+ *
+ * Provides methods to create and extract type-safe context that flows
+ * through tools via AI SDK's experimental_context parameter.
+ *
+ * @example Creating context
+ * ```typescript
+ * const context = IgniterAgentContext.create({
+ *   context: { userId: '123', db: database },
+ *   writer: streamWriter
+ * });
+ * ```
+ *
+ * @example Extracting context in tools
+ * ```typescript
+ * export const myTool = tool({
+ *   execute: async (params, executionOptions) => {
+ *     const ctx = IgniterAgentContext.get<MyContext>(executionOptions);
+ *     const user = await ctx?.db.users.findOne(ctx.userId);
+ *   }
+ * });
+ * ```
+ */
+declare class IgniterAgentContext {
+    /**
+     * Private constructor to prevent instantiation.
+     * This is a static-only utility class.
+     */
+    private constructor();
+    /**
+     * Creates an execution context to pass to AI SDK's experimental_context.
+     *
+     * Your context object is spread at the top level, merged with writer and metadata.
+     * This means you can access your fields directly without a wrapper.
+     *
+     * @template TContext - Your custom context type (must be an object)
+     * @param options - The context creation options
+     * @returns The merged execution context ready for AI SDK
+     *
+     * @example Basic usage
+     * ```typescript
+     * const context = IgniterAgentContext.create({
+     *   context: { userId: '123', db: database, permissions: ['read', 'write'] },
+     *   writer: streamWriter
+     * });
+     * // Access in tools: executionOptions.experimental_context.userId
+     * ```
+     *
+     * @example With typed context
+     * ```typescript
+     * interface MyAppContext {
+     *   tenant: string;
+     *   workspace: string;
+     *   features: string[];
+     * }
+     *
+     * const context = IgniterAgentContext.create<MyAppContext>({
+     *   context: { tenant: 'acme', workspace: 'main', features: ['analytics'] },
+     *   writer: streamWriter
+     * });
+     * // Access in tools: executionOptions.experimental_context.tenant
+     * ```
+     *
+     * @example With metadata for tracing
+     * ```typescript
+     * const context = IgniterAgentContext.create({
+     *   context: { userId: '123', tenantId: 'acme' },
+     *   writer: streamWriter,
+     *   metadata: { agent: 'reports', requestId: 'req_123' }
+     * });
+     * ```
+     */
+    static create<TContext extends Record<string, unknown> = Record<string, unknown>>(options: IgniterAgentContextOptions<TContext>): IgniterAgentExecutionContext<TContext>;
+    /**
+     * Gets your custom context from execution options.
+     *
+     * Your context fields are available directly in experimental_context (no wrapper).
+     * This helper provides type-safe access.
+     *
+     * @template T - Your custom context type (object)
+     * @param executionOptions - Tool execution options from AI SDK
+     * @returns Your custom context or undefined if not available
+     *
+     * @example Direct access (no helper needed)
+     * ```typescript
+     * export const myTool = tool({
+     *   execute: async (params, executionOptions) => {
+     *     // Access fields directly
+     *     const userId = executionOptions.experimental_context.userId;
+     *     const db = executionOptions.experimental_context.db;
+     *   }
+     * });
+     * ```
+     *
+     * @example With typed helper
+     * ```typescript
+     * interface AppContext {
+     *   userId: string;
+     *   tenantId: string;
+     *   db: Database;
+     * }
+     *
+     * export const myTool = tool({
+     *   execute: async (params, executionOptions) => {
+     *     const ctx = IgniterAgentContext.get<AppContext>(executionOptions);
+     *     if (ctx) {
+     *       const user = await ctx.db.users.findOne(ctx.userId);
+     *     }
+     *   }
+     * });
+     * ```
+     */
+    static get<T extends Record<string, unknown> = Record<string, unknown>>(executionOptions?: {
+        experimental_context?: T;
+    }): T | undefined;
+}
+
+export { type DeepPartial, type DeepRequired, IgniterAgent, IgniterAgentAdapterError, IgniterAgentAsyncUtils, IgniterAgentBuilder, type IgniterAgentBuiltAgent, type IgniterAgentBuiltTool, type IgniterAgentBuiltToolset, IgniterAgentChatSession, type IgniterAgentConfig, IgniterAgentConfigError, type IgniterAgentConnectionStatus, IgniterAgentContext, type IgniterAgentContextOptions, IgniterAgentConversationMessage, IgniterAgentCore, IgniterAgentError, IgniterAgentErrorCode, type IgniterAgentErrorOptions, type IgniterAgentExecutionContext, type IgniterAgentExecutionContextMetadata, 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 };