@dpml/agent/dist/index.d.ts

Agent implementation for DPML

import * as _dpml_core from '@dpml/core';

/**
 * 内容类型
 */
type ContentType = 'text' | 'image' | 'audio' | 'video' | 'file';
/**
 * 内容项
 *
 * 表示多模态内容的统一接口。
 */
interface ContentItem {
    /**
     * 内容类型
     */
    readonly type: ContentType;
    /**
     * 内容值，根据类型有不同的表示
     */
    readonly value: string | Uint8Array | Record<string, never>;
    /**
     * MIME类型，可选
     */
    readonly mimeType?: string;
}
/**
 * 内容
 *
 * 表示单个内容项或内容项数组，提供灵活的内容表示方式。
 */
type Content = ContentItem | ContentItem[];

/**
 * 聊天输入
 *
 * 包含发送给Agent的输入内容，支持多模态。
 */
interface ChatInput {
    /**
     * 内容，支持单个内容项或内容项数组
     */
    readonly content: Content;
}
/**
 * 聊天输出
 *
 * 包含Agent的响应内容，支持多模态。
 */
interface ChatOutput {
    /**
     * 内容，支持单个内容项或内容项数组
     */
    readonly content: Content;
}

/**
 * Agent接口
 *
 * 定义AI对话代理的标准交互方法。
 */
interface Agent {
    /**
     * 发送消息并获取文本响应
     * @param input 文本消息或ChatInput对象
     * @returns 文本响应
     */
    chat(input: string | ChatInput): Promise<string>;
    /**
     * 发送消息并获取流式响应
     * @param input 文本消息或ChatInput对象
     * @returns 文本块的异步迭代器
     */
    chatStream(input: string | ChatInput): AsyncIterable<string>;
}

/**
 * LLM配置
 *
 * 定义连接LLM服务所需的配置信息。
 */
interface LLMConfig {
    /**
     * API提供商类型，如"openai"、"anthropic"等
     */
    readonly apiType: string;
    /**
     * API端点URL，可选
     */
    readonly apiUrl?: string;
    /**
     * API密钥
     */
    readonly apiKey?: string;
    /**
     * 使用的模型名称
     */
    readonly model: string;
}

/**
 * Agent配置
 *
 * 定义创建Agent所需的配置信息。
 */
interface AgentConfig {
    /**
     * LLM配置信息
     */
    readonly llm: LLMConfig;
    /**
     * 系统提示词，定义Agent的行为和能力
     */
    readonly prompt: string;
}

/**
 * Agent错误类型
 */
declare enum AgentErrorType {
    /**
     * 配置错误
     */
    CONFIG = "CONFIG",
    /**
     * LLM服务调用错误
     */
    LLM_SERVICE = "LLM_SERVICE",
    /**
     * 内容处理错误
     */
    CONTENT = "CONTENT",
    /**
     * 会话错误
     */
    SESSION = "SESSION",
    /**
     * 未知错误
     */
    UNKNOWN = "UNKNOWN"
}
/**
 * Agent错误
 *
 * 统一的错误类，用于处理Agent模块中的所有错误。
 */
declare class AgentError extends Error {
    /**
     * 错误类型
     */
    readonly type: AgentErrorType;
    /**
     * 错误码
     */
    readonly code: string;
    /**
     * 原始错误
     */
    readonly cause?: Error;
    /**
     * 创建Agent错误
     *
     * @param message 错误消息
     * @param type 错误类型
     * @param code 错误码
     * @param cause 原始错误
     */
    constructor(message: string, type?: AgentErrorType, code?: string, cause?: Error);
}

/**
 * 创建Agent实例
 *
 * 基于提供的配置创建一个符合Agent接口的实例，用于与LLM交互。
 * 使用闭包模式封装内部状态，提供简洁的交互接口。
 *
 * @param config Agent配置信息
 * @returns 符合Agent接口的实例
 */
declare function createAgent(config: AgentConfig): Agent;

/**
 * 创建Agent领域DPML实例
 *
 * 集成Schema、转换器和CLI配置，
 * 提供编译和命令行功能。
 */
declare const agentDPML: _dpml_core.DomainDPML<AgentConfig>;
/**
 * 导出编译器，便于直接使用
 */
declare const compiler: _dpml_core.DomainCompiler<AgentConfig>;

export { type Agent, type AgentConfig, AgentError, AgentErrorType, type ChatInput, type ChatOutput, type Content, type ContentItem, type ContentType, type LLMConfig, agentDPML, compiler, createAgent };