AgentKit：基于TypeScript的确定性多智能体编排框架

AgentKit 是一个用于构建复杂多智能体网络的强大框架。其核心优势在于提供确定性和灵活的路由机制，兼容多种模型提供商，并深度集成了模型上下文协议（MCP）以实现丰富的工具调用。专为蓬勃发展的 TypeScript AI 社区打造，它可以与 Inngest 开发服务器无缝结合进行本地开发，并利用 Inngest 的编排引擎确保您的智能体在部署到云端时具备容错能力。

Core Concepts

要有效使用 AgentKit，理解其基础构建模块至关重要。

Agents

智能体（Agent）是一个可以通过提示词、工具和 MCP 服务器增强的 LLM 调用。它代表网络中的一个单一、专业化的执行者。

Networks

网络（Network）是多个智能体进行协作的结构化方式。它提供一个共享的状态（State），并促进智能体之间的交接，从而实现复杂的工作流。

State

状态（State）将对话历史与一个完全类型化的状态机相结合。它是路由决策的核心，并在同一网络内的所有智能体之间共享。

Routers

路由器（Routers）是系统自主性的体现。它们决定下一个应该执行哪个智能体，其逻辑范围可以从纯代码基础到基于 LLM 的编排（例如 ReAct 模式）。

Tracing

内置的追踪（Tracing）功能允许您在本地和云端调试和优化智能体工作流，为执行的每一步提供可见性。

Getting Started

首先安装必要的包。

npm i @inngest/agent-kit inngest

Note: Starting with AgentKit v0.9.0, inngest must be installed as a separate dependency alongside @inngest/agent-kit. This ensures runtime compatibility and prevents version conflicts.
注意：从 AgentKit v0.9.0 开始，inngest 必须作为单独的依赖项与 @inngest/agent-kit 一起安装。这确保了运行时兼容性并防止版本冲突。

MCP Agent Example

AgentKit 擅长将 MCP 服务器集成为工具。以下是一个使用 Neon 数据库 MCP 服务器的示例。

import {
  anthropic,
  createAgent,
  createNetwork,
  createTool,
} from "@inngest/agent-kit";
import { createServer } from "@inngest/agent-kit/server";
import { createSmitheryUrl } from "@smithery/sdk/config.js";
import { z } from "zod";

const neonServerUrl = createSmitheryUrl(
  "https://server.smithery.ai/neon/mcp?profile=bored-catshark-da8hf&api_key=123123123"
);

const neonAgent = createAgent({
  name: "neon-agent",
  system: `You are a helpful assistant that help manage a Neon account.
  IMPORTANT: Call the 'done' tool when the question is answered.
  `,
  tools: [
    createTool({
      name: "done",
      description: "Call this tool when you are finished with the task.",
      parameters: z.object({
        answer: z.string().describe("Answer to the user's question."),
      }),
      handler: async ({ answer }, { network }) => {
        network?.state.kv.set("answer", answer);
      },
    }),
  ],
  mcpServers: [
    {
      name: "neon",
      transport: {
        type: "streamable-http",
        url: neonServerUrl.toString(),
      },
    },
  ],
});

const neonAgentNetwork = createNetwork({
  name: "neon-agent",
  agents: [neonAgent],
  defaultModel: anthropic({
    model: "claude-3-5-sonnet-20240620",
    defaultParameters: {
      max_tokens: 1000,
    },
  }),
  router: ({ network }) => {
    if (!network?.state.kv.get("answer")) {
      return neonAgent;
    }
    return;
  },
});

// Create and start the server
const server = createServer({
  networks: [neonAgentNetwork],
});

server.listen(3010, () =>
  console.log("Support Agent demo server is running on port 3010")
);

您可以通过 GitHub 仓库 在本地运行此示例。

Deterministic Routing with State-Based Logic

AgentKit 的独特优势在于其确定性的、基于状态的路由。这种方法允许您实现从完全代码控制到自主的工作流，同时在整个过程中保持监督。

状态（State）是一个在网络中所有智能体之间共享的键值存储。它可以从路由器、智能体生命周期回调、智能体提示词和智能体工具中访问，构成了智能编排的支柱。

flowchart LR
    subgraph Network
        state["State"]
        subgraph Agent
            systemp["System prompt"]
            tools["Tools"]
            lifecycle["Lifecycle callbacks"]
        end
        router["Router"]
    end

    state-->systemp
    state<-->tools
    state<-->lifecycle
    state<-->router

双向箭头表示读/写访问权限，单向箭头表示只读访问权限。这种共享状态与消息历史记录相结合，是确定性路由的基础。

Code-Based Routing

我们建议从基于代码的路由开始，以便完全控制网络的执行流程。这是最确定的模式，其中路由函数对智能体工具所做的状态更新做出反应。

以下示例展示了一个编码助手网络，其中路由器根据 codeAssistantAgent 生成的计划来编排智能体。

（编码助手网络的示例代码较为详尽，演示了如何创建具有共享工具的多个智能体（documentationAgent、analysisAgent、summarizationAgent、codeAssistantAgent），以及一个根据存储的计划顺序执行智能体的路由器函数。关键点在于路由器的逻辑，它检查共享状态（code、plan、summary）来决定下一个要运行的智能体。）

// ... Agent definitions ...

const network = createNetwork({
  name: "code-assistant-v2",
  agents: [
    codeAssistantAgent,
    documentationAgent,
    analysisAgent,
    summarizationAgent,
  ],
  router: ({ network }) => {
    // 1. If no code or plan exists, start with the code assistant.
    if (!network?.state.kv.has("code") || !network?.state.kv.has("plan")) {
      return codeAssistantAgent;
    } else {
      const plan = (network?.state.kv.get("plan") || []) as string[];
      const nextAgent = plan.pop();
      // 2. Execute agents from the plan.
      if (nextAgent) {
        network?.state.kv.set("plan", plan);
        return network?.agents.get(nextAgent);
      // 3. If plan is done but no summary, run the summarization agent.
      } else if (!network?.state.kv.has("summary")) {
        return summarizationAgent;
      // 4. Everything is complete.
      } else {
        return undefined;
      }
    }
  },
  // ... default model configuration ...
});

查看完整源代码：代码助手示例

Agent-Based Routing

基于智能体的路由用一个专门的路由智能体（Routing Agent）取代了路由函数。这使得网络能够自主选择执行哪个智能体并决定任务何时完成。控制通过 onRoute 生命周期回调来保持。

下面的示例展示了一个使用“主管”路由智能体的支持智能体网络。

（此示例创建了 customerSupportAgent、technicalSupportAgent 以及一个 supervisorRoutingAgent。主管使用 route_to_agent 和 done 等工具做出决策。onRoute 回调包含解释主管工具调用并返回下一个要执行的智能体名称的逻辑，确保路由循环正确继续。）

// ... Agent and tool definitions ...

const supervisorRoutingAgent = createRoutingAgent({
  name: "Supervisor",
  system: `You are a supervisor. Your goal is to answer customer initial request or escalate the ticket...`,
  // ... tools: done, route_to_agent ...
  lifecycle: {
    onRoute: ({ result, network }) => {
      const lastMessage = lastResult(network?.state.results);
      // Ensure to loop back to the last agent if a tool was just called.
      if (lastMessage && isLastMessageOfType(lastMessage, "tool_call")) {
        return [lastMessage?.agent.name];
      }
      const tool = result.toolCalls[0];
      if (!tool) {
        return;
      }
      const toolName = tool.tool.name;
      if (toolName === "done") {
        return; // Stop routing.
      } else if (toolName === "route_to_agent") {
        // Extract the agent name from the tool call and route to it.
        if (/* ... extraction logic ... */) {
          return [extractedAgentName];
        }
      }
      return;
    },
  },
});

const supportNetwork = createNetwork({
  name: "Support Network",
  agents: [customerSupportAgent, technicalSupportAgent],
  router: supervisorRoutingAgent, // Use the agent as the router.
  // ... default model ...
});

在本地尝试此示例：支持智能体示例

建议：两种路由方法都兼容 maxIter 参数以限制网络迭代次数。强烈建议在使用基于智能体的路由时设置此限制。

Example Showcase

AgentKit 的多功能性通过几个复杂的示例得以展示：

SWE-bench 智能体：解决来自 SWE-bench 基准测试的复杂软件工程挑战。
简单搜索智能体：自主浏览网络以回答问题。
支持智能体：使用 Inngest 的 waitForEvent() 集成人在回路功能。
E2B 编码智能体：复制 Cursor 的 Agent 模式，根据提示创建完整项目。
Daytona 编码智能体：创建 Web 应用、运行测试、执行脚本，并具备自动化开发服务器检测功能。

Conclusion

AgentKit 为构建确定性的多智能体系统提供了一个健壮、灵活且对开发者友好的基础。通过结合共享状态、多种路由策略、MCP 集成和云原生韧性，它使开发人员能够有信心地创建复杂的人工智能工作流。通过浏览文档和克隆示例开始构建。

（注：由于篇幅限制，详细的贡献指南和许可证信息已进行概括。原始内容表明项目使用 Apache 2.0 许可证，并采用标准的 Node.js/PNPM 设置进行开发。）