import { type ZodObject, type ZodType, z } from "zod";
import { type NestAgentSchema } from "../loader/agent-yaml.js";
import type { AgentLoadOptions } from "../loader/index.js";
import { type Instructions } from "../loader/schema.js";
import type { CompactConfig, SessionMemoryConfig, UserMemoryConfig } from "../prompt/agent-session.js";
import { PromptBuilder } from "../prompt/prompt-builder.js";
import { Agent, type AgentInvokeOptions, type AgentOptions, type AgentProcessAsyncGenerator, type AgentProcessResult, type Message } from "./agent.js";
import type { ChatModel, ChatModelInput } from "./chat-model.js";
import type { GuideRailAgentOutput } from "./guide-rail-agent.js";
import { type FileType } from "./model.js";
export declare const DEFAULT_OUTPUT_KEY = "message";
export declare const DEFAULT_OUTPUT_FILE_KEY = "files";
/**
 * Configuration options for an AI Agent
 *
 * These options extend the base agent options with AI-specific parameters
 * like model configuration, prompt instructions, and tool choice.
 *
 * @template I The input message type the agent accepts
 * @template O The output message type the agent returns
 */
export interface AIAgentOptions<I extends Message = Message, O extends Message = Message> extends AgentOptions<I, O> {
    /**
     * Instructions to guide the AI model's behavior
     *
     * Can be a simple string or a full PromptBuilder instance for
     * more complex prompt templates
     */
    instructions?: string | PromptBuilder;
    /**
     * Pick a message from input to use as the user's message
     */
    inputKey?: string;
    inputFileKey?: string;
    /**
     * Custom key to use for text output in the response
     *
     * Defaults to `message` if not specified
     */
    outputKey?: string;
    outputFileKey?: string;
    outputFileType?: FileType;
    /**
     * Controls how the agent uses tools during execution
     *
     * @default AIAgentToolChoice.auto
     */
    toolChoice?: AIAgentToolChoice | Agent;
    /**
     * Maximum number of tool calls to execute concurrently
     *
     * @default 1
     */
    toolCallsConcurrency?: number;
    /**
     * Whether to preserve text generated during tool usage in the final output
     */
    keepTextInToolUses?: boolean;
    /**
     * Whether to catch errors from tool execution and continue processing.
     * If set to false, the agent will throw an error if a tool fails.
     *
     * @default true
     */
    catchToolsError?: boolean;
    /**
     * Whether to enable structured stream mode
     *
     * When enabled, the AI model's streaming response will be processed to extract
     * structured metadata. The model needs to include specific format metadata tags
     * (like <metadata></metadata>) in its response, which will be parsed as JSON
     * objects and passed through the stream.
     *
     * This is useful for scenarios that need to extract structured information
     * (like classifications, scores, tags, etc.) from AI responses.
     *
     * @default false
     */
    structuredStreamMode?: boolean;
    ignoreTextOfStructuredStreamMode?: (output: O) => boolean;
    /**
     * Custom structured stream instructions configuration
     *
     * Allows customization of structured stream mode behavior, including:
     * - instructions: Prompt instructions to guide the AI model on how to output structured data
     * - metadataStart: Metadata start marker (e.g., "<metadata>")
     * - metadataEnd: Metadata end marker (e.g., "</metadata>")
     * - parse: Function to parse metadata content, converting raw string to object
     *
     * If not provided, the default STRUCTURED_STREAM_INSTRUCTIONS configuration will be used,
     * which outputs structured data in YAML format within <metadata> tags.
     *
     * @example
     * ```typescript
     * {
     *   instructions: "Output metadata in JSON format at the end of response in markdown code block with json language",
     *   metadataStart: "```json",
     *   metadataEnd: "```",
     *   parse: JSON.parse
     * }
     * ```
     */
    customStructuredStreamInstructions?: {
        instructions: string | PromptBuilder;
        metadataStart: string;
        metadataEnd: string;
        parse: (raw: string) => object;
    };
    /**
     * Whether to include memory agents as tools for the AI model
     *
     * When set to true, memory agents will be made available as tools
     * that the model can call directly to retrieve or store information.
     * This enables the agent to explicitly interact with its memories.
     *
     * @default false
     */
    memoryAgentsAsTools?: boolean;
    /**
     * Custom prompt template for formatting memory content
     *
     * Allows customization of how memories are presented to the AI model.
     * If not provided, the default template from MEMORY_MESSAGE_TEMPLATE will be used.
     *
     * The template receives a {{memories}} variable containing serialized memory content.
     */
    memoryPromptTemplate?: string;
    useMemoriesFromContext?: boolean;
    /**
     * Agent session configuration
     *
     * Controls history recording, memory extraction, and conversation compaction.
     * By default, mode is "auto" (enabled). Set `{ mode: "disabled" }` to disable
     * for internal utility agents (extractors, compactors, etc.).
     *
     * @example
     * ```typescript
     * // Default behavior - session features enabled
     * new AIAgent({
     *   session: {
     *     compact: { mode: "auto" },
     *     sessionMemory: { mode: "auto" },
     *     userMemory: { mode: "auto" }
     *   }
     * })
     *
     * // Disable for internal utility agents
     * new AIAgent({
     *   session: { mode: "disabled" }
     * })
     * ```
     */
    session?: Partial<Omit<import("../prompt/agent-session.js").AgentSessionOptions, "sessionId" | "userId" | "agentId" | "afs">>;
}
export interface AIAgentLoadSchema {
    instructions?: Instructions;
    inputKey?: string;
    inputFileKey?: string;
    outputKey?: string;
    outputFileKey?: string;
    toolChoice?: AIAgentToolChoice;
    toolCallsConcurrency?: number;
    keepTextInToolUses?: boolean;
    session?: {
        mode?: "auto" | "disabled";
        compact?: Omit<CompactConfig, "compactor"> & {
            compactor?: NestAgentSchema;
        };
        sessionMemory?: Omit<SessionMemoryConfig, "extractor"> & {
            extractor?: NestAgentSchema;
        };
        userMemory?: Omit<UserMemoryConfig, "extractor"> & {
            extractor?: NestAgentSchema;
        };
    };
}
/**
 * Tool choice options for AI agents
 *
 * Controls how the agent decides to use tools during execution
 */
export declare enum AIAgentToolChoice {
    /**
     * Let the model decide when to use tools
     */
    auto = "auto",
    /**
     * Disable tool usage
     */
    none = "none",
    /**
     * Force tool usage
     */
    required = "required",
    /**
     * Choose exactly one tool and route directly to it
     */
    router = "router"
}
/**
 * Zod schema for validating AIAgentToolChoice values
 *
 * Used to ensure that toolChoice receives valid values
 *
 * @hidden
 */
export declare const aiAgentToolChoiceSchema: z.ZodUnion<[z.ZodNativeEnum<typeof AIAgentToolChoice>, ZodType<Agent<any, any>, z.ZodTypeDef, Agent<any, any>>]>;
/**
 * Zod schema for validating AIAgentOptions
 *
 * Extends the base agent options schema with AI-specific parameters
 *
 * @hidden
 */
export declare const aiAgentOptionsSchema: ZodObject<{
    [key in keyof AIAgentOptions]: ZodType<AIAgentOptions[key]>;
}>;
/**
 * AI-powered agent that leverages language models
 *
 * AIAgent connects to language models to process inputs and generate responses,
 * with support for streaming, function calling, and tool usage.
 *
 * Key features:
 * - Connect to any language model
 * - Use customizable instructions and prompts
 * - Execute tools/function calls
 * - Support streaming responses
 * - Router mode for specialized agents
 *
 * @template I The input message type the agent accepts
 * @template O The output message type the agent returns
 *
 * @example
 * Basic AIAgent creation:
 * {@includeCode ../../test/agents/ai-agent.test.ts#example-ai-agent-basic}
 */
export declare class AIAgent<I extends Message = any, O extends Message = any> extends Agent<I, O> {
    tag: string;
    static schema<T>({ filepath }: {
        filepath: string;
    }): ZodType<T>;
    static load<I extends Message = any, O extends Message = any>(options: {
        filepath: string;
        parsed: object;
        options?: AgentLoadOptions;
    }): Promise<Agent<I, O>>;
    /**
     * Create an AIAgent with the specified options
     *
     * Factory method that provides a convenient way to create new AI agents
     *
     * @param options Configuration options for the AI agent
     * @returns A new AIAgent instance
     *
     * @example
     * AI agent with custom instructions:
     * {@includeCode ../../test/agents/ai-agent.test.ts#example-ai-agent-instructions}
     */
    static from<I extends Message, O extends Message>(options: AIAgentOptions<I, O>): AIAgent<I, O>;
    /**
     * Create an AIAgent instance
     *
     * @param options Configuration options for the AI agent
     */
    constructor(options: AIAgentOptions<I, O>);
    /**
     * Instructions for the language model
     *
     * Contains system messages, user templates, and other prompt elements
     * that guide the model's behavior
     *
     * @example
     * Custom prompt builder:
     * {@includeCode ../../test/agents/ai-agent.test.ts#example-ai-agent-prompt-builder}
     */
    instructions: PromptBuilder;
    /**
     * Pick a message from input to use as the user's message
     */
    inputKey?: string;
    inputFileKey?: string;
    /**
     * Custom key to use for text output in the response
     *
     * @example
     * Setting a custom output key:
     * {@includeCode ../../test/agents/ai-agent.test.ts#example-ai-agent-custom-output-key}
     */
    outputKey: string;
    outputFileKey: string;
    outputFileType?: FileType;
    /**
     * Controls how the agent uses tools during execution
     *
     * @example
     * Automatic tool choice:
     * {@includeCode ../../test/agents/ai-agent.test.ts#example-ai-agent-tool-choice-auto}
     *
     * @example
     * Router tool choice:
     * {@includeCode ../../test/agents/ai-agent.test.ts#example-ai-agent-router}
     */
    toolChoice?: AIAgentToolChoice | Agent;
    /**
     * Maximum number of tool calls to execute concurrently
     *
     * @default 1
     */
    toolCallsConcurrency?: number;
    /**
     * Whether to preserve text generated during tool usage in the final output
     */
    keepTextInToolUses?: boolean;
    /**
     * Whether to include memory agents as tools for the AI model
     *
     * When set to true, memory agents will be made available as tools
     * that the model can call directly to retrieve or store information.
     * This enables the agent to explicitly interact with its memories.
     */
    memoryAgentsAsTools?: boolean;
    /**
     * Custom prompt template for formatting memory content
     *
     * Allows customization of how memories are presented to the AI model.
     * If not provided, the default template from MEMORY_MESSAGE_TEMPLATE will be used.
     *
     * The template receives a {{memories}} variable containing serialized memory content.
     */
    memoryPromptTemplate?: string;
    useMemoriesFromContext?: boolean;
    /**
     * Whether to catch error from tool execution and continue processing.
     * If set to false, the agent will throw an error if a tool fails
     *
     * @default true
     */
    catchToolsError: boolean;
    /**
     * Whether to enable structured stream mode
     *
     * When enabled, the AI model's streaming response will be processed to extract
     * structured metadata. The model needs to include specific format metadata tags
     * (like <metadata></metadata>) in its response, which will be parsed as JSON
     * objects and passed through the stream.
     *
     * This is useful for scenarios that need to extract structured information
     * (like classifications, scores, tags, etc.) from AI responses.
     *
     * @default false
     */
    structuredStreamMode?: boolean;
    ignoreTextOfStructuredStreamMode?: (output: O) => boolean;
    /**
     * Custom structured stream instructions configuration
     *
     * Allows customization of structured stream mode behavior, including:
     * - instructions: Prompt instructions to guide the AI model on how to output structured data
     * - metadataStart: Metadata start marker (e.g., "<metadata>")
     * - metadataEnd: Metadata end marker (e.g., "</metadata>")
     * - parse: Function to parse metadata content, converting raw string to object
     *
     * If not provided, the default STRUCTURED_STREAM_INSTRUCTIONS configuration will be used,
     * which outputs structured data in YAML format within <metadata> tags.
     */
    customStructuredStreamInstructions?: {
        instructions: PromptBuilder;
        metadataStart: string;
        metadataEnd: string;
        parse: (raw: string) => object;
    };
    /**
     * Agent session configuration
     */
    session?: Partial<Omit<import("../prompt/agent-session.js").AgentSessionOptions, "sessionId" | "userId" | "agentId" | "afs">>;
    get inputSchema(): ZodType<I>;
    /**
     * Process an input message and generate a response
     *
     * @protected
     */
    process(input: I, options: AgentInvokeOptions): AgentProcessResult<O>;
    private _process;
    protected onGuideRailError(error: GuideRailAgentOutput): Promise<O | GuideRailAgentOutput>;
    /**
     * Process router mode requests
     *
     * In router mode, the agent sends a single request to the model to determine
     * which tool to use, then routes the request directly to that tool
     *
     * @protected
     */
    _processRouter(input: I, model: ChatModel, modelInput: ChatModelInput, options: AgentInvokeOptions, toolsMap: Map<string, Agent>): AgentProcessAsyncGenerator<O>;
}