Agentspan

Agentspan 是人工智能代理的开源执行层，其工作必须能够承受流程崩溃、部署、长时间等待和人工批准。它不是将整个代理循环保留在应用程序内存中，而是将执行状态存储在 Agentspan 服务器上，并将工具工作委托给连接的工作人员。该项目由 Orkes 在 Conductor 工作流引擎上构建，目前已获得 MIT 许可并可自行托管。

区别很重要：Agentspan 不会使弱代理变得智能、选择安全权限或验证业务结果。它改变了故障模型。运行获得持久的身份，已完成的步骤具有历史记录，待批准可以在服务器端等待，并且替换工作人员可以重新连接。团队应该将其视为分布式系统基础设施，而不是提示库。

当状态移出代理进程时会发生什么变化

运行时路径，绘制为故障边界

 用户/事件
      |
      v
 .--------------------.       持久状态.----------------------。
 |申请代码| ------------------------> | Agentspan / Conductor|
 |代理+工具| <--- task delegation ---- | run, step, history   |
 '--------------------'                            '----------+-----------'
      | worker may die                                        |
      | and reconnect                                         | calls
      v                                                       v
 custom tool process                               LLM / HTTP / MCP tools
      |                                                       |
      '---------------- results + side effects ---------------'

 Durable checkpoint ≠ transaction over every external side effect

最后一行是最重要的操作警告。工作流引擎可以记住它请求了付款、电子邮件或存储库变更，但它无法自动使任意外部操作成为事务性的。如果工作人员远程成功并在确认完成之前崩溃，则重试可能会重复该操作。每个变异工具都需要幂等密钥、协调查询或人工决策路径。

在快乐路径演示之前进行碰撞测试

一个有用的概念证明故意杀死不同边界的工人。运行一项只读研究作业、一项具有受控副作用的作业和一项受审批限制的作业。保留执行 ID，在不同的计算机上重新启动，重新连接，并将最终状态与不间断的控制运行进行比较。

重试需要副作用合约

在启用自动重试之前对工具进行分类。纯函数和可重复读取通常可以重试。写入需要工作流程和步骤范围内的稳定操作密钥。不可重复的操作需要“重试前查询”适配器或手动协调队列。不要要求法学硕士从对话上下文中推断是否已发生付款或消息。

• 安全重试： 计算校验和、读取公共页面或通过不可变 ID 进行查询。
• 有条件安全： 使用服务器强制的幂等性密钥创建票证，或通过版本检查更新已知记录。
• 默认情况下不安全： 发送电子邮件、发布内容、转账或执行生产更改，无需重复数据删除。
• 可补偿： 当存在经过测试的取消操作和负责任的升级路径时，保留资源。

人工审批是一个政策系统，而不是暂停按钮

Agentspan 记录标记为批准的工具以及 CLI、API 或 UI 响应。生产策略还必须定义谁可以批准、冻结哪些具体参数、如何验证身份、请求何时过期以及修改的操作是否创建新的批准。向审批者展示提议的副作用、目的地、数据披露、估计成本和人类可读的差异。

将高影响力行动的请求者与批准者分开。拒绝必须终止或缩小行动范围；它不应该提示模型使用其他工具绕着门走线。在运行过程中记录策略版本和批准工件，以便重播无法将旧决策应用于新参数。

框架兼容性并不意味着相同的语义

官方文档演示了自己的代理 API 以及与 LangGraph、OpenAI 代理 SDK 和 Google ADK 的集成。测试您计划部署的确切适配器和版本。检查流、取消、嵌套代理、工具调用 ID、结构化输出、上下文传播和错误映射。包装器可以在更改检查点或重试行为时保留可调用接口。

凭证和存储的执行数据

Agentspan 通过环境配置和服务器执行的 HTTP、OpenAPI 和 MCP 工具支持提供程序密钥。集中执行可以减少复制到每个工人身上的秘密，但它也集中了权力。使用秘密管理器、短期凭据、每个环境的身份和出站允许列表。切勿将凭据放置在提示、工具架构或持久结果中。

执行历史记录可以包含客户文本、检索到的文档、源代码、模型响应、工具参数和错误。决定在存储之前编辑哪些字段、谁可以搜索或重播运行、如何分隔租户以及如何将删除请求传播到备份和可观察性导出。加密传输和存储、审核读取访问和测试恢复，而不是假设持久性等于可恢复性。

导致行动的可观察性

原始跟踪仅在回答操作问题时才有用。跨触发器、工作流程、模型调用和外部突变附加关联 ID。记录型号/版本、提示策略版本、代币数量、工具延迟、重试原因、审批延迟和终端分类。避免标签中出现高基数秘密。

部署和升级清单

1. 固定 SDK、服务器和 Conductor 版本；记录兼容性矩阵。
2. 独立的开发、登台和生产凭证、队列和数据存储。
3. 备份工作流元数据并测试恢复到隔离环境中。
4. 设置每个代理和租户的并发、令牌、时间、重试和递归预算。
5. 配置服务器、工作人员、队列、数据库和模型提供程序的运行状况检查。
6. 使用金丝雀工作人员进行升级，并保留旧的工作流程定义可用于运行中的运行。
7. 定义取消语义：停止未来的工作、撤销凭证并协调部分副作用。
8. 威胁模型提示注入、SSRF、恶意工具输出和过于广泛的MCP/OpenAPI暴露。

替代方案和诚实选择边界

不要仅仅因为工作流程使用 LLM 就添加持久运行时。一个没有副作用的简短同步助手可能只需要请求记录和重试。当运行时间较长、审批等待超出流程生命周期、事件触发工作或恢复历史记录是产品要求时，Agentspan 变得引人注目。

两周评估计划

第一周应该建立控制工作流程和集成。选择一项具有三到十个步骤、一项批准和可逆外部写入的有界作业。衡量不间断的成功和成本，然后注入崩溃。第二周应重点关注敌对和操作案例：重复事件、延迟批准、格式错误的工具输出、提供商速率限制、工作人员替换、服务器重新启动以及运行中的升级。

仅当另一位工程师可以根据书面说明重现部署和恢复、每个变异工具都有经过测试的副作用策略、敏感历史记录受到管理、并且接受结果率提高到足以证明服务器和待命负担的合理性时，才能进行升级。

常见问题

Agentspan 是代理框架吗？

它包括代理 API，但其区别在于代理下的持久运行时。它还可以运行使用受支持的外部框架构建的代理。

执行引擎是什么？

该项目指出，代理定义编译为 Conductor 上的工作流程，提供持久状态、历史记录、重试和工作流程原语。

可以自托管吗？

是的。官方网站将其描述为 MIT 许可且可自行托管。运营商仍然需要验证依赖关系、数据存储、升级和支持期望。

崩溃恢复是否可以防止重复写入？

不会。持久编排可以减少状态丢失，但外部写入仍然需要幂等性、协调或补偿。

批准是否自动安全？

不可以。团队必须定义身份验证、授权、参数绑定、到期、职责分离和审计保留。

它是否消除了对代理框架的需要？

不会。它可以补充现有的代理定义。为状态、重试和中断选择一个明确的所有者，以避免语义冲突。

第一个生产工作负载应该是多少？

有界、可逆、低敏感度的工作流程，具有可衡量的成功和明确的升级，而不是付款、生产变更或广泛的数据访问。

主要来源

• 官方 Agentspan 网站和快速入门
• 官方文档
• 官方架构和耐久性解释
• 代理执行概念
• 工具类型和服务器端执行
• 支持的模型提供者和配置
• CLI、批准和执行历史记录
• 官方源码库
• OWASP 针对 LLM 申请风险的指南

上次审核日期为 2026 年 7 月 25 日。Agentspan 正在快速发展。在采用之前验证准确的 SDK/server 版本、许可证、框架适配器和部署说明。