AgentKit

通过 MCP 构建具有确定性路由和丰富工具链的多智能体网络。

文档  ·  博客  ·  社区

AgentKit 提供更确定、更灵活的路由，兼容多家模型提供商，拥抱 MCP（以实现丰富的工具支持），并支持不断壮大、充满活力的 TypeScript AI 开发者社区。结合 Inngest 开发服务器，您可以在本地快速启动项目，并利用其编排引擎使您的智能体在部署到云端时具备容错能力。

核心概念

• 智能体：可与提示词、工具以及 MCP 结合使用的 LLM 调用。
• 网络：一种让智能体通过共享状态协作的简单方式，包括任务交接。
• 状态：将对话历史与完全类型化的状态机相结合，用于路由决策。
• 路由器：自主性的核心所在，从基于代码的编排到基于 LLM 的编排（例如 ReAct）。
• 追踪：借助内置追踪功能，在本地和云端调试与优化工作流。

立即开始吧！您可以 克隆我们的示例 或 浏览文档。

快速入门

npm i @inngest/agent-kit inngest

注意：自 AgentKit v0.9.0 起，您需要将 inngest 作为独立依赖项与 @inngest/agent-kit 一同安装。这样做可以确保运行时兼容性，并避免多个包依赖不同版本的 Inngest 时产生冲突。

MCP 智能体示例

在 Smithery 上选择您喜爱的 MCP 服务器（或自行托管一个），即可使用 MCP 作为工具构建 AgentKit 智能体。以下是一个使用 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: `你是一位帮助管理 Neon 账户的助手。
  重要提示：问题解答完毕后，请调用 'done' 工具。
  `,
  tools: [
    createTool({
      name: "done",
      description: "当任务完成后调用此工具。",
      parameters: z.object({
        answer: z.string().describe("用户问题的答案。"),
      }),
      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;
  },
});

// 创建并启动服务器
const server = createServer({
  networks: [neonAgentNetwork],
});

server.listen(3010, () =>
  console.log("Support Agent 示例服务器正在端口 3010 运行")
);

您可以通过以下链接在本地运行此示例：https://github.com/inngest/agent-kit/tree/main/examples/mcp-neon-agent#readme

更多示例请参见下文。

基于状态的确定性路由

AgentKit 提供了一种独特的基于状态的确定性路由方法，能够在全程可控的前提下实现从基于代码的路由到完全自主路由的过渡。

状态是同一网络中所有智能体之间存储和共享的关键值。

该状态可被路由器、智能体生命周期回调、智能体提示词以及智能体工具访问：

flowchart LR
	subgraph 网络
		state["状态"]
		subgraph 智能体
			systemp["系统提示词"]
			tools["工具"]
			lifecycle["生命周期回调"]
		end
		router["路由器"]
	end


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

双向箭头表示读写访问权限，而单向箭头则表示只读访问权限。

这种共享状态与网络的消息历史相结合，构成了 AgentKit 确定性基于状态路由的基础。

基于代码的路由

我们建议从基于代码的路由开始，它能让你对网络的执行流程拥有完全的控制权。

这种路由模式是最具确定性的。通过提供一个能够访问状态和历史记录的路由函数，你可以实现一种智能体式的路由机制，该机制会根据智能体工具所执行的状态更新做出响应。

以下是一个编码智能体的例子，它使用基于代码的路由器，根据 codeAssistantAgent 生成的计划来编排网络中的各个智能体：

import { z } from "zod";
import {
  anthropic,
  createAgent,
  createNetwork,
  createTool,
} from "@inngest/agent-kit";

import { readFileSync } from "fs";
import { join } from "path";

// 创建一个共享工具
const saveSuggestions = createTool({
  name: "save_suggestions",
  description: "将其他智能体提出的建议保存到状态中",
  parameters: z.object({
    suggestions: z.array(z.string()),
  }),
  handler: async (input, { network }) => {
    const suggestions = network?.state.kv.get("suggestions") || [];
    network?.state.kv.set("suggestions", [
      ...suggestions,
      ...input.suggestions,
    ]);
    return "建议已保存！";
  },
});

// 创建可使用 `saveSuggestions` 工具访问状态的智能体
const documentationAgent = createAgent({
  name: "documentation_agent",
  system: "你是一位代码文档生成专家",
  tools: [saveSuggestions],
});

const analysisAgent = createAgent({
  name: "analysis_agent",
  system: "你是一位代码分析和改进建议专家",
  tools: [saveSuggestions],
});

const summarizationAgent = createAgent({
  name: "summarization_agent",
  system: ({ network }) => {
    const suggestions = network?.state.kv.get("suggestions") || [];
    return `请保存以下建议的摘要：
    ${suggestions.join("\n")}`;
  },
  tools: [
    createTool({
      name: "save_summary",
      description:
        "将其他智能体提出的建议摘要保存到状态中",
      parameters: z.object({
        summary: z.string(),
      }),
      handler: async (input, { network }) => {
        network?.state.kv.set("summary", input.summary);
        return "已保存！";
      },
    }),
  ],
});

// 创建生成计划的代码助手智能体
const codeAssistantAgent = createAgent({
  name: "code_assistant_agent",
  system: ({ network }) => {
    const agents = Array.from(network?.agents.values() || [])
      .filter(
        (agent) =>
          !["code_assistant_agent", "summarization_agent"].includes(agent.name)
      )
      .map((agent) => `${agent.name} (${agent.system})`);
    return `根据用户请求，仅执行以下工具调用：
- 读取文件内容
- 根据以下列表生成要运行的智能体计划：${agents.join(", ")}

完成后回答“完成”。`;
  },
  tools: [
    createTool({
      name: "read_file",
      description: "读取当前目录下的文件",
      parameters: z.object({
        filename: z.string(),
      }),
      handler: async (input, { network }) => {
        const filePath = join(process.cwd(), `files/${input.filename}`);
        const code = readFileSync(filePath, "utf-8");
        network?.state.kv.set("code", code);
        return "文件已读取！";
      },
    }),
    createTool({
      name: "generate_plan",
      description: "生成要运行的智能体计划",
      parameters: z.object({
        plan: z.array(z.string()),
      }),
      handler: async (input, { network }) => {
        network?.state.kv.set("plan", input.plan);
        return "计划已生成！";
      },
    }),
  ],
});

const network = createNetwork({
  name: "code-assistant-v2",
  agents: [
    codeAssistantAgent,
    documentationAgent,
    analysisAgent,
    summarizationAgent,
  ],
  // 我们的路由函数依赖共享状态来编排智能体
  //   首先调用 codeAssistantAgent，然后逐步执行其计划，
  //   直到摘要被写入状态。
  router: ({ network }) => {
    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();
      if (nextAgent) {
        network?.state.kv.set("plan", plan);
        return network?.agents.get(nextAgent);
      } else if (!network?.state.kv.has("summary")) {
        return summarizationAgent;
      } else {
        return undefined;
      }
    }
  },
  defaultModel: anthropic({
    model: "claude-3-5-sonnet-latest",
    defaultParameters: {
      max_tokens: 4096,
    },
  }),
});

源代码可在以下链接查看：https://github.com/inngest/agent-kit/blob/main/examples/code-assistant-agentic/src/index.ts

基于代理的路由

基于代理的路由用一个代理来替代传统的路由功能。这使得您的代理网络能够自主选择要执行的代理，并决定任务何时完成。

路由代理配备了一个 onRoute 生命周期回调，它沿用了基于代码的路由方法。这个生命周期回调是您掌控代理路由决策的入口。

下面的示例展示了一个支持代理，它使用路由代理作为“主管”：

import {
  anthropic,
  createAgent,
  createNetwork,
  createRoutingAgent,
  createTool,
} from "@inngest/agent-kit";
import { z } from "zod";

import { isLastMessageOfType, lastResult } from "./utils.js";

import { knowledgeBaseDB, releaseNotesDB, ticketsDB } from "./databases.js";

// 创建共享工具
const searchKnowledgeBase = createTool({
  name: "search_knowledge_base",
  description: "在知识库中搜索相关文章",
  parameters: z.object({
    query: z.string().describe("搜索查询"),
  }),
  handler: async ({ query }, { step }) => {
    return await step?.run("search_knowledge_base", async () => {
      // 模拟知识库搜索
      const results = knowledgeBaseDB.filter(
        (article) =>
          article.title.toLowerCase().includes(query.toLowerCase()) ||
          article.content.toLowerCase().includes(query.toLowerCase())
      );
      return results;
    });
  },
});

const searchLatestReleaseNotes = createTool({
  name: "search_latest_release_notes",
  description: "在最新发布说明中搜索相关文章",
  parameters: z.object({
    query: z.string().describe("搜索查询"),
  }),
  handler: async ({ query }, { step }) => {
    return await step?.run("search_latest_release_notes", async () => {
      // 模拟知识库搜索
      const results = releaseNotesDB.filter(
        (releaseNote) =>
          releaseNote.title.toLowerCase().includes(query.toLowerCase()) ||
          releaseNote.content.toLowerCase().includes(query.toLowerCase())
      );
      return results;
    });
  },
});

const getTicketDetails = async (ticketId: string) => {
  const ticket = ticketsDB.find((t) => t.id === ticketId);
  return ticket || { error: "工单未找到" };
};

// 创建我们的代理
const customerSupportAgent = createAgent({
  name: "客户支持",
  description:
    "我是一名客户支持代理，帮助客户解答疑问。",
  system: `你是一位乐于助人的客户支持代理。
你的目标是协助客户解决他们的问题和疑虑。
请以专业、礼貌和详尽的方式回复。`,
  model: anthropic({
    model: "claude-3-5-haiku-latest",
    defaultParameters: {
      max_tokens: 1000,
    },
  }),
  tools: [
    searchKnowledgeBase,
    createTool({
      name: "update_ticket",
      description: "更新工单备注",
      parameters: z.object({
        ticketId: z.string().describe("要更新的工单ID"),
        priority: z.string().describe("工单优先级"),
        status: z.string().describe("工单状态"),
        note: z.string().describe("要添加到工单的备注"),
      }),
      handler: async ({ ticketId, priority, status, note }, { step }) => {
        return await step?.run("update_ticket", async () => {
          // TODO: 更新数据库中的工单
          return { message: "工单更新成功" };
        });
      },
    }),
  ],
});

const technicalSupportAgent = createAgent({
  name: "技术支持",
  description: "我是一名技术支持代理，负责处理紧急工单。",
  system: `你是一位技术支持专家。
你的目标是帮助解决紧急工单。
运用你的专业知识诊断问题并提出解决方案。`,
  model: anthropic({
    model: "claude-3-5-haiku-latest",
    defaultParameters: {
      max_tokens: 1000,
    },
  }),
  tools: [searchLatestReleaseNotes],
});

// 创建我们的路由代理，用于编排代理网络
// 并评估是否已回答支持请求。
const supervisorRoutingAgent = createRoutingAgent({
  name: "主管",
  description: "我是一名支持主管。",
  system: `你是一位主管。
你的目标是回答客户的初始请求，或者在无法提供答案时升级工单。
请根据以下指示将工单路由到合适的代理：
- 紧急工单应路由到“技术支持”代理。
- 更新工单或处理非紧急工单等操作应路由到“客户支持”代理。

请逐步思考并理性做出决策。
当某个代理已经回答了工单的初始请求或更新了工单时，请调用“done”工具。`,
  model: anthropic({
    model: "claude-3-5-haiku-latest",
    defaultParameters: {
      max_tokens: 1000,
    },
  }),
  tools: [
    createTool({
      name: "done",
      description: "在工单解决或升级时调用此工具",
      handler: async () => {},
    }),
    createTool({
      name: "route_to_agent",
      description: "将工单路由到合适的代理",
      parameters: z.object({
        agent: z.string().describe("要路由到的代理名称"),
      }),
      handler: async ({ agent }) => {
        return agent;
      },
    }),
  ],
  lifecycle: {
    onRoute: ({ result, network }) => {
      const lastMessage = lastResult(network?.state.results);

      // 如果之前调用了工具，确保返回到上一个执行的代理
      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;
      } else if (toolName === "route_to_agent") {
        if (
          typeof tool.content === "object" &&
          tool.content !== null &&
          "data" in tool.content &&
          typeof tool.content.data === "string"
        ) {
          return [tool.content.data];
        }
      }
      return;
    },
  },
});

// 创建包含路由代理的支持网络
const supportNetwork = createNetwork({
  name: "支持网络",
  agents: [customerSupportAgent, technicalSupportAgent],
  defaultModel: anthropic({
    model: "claude-3-5-haiku-latest",
    defaultParameters: {
      max_tokens: 1000,
    },
  }),
  router: supervisorRoutingAgent,
});

您可以在本地尝试这个代理网络：https://github.com/inngest/agent-kit/tree/main/examples/support-agent-human-in-the-loop#readme

两种方法都兼容 maxIter 参数，该参数允许您设置网络迭代的最大次数。 我们建议在使用基于代理的路由时，始终设置一个 master 值。

示例

• AgentKit SWE-bench 示例 展示了如何构建一个由多个智能体组成的网络，以解决复杂的 SWE bench 挑战。
• 简单搜索智能体 能够自主地浏览网页，回答给定的问题。
• 支持智能体 展示了 Inngest 的 waitForEvent() 如何使智能体能够请求人类的帮助。
• E2B 编码智能体 复现了 Cursor 的 Agent 模式，仅凭一个简单的提示就能创建出完整的项目。
• Daytona 编码智能体 可以创建 Web 应用、运行测试、执行脚本等，并且还具备自动检测开发服务器和生成预览的功能。

贡献

克隆仓库后：

1. 确保已安装 node 和 pnpm：

node -v # 应该是 > 20.x

pnpm -v # 应该是 > 9.x

2. 安装依赖：

pnpm i

3. 构建包或运行测试：

pnpm build

pnpm test

许可证

Apache 2.0

AgentKit 快速上手指南

AgentKit 是一个用于构建多智能体（Multi-Agent）网络的开源框架。它支持确定性路由、丰富的工具集成（通过 MCP 协议），并结合 Inngest 引擎确保工作流在云端部署时的容错性。

环境准备

在开始之前，请确保您的开发环境满足以下要求：

• Node.js: 建议安装 LTS 版本（v18 或更高）。
• 包管理器: npm, yarn, pnpm 或 bun。
• API Keys: 准备好您使用的 LLM 提供商（如 Anthropic, OpenAI 等）的 API 密钥。
• MCP Server (可选): 如果需要使用模型上下文协议（MCP）工具，需配置相应的 MCP 服务器地址。

注意：从 AgentKit v0.9.0 开始，inngest 必须作为独立的依赖项安装，以确保运行时兼容性。

安装步骤

使用 npm 安装核心库和运行时引擎：

npm i @inngest/agent-kit inngest

如果您使用其他包管理器，命令如下：

• yarn: yarn add @inngest/agent-kit inngest
• pnpm: pnpm add @inngest/agent-kit inngest

基本使用

以下是一个最简化的示例，展示如何创建一个基于 MCP 工具的单个智能体，并将其放入网络中运行。本例使用了 Neon 数据库的 MCP 服务作为工具来源。

1. 创建入口文件

新建一个文件（例如 index.ts），并填入以下代码：

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";

// 配置 MCP 服务器地址 (此处以 Neon 为例)
const neonServerUrl = createSmitheryUrl(
  "https://server.smithery.ai/neon/mcp?profile=bored-catshark-da8hf&api_key=YOUR_API_KEY"
);

// 定义智能体
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);
      },
    }),
  ],
  // 挂载 MCP 服务器作为工具集
  mcpServers: [
    {
      name: "neon",
      transport: {
        type: "streamable-http",
        url: neonServerUrl.toString(),
      },
    },
  ],
});

// 创建智能体网络
const neonAgentNetwork = createNetwork({
  name: "neon-agent-network",
  agents: [neonAgent],
  defaultModel: anthropic({
    model: "claude-3-5-sonnet-20240620",
    defaultParameters: {
      max_tokens: 1000,
    },
  }),
  // 简单的确定性路由：如果没有答案，则调用 neonAgent
  router: ({ network }) => {
    if (!network?.state.kv.get("answer")) {
      return neonAgent;
    }
    return; // 任务完成，结束路由
  },
});

// 启动本地服务器
const server = createServer({
  networks: [neonAgentNetwork],
});

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

2. 配置环境变量

确保在终端或 .env 文件中设置必要的 API 密钥（根据您的模型提供商和 MCP 服务调整）：

export ANTHROPIC_API_KEY="your_anthropic_key"
# 如果使用 Smithery 或其他 MCP 服务，可能还需要配置相关 Key

3. 运行项目

使用 TypeScript 运行环境（如 tsx 或 ts-node）启动服务：

npx tsx index.ts

启动成功后，控制台将显示： AgentKit server is running on port 3010

此时，您可以结合 Inngest Dev Server 在本地调试工作流，或通过 HTTP 请求触发智能体网络。

核心概念简述

• Agents: 封装了 LLM 调用、提示词和工具（包括 MCP 工具）的基本单元。
• Networks: 让多个智能体协作的容器，它们共享一个类型安全的 State（状态）。
• Routers: 决定下一个执行哪个智能体的逻辑。可以是纯代码控制（确定性最高），也可以由另一个 LLM 智能体自主决定。
• State: 键值对存储，用于在智能体之间传递数据和记忆，是实现复杂工作流编排的关键。

更多高级用法（如多智能体协作、代码级路由编排）请参考官方文档或 GitHub 仓库中的 examples 目录。