multi-agent

一个 TypeScript 多智能体编排工具。

multi-agent 关注的是 Agent 应用里的基础编排问题：任务如何拆分、如何按依赖顺序执行、多个 Agent 如何共享状态、流程如何暂停等待人工确认，以及如何接入事件驱动场景。

它不绑定任何 LLM 厂商，也不内置模型调用。你可以把它作为一个小而清晰的编排内核，嵌入到自己的应用里。

特性

• 基于 Operation 的异步任务单元
• 基于 AgentQueue 的依赖调度、并发控制和优先级执行
• 支持取消、超时、失败传播和生命周期事件
• 支持 human-in-the-loop：任务可暂停，等待外部确认后恢复
• 提供轻量 Store，适合做多 Agent 共享状态
• 提供模型无关的消息、工具调用和 LLM provider 类型
• 支持 RunLoop，可处理定时器或外部输入驱动的长期运行流程
• TypeScript 编写，ESM，运行时零依赖

要求 Node.js >=18。

安装

npm install @coderyi/multi-agent

快速开始

import { AgentQueue, createOperation } from "multi-agent";

const queue = new AgentQueue({
  id: "main",
  maxConcurrent: 2,
});

const fetchUser = createOperation("fetchUser", async () => {
  return { id: 1, name: "Alice" };
});

const fetchStats = createOperation("fetchStats", async () => {
  return { posts: 17 };
});

const summarize = createOperation("summarize", async () => {
  const user = await fetchUser.result;
  const stats = await fetchStats.result;
  return `${user.name} has ${stats.posts} posts`;
})
  .addDependency(fetchUser)
  .addDependency(fetchStats);

queue.submitAll([fetchUser, fetchStats, summarize]);

await queue.waitFor([summarize]);
console.log(await summarize.result);

await queue.close();

fetchUser 和 fetchStats 可以并发执行；summarize 会等两个依赖都成功后再运行。

核心概念

Operation

Operation 是最小工作单元。它有自己的状态、结果、依赖、取消信号和生命周期回调。

常见状态包括：

• pending
• running
• interrupted
• finished
• cancelled
• failed

AgentQueue

AgentQueue 负责调度 Operation。它会根据依赖关系决定执行顺序，并处理并发、失败传播、暂停恢复和队列关闭。

const queue = new AgentQueue({
  id: "workflow",
  maxConcurrent: 4,
  onEvent: (event) => {
    console.log(event.type);
  },
});

Store

Store 是一个简单的共享状态容器，适合做多 Agent 的状态黑板。

import { createStore, messagesReducer, textMessage } from "multi-agent";
import type { Message } from "multi-agent";

const store = createStore<{ messages: Message[] }>(
  { messages: [] },
  { reducers: { messages: messagesReducer } },
);

store.merge({
  messages: [textMessage("user", "Hello")],
});

LLM

multi-agent 不直接调用模型。

具体的模型服务、推理接口或内部系统，可以在应用层按需接入。

Interrupt

Operation 可以通过 ctx.interrupt() 暂停执行，并等待外部调用 queue.resolveInterrupt() 恢复。

这适合审批、确认、权限申请、人工输入等流程。

RunLoop

RunLoop 用于事件驱动场景。内置：

• TimerSource
• InputSource

也可以把事件源注册到 AgentQueue，让每次事件触发一轮新的任务执行。

示例

仓库提供了几个示例：

npm run example -- examples/01-queue.ts
npm run example -- examples/02-workflow.ts
npm run example -- examples/03-interrupt.ts
npm run example -- examples/04-runloop.ts

模块入口

import { AgentQueue, createOperation } from "multi-agent";
import { createStore } from "multi-agent/state";
import { textMessage, messagesReducer } from "multi-agent/llm";

也可以从主入口直接导入常用能力：

import {
  AgentQueue,
  createOperation,
  createStore,
  textMessage,
  messagesReducer,
} from "multi-agent";

License

MIT