@axiom-lattice/core 1.0.1

package/src/agent_lattice/AgentLatticeManager.ts

@@ -0,0 +1,216 @@
+import { BaseLatticeManager } from "../base/BaseLatticeManager";
+import {
+  AgentConfig,
+  AgentClient,
+  AgentLattice,
+  GraphBuildOptions,
+  AgentBuildParams,
+} from "./types";
+import { AgentGraphBuilderFactory } from "./builders/AgentGraphBuilderFactory";
+import { AgentParamsBuilder } from "./builders/AgentParamsBuilder";
+
+// 类型定义已移至 ./types.ts
+
+/**
+ * AgentLatticeManager - 单例Agent Lattice管理器
+ * 负责注册、管理各种Agent Lattice
+ */
+export class AgentLatticeManager extends BaseLatticeManager<AgentLattice> {
+  private static _instance: AgentLatticeManager;
+
+  /**
+   * 获取AgentLatticeManager单例实例
+   */
+  public static getInstance(): AgentLatticeManager {
+    if (!AgentLatticeManager._instance) {
+      AgentLatticeManager._instance = new AgentLatticeManager();
+    }
+    return AgentLatticeManager._instance;
+  }
+
+  /**
+   * 获取Lattice类型前缀
+   */
+  protected getLatticeType(): string {
+    return "agents";
+  }
+
+  /**
+   * 注册Agent Lattice
+   * @param config Agent配置
+   */
+  public registerLattice(config: AgentConfig): void {
+    // 创建Agent Lattice对象
+    const agentLattice: AgentLattice = {
+      config,
+      client: undefined, // 客户端将在需要时由initializeClient创建
+    };
+
+    // 调用基类的register方法
+    this.register(config.key, agentLattice);
+  }
+
+  /**
+   * 获取AgentLattice
+   * @param key Lattice键名
+   */
+  public getAgentLattice(key: string): AgentLattice | undefined {
+    return this.get(key);
+  }
+
+  /**
+   * 获取所有Lattice
+   */
+  public getAllLattices(): AgentLattice[] {
+    return this.getAll();
+  }
+
+  /**
+   * 检查Lattice是否存在
+   * @param key Lattice键名
+   */
+  public hasLattice(key: string): boolean {
+    return this.has(key);
+  }
+
+  /**
+   * 移除Lattice
+   * @param key Lattice键名
+   */
+  public removeLattice(key: string): boolean {
+    return this.remove(key);
+  }
+
+  /**
+   * 获取Agent配置
+   * @param key Lattice键名
+   */
+  public getAgentConfig(key: string): AgentConfig | undefined {
+    return this.getAgentLattice(key)?.config;
+  }
+
+  /**
+   * 获取所有Agent配置
+   */
+  public getAllAgentConfigs(): AgentConfig[] {
+    return this.getAllLattices().map((lattice) => lattice.config);
+  }
+
+  /**
+   * 验证Agent输入参数
+   * @param key Lattice键名
+   * @param input 输入参数
+   */
+  public validateAgentInput(key: string, input: any): boolean {
+    const agentLattice = this.getAgentLattice(key);
+    if (!agentLattice) {
+      return false;
+    }
+
+    try {
+      if (agentLattice.config.schema) {
+        agentLattice.config.schema.parse(input);
+      }
+      return true;
+    } catch {
+      return false;
+    }
+  }
+
+  /**
+   * 构建Agent参数
+   *
+   * @param agentLattice Agent Lattice对象
+   * @param options 构建选项
+   * @returns 返回Agent构建参数
+   */
+  private buildAgentParams(
+    agentLattice: AgentLattice,
+    options?: GraphBuildOptions
+  ): AgentBuildParams {
+    // 创建参数构建器
+    const paramsBuilder = new AgentParamsBuilder((key: string) =>
+      this.getAgentLattice(key)
+    );
+
+    // 构建参数
+    return paramsBuilder.buildParams(agentLattice, options);
+  }
+
+  /**
+   * 初始化Agent客户端
+   *
+   * 使用AgentGraphBuilderFactory构建Graph并设置为客户端
+   *
+   * @param key Lattice键名
+   * @param options 构建选项
+   * @returns 返回CompiledGraph对象
+   */
+  public initializeClient(
+    key: string,
+    options?: GraphBuildOptions
+  ): AgentClient {
+    const agentLattice = this.getAgentLattice(key);
+    if (!agentLattice) {
+      throw new Error(`Agent Lattice "${key}" 不存在`);
+    }
+
+    // 如果客户端已经存在，直接返回
+    if (agentLattice.client) {
+      return agentLattice.client;
+    }
+
+    // 获取工厂实例
+    const factory = AgentGraphBuilderFactory.getInstance();
+
+    // 获取对应类型的Builder
+    const builder = factory.getBuilder(agentLattice.config.type);
+
+    // 构建参数
+    const params = this.buildAgentParams(agentLattice, options);
+
+    // 使用Builder构建Graph
+    const graph = builder.build(agentLattice, params);
+
+    // 设置为客户端
+    agentLattice.client = graph;
+
+    return graph;
+  }
+}
+
+// 导出单例实例
+export const agentLatticeManager = AgentLatticeManager.getInstance();
+
+// 导出便捷方法
+export const registerAgentLattice = (config: AgentConfig) => {
+  agentLatticeManager.registerLattice(config);
+};
+
+export const registerAgentLattices = (configs: AgentConfig[]) => {
+  configs.forEach((config) => {
+    agentLatticeManager.registerLattice(config);
+  });
+};
+
+export const getAgentLattice = (key: string) =>
+  agentLatticeManager.getAgentLattice(key);
+
+export const getAgentConfig = (key: string) =>
+  agentLatticeManager.getAgentConfig(key);
+
+export const getAllAgentConfigs = () =>
+  agentLatticeManager.getAllAgentConfigs();
+
+export const validateAgentInput = (key: string, input: any) =>
+  agentLatticeManager.validateAgentInput(key, input);
+
+/**
+ * 获取或初始化Agent客户端
+ *
+ * @param key Agent Lattice键名
+ * @param options 构建选项
+ * @returns 返回CompiledGraph对象
+ */
+export const getAgentClient = (key: string, options?: GraphBuildOptions) =>
+  agentLatticeManager.initializeClient(key, options);

package/src/agent_lattice/builders/AgentBuilder.ts

@@ -0,0 +1,79 @@
+/**
+ * Agent Builder 服务
+ *
+ * 提供构建和执行Agent的功能
+ */
+
+import { CompiledStateGraph } from "@langchain/langgraph";
+import { AgentLattice, GraphBuildOptions } from "../types";
+import { AgentGraphBuilderFactory } from "./AgentGraphBuilderFactory";
+import {
+  AgentParamsBuilder,
+  GetAgentLatticeFunction,
+} from "./AgentParamsBuilder";
+
+/**
+ * Agent Builder 服务
+ */
+export class AgentBuilder {
+  private graphBuilderFactory: AgentGraphBuilderFactory;
+  private paramsBuilder: AgentParamsBuilder;
+
+  /**
+   * 构造函数
+   *
+   * @param getAgentLatticeFunc 获取Agent Lattice的函数
+   */
+  constructor(getAgentLatticeFunc: GetAgentLatticeFunction) {
+    this.graphBuilderFactory = AgentGraphBuilderFactory.getInstance();
+    this.paramsBuilder = new AgentParamsBuilder(getAgentLatticeFunc);
+  }
+
+  /**
+   * 构建Agent Graph
+   *
+   * @param agentLattice Agent Lattice对象
+   * @param options 构建选项
+   * @returns 返回CompiledGraph对象
+   */
+  public buildGraph(
+    agentLattice: AgentLattice,
+    options?: GraphBuildOptions
+  ): CompiledStateGraph<any, any, any, any, any> {
+    // 准备构建参数
+    const buildParams = this.paramsBuilder.buildParams(agentLattice, options);
+
+    // 获取对应的Builder
+    const builder = this.graphBuilderFactory.getBuilder(
+      agentLattice.config.type
+    );
+
+    // 构建Graph
+    return builder.build(agentLattice, buildParams);
+  }
+
+  /**
+   * 执行Agent
+   *
+   * @param agentLattice Agent Lattice对象
+   * @param input 输入参数
+   * @param options 执行选项
+   * @returns 返回执行结果
+   */
+  public async execute<TInput = any, TOutput = any>(
+    agentLattice: AgentLattice,
+    input: TInput,
+    options?: GraphBuildOptions & { sessionId?: string }
+  ): Promise<TOutput> {
+    // 构建Graph
+    const graph = this.buildGraph(agentLattice, options);
+
+    // 执行Graph
+    const config: any = {};
+    if (options?.metadata) {
+      config.metadata = options.metadata;
+    }
+
+    return (await graph.invoke({ input }, config)) as TOutput;
+  }
+}

package/src/agent_lattice/builders/AgentGraphBuilder.ts

@@ -0,0 +1,22 @@
+/**
+ * Agent Graph Builder 接口
+ *
+ * 策略模式的核心接口，定义了构建Agent Graph的方法
+ */
+
+import { CompiledStateGraph } from "@langchain/langgraph";
+import { AgentLattice, AgentBuildParams } from "../types";
+
+export interface AgentGraphBuilder {
+  /**
+   * 构建Agent Graph
+   *
+   * @param agentLattice Agent Lattice对象
+   * @param params Agent构建参数
+   * @returns 返回CompiledGraph对象
+   */
+  build(
+    agentLattice: AgentLattice,
+    params: AgentBuildParams
+  ): CompiledStateGraph<any, any, any, any, any>;
+}

package/src/agent_lattice/builders/AgentGraphBuilderFactory.ts

@@ -0,0 +1,70 @@
+/**
+ * Agent Graph Builder Factory
+ *
+ * 工厂类，根据Agent类型创建对应的Builder
+ */
+
+import { AgentType } from "../types";
+import { AgentGraphBuilder } from "./AgentGraphBuilder";
+import { ReActAgentGraphBuilder } from "./ReActAgentGraphBuilder";
+import { DeepAgentGraphBuilder } from "./DeepAgentGraphBuilder";
+import { PlanExecuteAgentGraphBuilder } from "./PlanExecuteAgentGraphBuilder";
+
+export class AgentGraphBuilderFactory {
+  // 单例模式
+  private static instance: AgentGraphBuilderFactory;
+
+  // Builder缓存
+  private builders: Map<AgentType, AgentGraphBuilder>;
+
+  private constructor() {
+    this.builders = new Map();
+    this.registerDefaultBuilders();
+  }
+
+  /**
+   * 获取单例实例
+   */
+  public static getInstance(): AgentGraphBuilderFactory {
+    if (!AgentGraphBuilderFactory.instance) {
+      AgentGraphBuilderFactory.instance = new AgentGraphBuilderFactory();
+    }
+    return AgentGraphBuilderFactory.instance;
+  }
+
+  /**
+   * 注册默认的Builder
+   */
+  private registerDefaultBuilders(): void {
+    this.builders.set(AgentType.REACT, new ReActAgentGraphBuilder());
+    this.builders.set(AgentType.DEEP_AGENT, new DeepAgentGraphBuilder());
+    this.builders.set(
+      AgentType.PLAN_EXECUTE,
+      new PlanExecuteAgentGraphBuilder()
+    );
+  }
+
+  /**
+   * 注册自定义Builder
+   *
+   * @param type Agent类型
+   * @param builder Builder实例
+   */
+  public registerBuilder(type: AgentType, builder: AgentGraphBuilder): void {
+    this.builders.set(type, builder);
+  }
+
+  /**
+   * 获取Builder
+   *
+   * @param type Agent类型
+   * @returns 返回对应的Builder
+   */
+  public getBuilder(type: AgentType): AgentGraphBuilder {
+    const builder = this.builders.get(type);
+    if (!builder) {
+      throw new Error(`不支持的Agent类型: ${type}`);
+    }
+    return builder;
+  }
+}

package/src/agent_lattice/builders/AgentParamsBuilder.ts

@@ -0,0 +1,86 @@
+/**
+ * Agent parameters builder
+ *
+ * responsible for preparing the parameters required for building the Agent
+ */
+
+import { toolLatticeManager } from "../../tool_lattice/ToolLatticeManager";
+import { modelLatticeManager } from "../../model_lattice/ModelLatticeManager";
+import { AgentLattice, AgentBuildParams, GraphBuildOptions } from "../types";
+
+/**
+ * Get Agent Lattice function type
+ */
+export type GetAgentLatticeFunction = (key: string) => AgentLattice | undefined;
+
+/**
+ * Agent parameters builder
+ */
+export class AgentParamsBuilder {
+  private getAgentLatticeFunc: GetAgentLatticeFunction;
+
+  /**
+   * constructor
+   *
+   * @param getAgentLatticeFunc get Agent Lattice function
+   */
+  constructor(getAgentLatticeFunc: GetAgentLatticeFunction) {
+    this.getAgentLatticeFunc = getAgentLatticeFunc;
+  }
+
+  /**
+   * build Agent parameters
+   *
+   * @param agentLattice Agent Lattice object
+   * @param options build options
+   * @returns Agent build parameters
+   */
+  public buildParams(
+    agentLattice: AgentLattice,
+    options?: GraphBuildOptions
+  ): AgentBuildParams {
+    // get tools
+    const toolKeys = options?.overrideTools || agentLattice.config.tools || [];
+    const tools = toolKeys.map((toolKey: string) => {
+      const toolLattice = toolLatticeManager.getToolLattice(toolKey);
+      if (!toolLattice) {
+        throw new Error(`Tool "${toolKey}" does not exist`);
+      }
+      return {
+        key: toolKey,
+        definition: toolLattice.config,
+        executor: toolLattice.client,
+      };
+    });
+
+    // get model
+    const modelKey = options?.overrideModel || agentLattice.config.modelKey;
+    const model = modelKey
+      ? modelLatticeManager.getModelLattice(modelKey).client
+      : modelLatticeManager.getModelLattice("default").client;
+    if (!model) {
+      throw new Error(`Model "${modelKey}" does not exist`);
+    }
+
+    // get subAgents
+    const subAgentKeys = agentLattice.config.subAgents || [];
+    const subAgents = subAgentKeys.map((agentKey: string) => {
+      const subAgentLattice = this.getAgentLatticeFunc(agentKey);
+      if (!subAgentLattice) {
+        throw new Error(`SubAgent "${agentKey}" does not exist`);
+      }
+      return {
+        key: agentKey,
+        config: subAgentLattice.config,
+        client: subAgentLattice.client,
+      };
+    });
+
+    return {
+      tools,
+      model,
+      subAgents,
+      prompt: agentLattice.config.prompt,
+    };
+  }
+}

package/src/agent_lattice/builders/DeepAgentGraphBuilder.ts

@@ -0,0 +1,46 @@
+/**
+ * Deep Agent Graph Builder
+ *
+ * 实现 Deep Agent 类型的 Agent Graph 构建
+ */
+
+import { CompiledStateGraph } from "@langchain/langgraph";
+import { DynamicTool } from "@langchain/core/tools";
+import { createDeepAgent } from "../../deep_agent";
+import { AgentLattice, AgentBuildParams } from "../types";
+import { AgentGraphBuilder } from "./AgentGraphBuilder";
+import { getToolClient } from "../../tool_lattice/ToolLatticeManager";
+
+export class DeepAgentGraphBuilder implements AgentGraphBuilder {
+  /**
+   * 构建Deep Agent Graph
+   *
+   * @param agentLattice Agent Lattice对象
+   * @param params Agent构建参数
+   * @returns 返回CompiledGraph对象
+   */
+  build(
+    agentLattice: AgentLattice,
+    params: AgentBuildParams
+  ): CompiledStateGraph<any, any, any, any, any> {
+    const tools = params.tools
+      .map((t) => {
+        const toolClient = getToolClient(t.key);
+
+        return toolClient;
+      })
+      .filter((tool) => tool !== undefined);
+
+    return createDeepAgent({
+      tools: tools,
+      model: params.model,
+      instructions: params.prompt,
+      subagents: params.subAgents.map((sa) => ({
+        name: sa.key,
+        description: sa.config.description,
+        prompt: sa.config.prompt,
+        tools: sa.config.tools || [],
+      })),
+    });
+  }
+}

package/src/agent_lattice/builders/PlanExecuteAgentGraphBuilder.ts

@@ -0,0 +1,46 @@
+/**
+ * Plan Execute Agent Graph Builder
+ *
+ * 实现 Plan Execute 类型的 Agent Graph 构建
+ */
+
+import { CompiledStateGraph } from "@langchain/langgraph";
+import { DynamicTool } from "@langchain/core/tools";
+import { AgentLattice, AgentBuildParams } from "../types";
+import { AgentGraphBuilder } from "./AgentGraphBuilder";
+import { getToolClient } from "../../tool_lattice/ToolLatticeManager";
+import { createPlanExecuteAgent } from "@createPlanExecuteAgent";
+
+export class PlanExecuteAgentGraphBuilder implements AgentGraphBuilder {
+  /**
+   * 构建Plan Execute Agent Graph
+   *
+   * @param agentLattice Agent Lattice对象
+   * @param params Agent构建参数
+   * @returns 返回CompiledGraph对象
+   */
+  build(
+    agentLattice: AgentLattice,
+    params: AgentBuildParams
+  ): CompiledStateGraph<any, any, any, any, any> {
+    // 创建符合 DynamicTool 接口的工具对象
+    const tools = params.tools
+      .map((t) => {
+        // 使用 DynamicTool 构造工具对象
+        const tool = getToolClient(t.key);
+        return tool;
+      })
+      .filter((tool) => tool !== undefined);
+
+    // 由于createPlanExecuteAgent的返回类型与CompiledStateGraph不兼容
+    // 这里我们使用createAgentExecutor作为替代方案
+    const agent = createPlanExecuteAgent({
+      llmManager: params.model,
+      tools: tools,
+      prompt: params.prompt,
+      name: agentLattice.config.name,
+      description: agentLattice.config.description,
+    });
+    return agent.getCompiledGraph();
+  }
+}

package/src/agent_lattice/builders/ReActAgentGraphBuilder.ts

@@ -0,0 +1,42 @@
+/**
+ * ReAct Agent Graph Builder
+ *
+ * 实现 ReAct 类型的 Agent Graph 构建
+ */
+
+import { CompiledStateGraph } from "@langchain/langgraph";
+import { DynamicTool } from "@langchain/core/tools";
+import { AgentLattice, AgentBuildParams } from "../types";
+import { AgentGraphBuilder } from "./AgentGraphBuilder";
+import { getToolClient } from "../../tool_lattice/ToolLatticeManager";
+import { createReactAgent } from "@langchain/langgraph/prebuilt";
+
+export class ReActAgentGraphBuilder implements AgentGraphBuilder {
+  /**
+   * 构建ReAct Agent Graph
+   *
+   * @param agentLattice Agent Lattice对象
+   * @param params Agent构建参数
+   * @returns 返回CompiledGraph对象
+   */
+  build(
+    agentLattice: AgentLattice,
+    params: AgentBuildParams
+  ): CompiledStateGraph<any, any, any, any, any> {
+    // 创建符合 DynamicTool 接口的工具对象
+    const tools = params.tools
+      .map((t) => {
+        // 使用 DynamicTool 构造工具对象
+        const tool = getToolClient(t.key);
+        return tool;
+      })
+      .filter((tool) => tool !== undefined);
+
+    return createReactAgent({
+      llm: params.model,
+      tools: tools,
+      prompt: params.prompt,
+      name: agentLattice.config.name,
+    });
+  }
+}

package/src/agent_lattice/builders/index.ts

@@ -0,0 +1,14 @@
+/**
+ * Agent Builder 模块
+ *
+ * 提供构建Agent Graph的各种Builder和工具
+ */
+
+// 导出接口
+export { AgentGraphBuilder } from "./AgentGraphBuilder";
+export { GetAgentLatticeFunction } from "./AgentParamsBuilder";
+
+// 导出工厂和工具类
+export { AgentGraphBuilderFactory } from "./AgentGraphBuilderFactory";
+export { AgentParamsBuilder } from "./AgentParamsBuilder";
+export { AgentBuilder } from "./AgentBuilder";

package/src/agent_lattice/index.ts

@@ -0,0 +1,27 @@
+/**
+ * Agent Lattice模块
+ *
+ * 提供Agent Lattice的管理和Graph构建功能
+ */
+
+// 导出类型定义
+export {
+  AgentType,
+  AgentConfig,
+  AgentClient,
+  AgentLattice,
+  GraphBuildOptions,
+} from "./types";
+
+// 导出AgentLatticeManager相关内容
+export {
+  AgentLatticeManager,
+  agentLatticeManager,
+  registerAgentLattice,
+  registerAgentLattices,
+  getAgentLattice,
+  getAgentConfig,
+  getAllAgentConfigs,
+  validateAgentInput,
+  getAgentClient,
+} from "./AgentLatticeManager";

package/src/agent_lattice/types.ts

@@ -0,0 +1,42 @@
+/**
+ * Agent Lattice 类型定义
+ *
+ * 包含Agent Lattice相关的所有类型定义，供其他模块共享使用
+ */
+
+import { z } from "zod";
+import { ModelLattice } from "@model_lattice/ModelLattice";
+import { CompiledStateGraph } from "@langchain/langgraph";
+import {
+  AgentType,
+  AgentConfig,
+  GraphBuildOptions,
+} from "@axiom-lattice/protocols";
+
+// Re-export types from protocols
+export { AgentType, AgentConfig, GraphBuildOptions };
+
+// Agent客户端类型 - CompiledStateGraph
+export type AgentClient = CompiledStateGraph<any, any, any, any, any>;
+
+// AgentLattice接口定义
+export interface AgentLattice {
+  config: AgentConfig;
+  client: AgentClient | undefined;
+}
+
+// Agent构建参数接口
+export interface AgentBuildParams {
+  tools: Array<{
+    key: string;
+    definition: any;
+    executor: any;
+  }>;
+  model: ModelLattice;
+  subAgents: Array<{
+    key: string;
+    config: AgentConfig;
+    client: AgentClient | undefined;
+  }>;
+  prompt: string;
+}