@aigne/core 1.73.0-beta → 1.74.0-beta

package/lib/dts/agents/ai-agent.d.ts

@@ -1,395 +0,0 @@
-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>;
-}