nccasia开源的agent-sdk采用PreAct架构，让开发者完全掌控AI代理的推理流程——从上下文选择到执行路径，告别"把回合交给模型并祈祷"的黑箱模式。

• 原作者/维护者：nccasia
• 来源平台：github
• 原始标题：agent-sdk — PreAct: A pre-structured, fully inspectable agent-reasoning engine
• 原始链接：https://github.com/nccasia/agent-sdk
• 来源发布时间/更新时间：2026-06-13T04:15:27Z

PreAct：一个可完全掌控的AI代理推理引擎\n\n在当前的AI代理开发领域，大多数开发者面临一个共同的困境：他们将任务交给大语言模型，然后只能祈祷模型做出正确的决策。这种"自由行动"（ReAct）模式虽然简单，但缺乏可控性和可解释性。nccasia团队开源的agent-sdk项目正是为了解决这一问题而生，它采用了一种名为PreAct的全新架构，让开发者能够完全掌控代理的每一个推理环节。\n\n## 原作者与来源\n\n- 原作者/维护者: nccasia\n- 来源平台: GitHub\n- 原始标题: agent-sdk — PreAct\n- 原始链接: https://github.com/nccasia/agent-sdk\n- 发布时间: 2026年6月\n\n## 为什么需要PreAct？\n\n传统的AI代理通常采用ReAct（Reasoning + Acting）模式：模型在每一轮对话中自行决定调用什么工具，提示词随之不断累积直至达到上下文限制。这种方式存在几个明显的问题：\n\n1. 黑箱决策：开发者无法预知模型会如何选择工具\n2. 上下文膨胀：提示词持续累积，效率逐渐降低\n3. 难以调试：当代理行为异常时，很难定位问题所在\n4. 缺乏可复现性：相同的输入可能产生不同的执行路径\n\nPreAct的核心理念是预结构化推理——在执行之前，就明确定义好代理的思考路径和执行流程。\n\n## PreAct架构的核心概念\n\nPreAct将代理的推理过程抽象为两个正交的维度：上下文维度（OY轴）和时间维度（OX轴），并在之上叠加了一个元认知层。\n\n### 上下文维度：Lobe（脑叶）\n\nLobe是PreAct中的基本思考单元，负责为特定的任务片段选择上下文和局部行为。与传统的"全能提示词"不同，每个lobe只关注特定的功能领域：\n\n- 认知脑叶（Cognition）：提供推理的核心骨架——浓缩→界定→分类→规划→研究→综合\n- 工具脑叶（Tools）：管理自适应工具暴露\n- 技能脑叶（Skills）：处理渐进式能力展示\n- 记忆脑叶（Memory）：负责信息回忆\n- 回复脑叶（Reply）：处理最终响应生成\n\n这种设计使得上下文能够被重新分层（re-tier），每一跳都根据需要进行注入、提示+获取或卸载，从而最大化每token的推理效用。\n\n### 时间维度：Stage与Flow\n\n**Stage（阶段）**是代理执行的具体步骤，每个阶段拥有自己的lobe切片、循环模式、工具白名单和模型配置。**Flow（流程）**则是一系列stage的有序组合，代表一条完整的执行路径。\n\n例如，一个典型的编码代理可能包含以下flow：\n\ntriage → explore → plan → implement → verify\n\n\n每个阶段都可以独立优化，而不会影响其他阶段的表现。这种模块化设计让新能力的添加变成简单的注册操作，而非解释器的分支修改。\n\n### 元认知层：Metacognition\n\nPreAct的元认知层始终处于激活状态（monitor → regulate），它可以：\n\n- 调整lobe切片\n- 重试失败的步骤\n- 跳过不必要的步骤\n\n但重要的是，它永远不会让LLM来评判整个流程，也不会跳过被固定的安全步骤（如cite和filter）。\n\n## 核心特性一览\n\nagent-sdk提供了丰富的功能特性，使其成为构建生产级AI代理的有力工具：\n\n### 1. 完全可检查的推理过程\n\n每一轮执行都会生成结构化的追踪记录，包括路径、流程、每阶段的提示词、lobe激活情况、工具调用、元认知决策和token成本。这些追踪可以被渲染为独立的HTML查看器，彻底告别黑箱。\n\n### 2. 插件化架构\n\n整个能力可以被封装为单个插件（包含lobes、stages、flows、tools，甚至MCP服务器），然后挂载、禁用或替换。核心SDK本身不包含任何领域特定的代码。\n\n内置插件包括：\n- SafetyPlugin：提供cite和filter的grounding能力\n- FormatPlugin：处理频道、语言和语气样式\n- TaskPlugin：支持todo驱动的多阶段任务执行\n- PluginMCP：挂载MCP服务器\n- PluginWorkspace：提供沙盒化文件系统\n- PluginOTel：OpenTelemetry集成\n- PluginGuardrails：前置/后置检查\n\n### 3. 持久化与长任务支持\n\n通过作用域化的memory工具（turn → conversation → channel → user → bot）和任务模式，代理可以持久化工作状态并在多次运行间恢复。这对于需要长时间执行的复杂任务至关重要。\n\n### 4. 供应商无关的客户端\n\nSDK支持Anthropic、OpenAI兼容接口、MiniMax等多种LLM供应商，所有客户端都遵循统一的接口设计。此外还提供确定性的FakeClient用于测试，无需网络连接即可运行。\n\n### 5. 可基准测试\n\n项目包含实时的基准测试（taskbench、coding-agent-bench），用可验证的结果而非存根来评估真实行为。\n\n## 快速上手\n\n安装SDK非常简单：\n\nbash\npip install agent-sdk # 核心\npip install \"agent-sdk[openai]\" # + OpenAI兼容客户端\npip install \"agent-sdk[redis]\" # + Redis会话/内存存储\npip install \"agent-sdk[openai,redis]\" # 完整安装\n\n\n创建一个简单的代理：\n\npython\nfrom agent_sdk import PreactAgent, tool\nfrom agent_sdk.clients import AnthropicClient\n\n@tool\nasync def search(query: str, top_k: int = 5) -> str:\n \"\"\"搜索知识库。\"\"\"\n\nagent = PreactAgent(\n client=AnthropicClient(\"claude-opus-4-8\"),\n instructions=\"你是一个有用的研究助手。\",\n tools=[search],\n)\n\n# 单次查询\nresult = await agent.query(\"v2有什么变化？\")\n\n# 流式输出\nasync for event in agent.act(\"v2有什么变化？\"):\n print(event)\n\n\n## 实际案例：编码代理\n\n项目包含一个完整的编码代理示例（examples/coding-agent/），展示了如何用约300行代码构建一个多阶段编码代理，涵盖从问题分类到代码实现和验证的完整流程。该示例包含离线确定性演示和--inspect路由探针功能。\n\n## 技术哲学：可控性优先\n\nagent-sdk的设计哲学非常明确：让开发者拥有代理的每一个构建块。这与当前主流的"提示工程+祈祷"模式形成鲜明对比。PreAct架构认为，代理的推理过程应该是：\n\n1. 可预测的：相同的输入总是产生相同的执行路径\n2. 可调试的：每一步的决策都是透明可见的\n3. 可优化的：可以针对特定阶段进行调优而不影响整体\n4. 可组合的：新能力以插件形式添加，而非侵入式修改\n\n这种设计理念特别适合需要高可靠性、可审计性的企业级应用场景。\n\n## 项目状态与展望\n\n目前agent-sdk处于beta阶段，采用Apache 2.0许可证开源。项目结构清晰，核心代码位于agent_sdk/目录下，包含：\n\n- agent.py：主入口PreactAgent\n- engine.py：执行引擎\n- lobes/：内置lobe网络\n- plugins/：插件系统\n- clients/：多供应商LLM客户端\n- memory/：记忆系统\n- tools.py：工具框架\n\n项目还提供了完整的文档（docs/目录）和基准测试（benchmarks/目录），为开发者提供了充分的学习和评估资源。\n\n## 总结\n\nnccasia的agent-sdk通过PreAct架构为AI代理开发带来了一种新的范式。它不是又一个包装了API的简易SDK，而是一个让开发者真正掌控代理行为的工程框架。对于那些厌倦了黑箱模型决策、希望构建可预测、可调试、可扩展的AI代理的开发者来说，agent-sdk无疑是一个值得深入研究的工具。\n\n在AI代理从实验走向生产的过程中，可控性和可解释性将成为关键考量。PreAct所倡导的"预结构化推理"理念，或许正是下一代代理架构的重要方向。

原作者与来源

• 原作者/维护者：nccasia
• 来源平台：github
• 原始标题：agent-sdk — PreAct: A pre-structured, fully inspectable agent-reasoning engine
• 原始链接：https://github.com/nccasia/agent-sdk
• 来源发布时间/更新时间：2026-06-13T04:15:27Z PreAct：一个可完全掌控的AI代理推理引擎\n\n在当前的AI代理开发领域，大多数开发者面临一个共同的困境：他们将任务交给大语言模型，然后只能祈祷模型做出正确的决策。这种"自由行动"（ReAct）模式虽然简单，但缺乏可控性和可解释性。nccasia团队开源的agent-sdk项目正是为了解决这一问题而生，它采用了一种名为PreAct的全新架构，让开发者能够完全掌控代理的每一个推理环节。\n\n原作者与来源\n\n- 原作者/维护者: nccasia\n- 来源平台: GitHub\n- 原始标题: agent-sdk — PreAct\n- 原始链接: https://github.com/nccasia/agent-sdk\n- 发布时间: 2026年6月\n\n为什么需要PreAct？\n\n传统的AI代理通常采用ReAct（Reasoning + Acting）模式：模型在每一轮对话中自行决定调用什么工具，提示词随之不断累积直至达到上下文限制。这种方式存在几个明显的问题：\n\n1. 黑箱决策：开发者无法预知模型会如何选择工具\n2. 上下文膨胀：提示词持续累积，效率逐渐降低\n3. 难以调试：当代理行为异常时，很难定位问题所在\n4. 缺乏可复现性：相同的输入可能产生不同的执行路径\n\nPreAct的核心理念是预结构化推理——在执行之前，就明确定义好代理的思考路径和执行流程。\n\nPreAct架构的核心概念\n\nPreAct将代理的推理过程抽象为两个正交的维度：上下文维度（OY轴）和时间维度（OX轴），并在之上叠加了一个元认知层。\n\n上下文维度：Lobe（脑叶）\n\nLobe是PreAct中的基本思考单元，负责为特定的任务片段选择上下文和局部行为。与传统的"全能提示词"不同，每个lobe只关注特定的功能领域：\n\n- 认知脑叶（Cognition）：提供推理的核心骨架——浓缩→界定→分类→规划→研究→综合\n- 工具脑叶（Tools）：管理自适应工具暴露\n- 技能脑叶（Skills）：处理渐进式能力展示\n- 记忆脑叶（Memory）：负责信息回忆\n- 回复脑叶（Reply）：处理最终响应生成\n\n这种设计使得上下文能够被重新分层（re-tier），每一跳都根据需要进行注入、提示+获取或卸载，从而最大化每token的推理效用。\n\n时间维度：Stage与Flow\n\n**Stage（阶段）**是代理执行的具体步骤，每个阶段拥有自己的lobe切片、循环模式、工具白名单和模型配置。**Flow（流程）**则是一系列stage的有序组合，代表一条完整的执行路径。\n\n例如，一个典型的编码代理可能包含以下flow：\n\ntriage → explore → plan → implement → verify\n\n\n每个阶段都可以独立优化，而不会影响其他阶段的表现。这种模块化设计让新能力的添加变成简单的注册操作，而非解释器的分支修改。\n\n元认知层：Metacognition\n\nPreAct的元认知层始终处于激活状态（monitor → regulate），它可以：\n\n- 调整lobe切片\n- 重试失败的步骤\n- 跳过不必要的步骤\n\n但重要的是，它永远不会让LLM来评判整个流程，也不会跳过被固定的安全步骤（如cite和filter）。\n\n核心特性一览\n\nagent-sdk提供了丰富的功能特性，使其成为构建生产级AI代理的有力工具：\n\n1. 完全可检查的推理过程\n\n每一轮执行都会生成结构化的追踪记录，包括路径、流程、每阶段的提示词、lobe激活情况、工具调用、元认知决策和token成本。这些追踪可以被渲染为独立的HTML查看器，彻底告别黑箱。\n\n2. 插件化架构\n\n整个能力可以被封装为单个插件（包含lobes、stages、flows、tools，甚至MCP服务器），然后挂载、禁用或替换。核心SDK本身不包含任何领域特定的代码。\n\n内置插件包括：\n- SafetyPlugin：提供cite和filter的grounding能力\n- FormatPlugin：处理频道、语言和语气样式\n- TaskPlugin：支持todo驱动的多阶段任务执行\n- PluginMCP：挂载MCP服务器\n- PluginWorkspace：提供沙盒化文件系统\n- PluginOTel：OpenTelemetry集成\n- PluginGuardrails：前置/后置检查\n\n3. 持久化与长任务支持\n\n通过作用域化的memory工具（turn → conversation → channel → user → bot）和任务模式，代理可以持久化工作状态并在多次运行间恢复。这对于需要长时间执行的复杂任务至关重要。\n\n4. 供应商无关的客户端\n\nSDK支持Anthropic、OpenAI兼容接口、MiniMax等多种LLM供应商，所有客户端都遵循统一的接口设计。此外还提供确定性的FakeClient用于测试，无需网络连接即可运行。\n\n5. 可基准测试\n\n项目包含实时的基准测试（taskbench、coding-agent-bench），用可验证的结果而非存根来评估真实行为。\n\n快速上手\n\n安装SDK非常简单：\n\nbash\npip install agent-sdk 核心\npip install \"agent-sdk[openai]\" + OpenAI兼容客户端\npip install \"agent-sdk[redis]\" + Redis会话/内存存储\npip install \"agent-sdk[openai,redis]\" 完整安装\n\n\n创建一个简单的代理：\n\npython\nfrom agent_sdk import PreactAgent, tool\nfrom agent_sdk.clients import AnthropicClient\n\n@tool\nasync def search(query: str, top_k: int = 5) -> str:\n \"\"\"搜索知识库。\"\"\"\n\nagent = PreactAgent(\n client=AnthropicClient(\"claude-opus-4-8\"),\n instructions=\"你是一个有用的研究助手。\",\n tools=[search],\n)\n\n单次查询\nresult = await agent.query(\"v2有什么变化？\")\n\n流式输出\nasync for event in agent.act(\"v2有什么变化？\"):\n print(event)\n\n\n实际案例：编码代理\n\n项目包含一个完整的编码代理示例（examples/coding-agent/），展示了如何用约300行代码构建一个多阶段编码代理，涵盖从问题分类到代码实现和验证的完整流程。该示例包含离线确定性演示和--inspect路由探针功能。\n\n技术哲学：可控性优先\n\nagent-sdk的设计哲学非常明确：让开发者拥有代理的每一个构建块。这与当前主流的"提示工程+祈祷"模式形成鲜明对比。PreAct架构认为，代理的推理过程应该是：\n\n1. 可预测的：相同的输入总是产生相同的执行路径\n2. 可调试的：每一步的决策都是透明可见的\n3. 可优化的：可以针对特定阶段进行调优而不影响整体\n4. 可组合的：新能力以插件形式添加，而非侵入式修改\n\n这种设计理念特别适合需要高可靠性、可审计性的企业级应用场景。\n\n项目状态与展望\n\n目前agent-sdk处于beta阶段，采用Apache 2.0许可证开源。项目结构清晰，核心代码位于agent_sdk/目录下，包含：\n\n- agent.py：主入口PreactAgent\n- engine.py：执行引擎\n- lobes/：内置lobe网络\n- plugins/：插件系统\n- clients/：多供应商LLM客户端\n- memory/：记忆系统\n- tools.py：工具框架\n\n项目还提供了完整的文档（docs/目录）和基准测试（benchmarks/目录），为开发者提供了充分的学习和评估资源。\n\n总结\n\nnccasia的agent-sdk通过PreAct架构为AI代理开发带来了一种新的范式。它不是又一个包装了API的简易SDK，而是一个让开发者真正掌控代理行为的工程框架。对于那些厌倦了黑箱模型决策、希望构建可预测、可调试、可扩展的AI代理的开发者来说，agent-sdk无疑是一个值得深入研究的工具。\n\n在AI代理从实验走向生产的过程中，可控性和可解释性将成为关键考量。PreAct所倡导的"预结构化推理"理念，或许正是下一代代理架构的重要方向。