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

AgentKit is a powerful framework for building sophisticated multi-agent networks. It distinguishes itself by offering deterministic and flexible routing, compatibility with multiple model providers, and deep integration with the Model Context Protocol (MCP) for rich tooling. Built for the thriving TypeScript AI community, it combines seamlessly with the Inngest Dev Server for local development and leverages Inngest's orchestration engine to ensure your agents are fault-tolerant when deployed to the cloud.

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

Core Concepts

To effectively use AgentKit, it's essential to understand its foundational building blocks.

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

Agents

An Agent is an LLM call that can be enhanced with prompts, tools, and MCP servers. It represents a single, specialized actor within a network.

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

Networks

A Network is a structured way for multiple Agents to collaborate. It provides a shared State and facilitates handoff between agents, enabling complex workflows.

网络（Network）是多个智能体进行协作的结构化方式。它提供一个共享的状态（State）结合对话历史和类型化状态机的共享存储，用于在智能体之间传递信息和控制路由决策。，并促进智能体之间的交接，从而实现复杂的工作流。

State

The State combines the conversation history with a fully typed state machine. It is central to routing decisions and is shared across all Agents within the same network.

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

Routers

Routers are where the autonomy of the system lives. They determine which Agent should act next, ranging from purely code-based logic to LLM-based orchestration (e.g., ReAct patterns).

路由器（Routers）控制智能体执行流程的组件，支持从代码驱动到智能体驱动的多种路由模式，实现工作流的自主性。是系统自主性的体现。它们决定下一个应该执行哪个智能体，其逻辑范围可以从纯代码基础到基于 LLM 的编排（例如 ReAct 模式）。

Tracing

Built-in tracing allows you to debug and optimize your agent workflows both locally and in the cloud, providing visibility into each step of execution.

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

Getting Started

Begin by installing the necessary packages.

首先安装必要的包。

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 excels at integrating MCP servers as tools. Below is an example using a Neon database MCP server.

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

You can get started with this example locally via the GitHub repository.

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

Deterministic Routing with State-Based Logic

AgentKit's unique strength lies in its deterministic, state-based routing. This approach allows you to implement workflows ranging from fully code-controlled to autonomous while maintaining oversight throughout.

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

The State is a key-value store shared among all Agents in a network. It is accessible from the router, agent lifecycle callbacks, agent prompts, and agent tools, forming the backbone of intelligent orchestration.

状态（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

Bidirectional arrows indicate read/write access, while one-way arrows indicate read-only access. This shared State, combined with message history, is the foundation for deterministic routing.

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

Code-Based Routing

We recommend starting with code-based routing for complete control over your network's execution flow. This is the most deterministic pattern, where a routing function reacts to state updates made by agent tools.

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

The following example shows a coding assistant network where a router orchestrates agents based on a plan generated by a codeAssistantAgent.

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

(The example code for the code assistant network is extensive, demonstrating the creation of multiple agents (documentationAgent, analysisAgent, summarizationAgent, codeAssistantAgent) with shared tools, and a router function that sequentially executes agents based on a stored plan. The key takeaway is the router's logic, which checks the shared state (code, plan, summary) to decide the next agent to run.)

（编码助手网络的示例代码较为详尽，演示了如何创建具有共享工具的多个智能体（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 ...
});

View the full source code: Code Assistant Example

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

Agent-Based Routing

Agent-based routing replaces the routing function with a specialized Routing Agent. This enables the network to autonomously select which agent to execute and decide when tasks are complete. Control is maintained through an onRoute lifecycle callback.

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

The example below showcases a Support Agent network using a "Supervisor" Routing Agent.

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

(This example creates customerSupportAgent and technicalSupportAgent, along with a supervisorRoutingAgent. The supervisor uses tools like route_to_agent and done to make decisions. The onRoute callback contains logic to interpret the supervisor's tool calls and return the name of the next agent to execute, ensuring the routing loop continues correctly.)

（此示例创建了 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 ...
});

Try this example locally: Support Agent Example

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

Recommendation: Both routing approaches are compatible with a maxIter parameter to limit network iterations. It is highly recommended to set this limit when using agent-based routing.

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

Example Showcase

AgentKit's versatility is demonstrated through several sophisticated examples:

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

• SWE-bench Agent: Solves complex software engineering challenges from the SWE-bench benchmark.

  SWE-bench 智能体：解决来自 SWE-bench 基准测试的复杂软件工程挑战。

• Simple Search Agent: Autonomously navigates the web to answer questions.

  简单搜索智能体：自主浏览网络以回答问题。

• Support Agent: Integrates human-in-the-loop functionality using Inngest's waitForEvent().

  支持智能体：使用 Inngest 的 waitForEvent() 集成人在回路功能。

• E2B Coding Agent: Replicates Cursor's Agent mode to create complete projects from a prompt.

  E2B 编码智能体：复制 Cursor 的 Agent 模式，根据提示创建完整项目。

• Daytona Coding Agent: Creates web apps, runs tests, executes scripts, and features automated dev server detection.

  Daytona 编码智能体：创建 Web 应用、运行测试、执行脚本，并具备自动化开发服务器检测功能。

Conclusion

AgentKit provides a robust, flexible, and developer-friendly foundation for building deterministic multi-agent systems. By combining shared state, multiple routing strategies, MCP integration, and cloud-native resilience, it empowers developers to create sophisticated AI workflows with confidence. Start building by exploring the documentation and cloning the examples.

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

(Note: Due to length, detailed contributing guidelines and license information have been summarized. The original content indicated the project uses Apache 2.0 license and standard Node.js/PNPM setup for development.)

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