imily-agent

imily-agent 是一个基于 LangChain JS 的 TypeScript 智能体工厂库。它把当前示例项目里的 agent 创建方式抽成可复用 npm 包：第三方应用只需要创建工厂、注册继承 BaseAgent 的智能体类，就可以按名称获取智能体并执行多轮对话。

核心差异是：每次执行都会返回完整 messages 历史，下一轮调用时可以把返回的 messages 继续传回去，避免多轮对话上下文丢失。

安装

npm install imily-agent

如果在本仓库内开发：

yarn --cwd imily-agent build
yarn --cwd imily-agent test

创建工厂

ESM / TypeScript：

import { ImilyAgentFactory } from "imily-agent";

const factory = new ImilyAgentFactory({
  baseURL: "https://ds.hnsin.cn",
  apiKey: process.env.OPENAI_API_KEY!,
  model: "deepseek-v4-flash",
  thinkingEnabled: false,
});

CommonJS / require：

const { ImilyAgentFactory } = require("imily-agent");

const factory = new ImilyAgentFactory({
  baseURL: "https://ds.hnsin.cn",
  apiKey: process.env.OPENAI_API_KEY,
  model: "deepseek-v4-flash",
});

工厂负责统一创建 ChatOpenAI 兼容模型，内部使用 configuration.baseURL 连接 OpenAI 兼容接口。

定义智能体

智能体继承 BaseAgent，在类里声明名称、作用、系统提示词，并通过 buildTools() 返回可用工具。智能体被添加到工厂时，会自动初始化 LangChain agent 并携带这些工具。

import { BaseAgent, z } from "imily-agent";

class ProductAgent extends BaseAgent {
  readonly name = "product";

  readonly description = "查询产品资料、库存和运营建议。";

  protected readonly systemPrompt = `你是产品运营智能体。遇到产品或库存问题时，先调用工具获取数据，再用中文给出结论。`;

  protected readonly modelOptions = {
    temperature: 0.2,
  };

  protected buildTools() {
    const searchProducts = this.createTool(
      async ({ query }) => {
        const products = [
          { id: "p-1001", name: "金属阅读台灯", stock: 42 },
          { id: "p-1002", name: "胡桃木置物架", stock: 18 },
        ].filter((product) => product.name.includes(query));

        return this.toJson({ products });
      },
      {
        name: "search_products",
        description: "按产品名称搜索产品和库存数据。",
        schema: z.object({
          query: z.string().min(1).describe("产品名称关键词。"),
        }),
      },
    );

    return [searchProducts];
  }
}

注册和查询智能体

factory.addAgent(new ProductAgent());

const agents = factory.listAgents();
// [{ name: "product", description: "查询产品资料、库存和运营建议。" }]

const productAgent = factory.getAgent("product");

单轮和多轮调用

invoke 可以接收 { messages }，也可以直接接收消息数组。返回值包含 answer 和完整 messages。

let result = await productAgent.invoke({
  messages: [{ role: "user", content: "请帮我分析金属阅读台灯的库存风险。" }],
});

console.log(result.answer);

result = await productAgent.invoke({
  messages: [
    ...result.messages,
    { role: "user", content: "继续给我一个补货建议。" },
  ],
});

console.log(result.answer);

result.messages 是 LangChain 返回的完整消息历史，可以直接作为下一轮的上下文传入。首次请求也可以按 LangChain 的普通消息格式传入：

[{ role: "user", content: "请帮我分析XX" }]

API

new ImilyAgentFactory(options)

常用参数：

• baseURL：OpenAI 兼容接口地址。
• apiKey：模型服务密钥。
• model：默认模型名。
• thinkingModel：启用思考模式时使用的模型名。
• thinkingEnabled：是否启用 reasoning.effort。
• thinkingEffort：low、medium 或 high。
• temperature：默认温度。
• streaming：是否启用模型流式调用。
• streamUsage：是否返回流式 token 用量。
• maxTokens、timeout：传给 ChatOpenAI 的限制参数。

factory.addAgent(agent)

注册一个继承 BaseAgent 的智能体实例。注册时会自动创建 LangChain agent，并绑定 buildTools() 返回的工具。

factory.listAgents()

返回所有已注册智能体的 { name, description }。

factory.getAgent(name)

按名称获取智能体实例。

agent.invoke({ messages })

执行智能体，返回：

type AgentRunResult = {
  agent: string;
  answer: string;
  messages: AgentOutputMessage[];
};

导出项

import {
  BaseAgent,
  ImilyAgentFactory,
  createTool,
  z,
} from "imily-agent";

createTool 是 LangChain tool 的别名；在 BaseAgent 子类中也可以直接使用 this.createTool(...)。