PACKHORIZON · AGENT ARCHITECTURE RESEARCH

MAF Agent 与 Pi Agent
使用方式和运行机制对比

基于 PackHorizon 当前 Microsoft Agent Framework 生产实现，以及 Pi Agent Harness（pi.dev） 官方运行模型的代码级调研。

PackHorizon branch: feature/agent-architecture-migrationMAF Core 1.11.0Pi Agent Harness架构调研

执行摘要

PackHorizon 当前的 MAF 不是一个持续自由行动的聊天 Agent，而是一套“先由模型规划、再冻结任务图、最后可靠执行”的业务工作流系统。

MAF：智能生产流水线

面向付费交付、结构化报告、质量门、审计、幂等、失败恢复和多租户隔离。

Pi：智能工具操作员

面向开放式任务、持续会话、自主工具调用、实时 Steering 和开发者工作流扩展。

最终判断：MAF 解决“如何可靠地运行一项 AI 业务”；Pi 解决“如何让一个模型持续使用工具完成开放任务”。两者可以互补，但不应该直接互换。

一、PackHorizon 如何使用 MAF

用户 Intake 对话 ↓ Requirement Card ↓ Model Planner 根据 Skills / Tools / Workflow 动态生成 DAG ↓ Validator 校验与 Repair ↓ 冻结 Plan、Model、Skill、Tool、Context 快照 ↓ Dispatch Outbox → Celery agent_execution Worker ↓ MAF Functional Workflow ↓ 按拓扑层并行执行 Task ↓ 每个 Task 创建一个独立 MAF Agent ↓ ToolBroker + JSON Schema + Gate + Reviewer + Retry ↓ Final Gate → 报告发布

1. 动态规划，冻结执行

Planner 可以根据需求卡和当前能力目录生成不同 DAG，但执行前必须完成 Validator、Repair、Fingerprint 与 Hash 校验。Run 启动后只读取冻结快照，因此后台修改模型或 Skill 不会污染正在执行的 Run。

plan_snapshotmodel_snapshotskill_snapshottool_snapshotcontext_snapshot

2. 一个 Task，一个独立 Agent

市场研究、品牌策略、设计方向和报告组装不是同一个 Agent 持续聊天，而是每个 Task 创建新的 MAF Agent。跨任务信息只通过显式 inputBindings、Artifact、需求卡和上游结构化输出传递。

效果：上下文边界清晰、容易审计和重试；代价是每个 Task 都需重新注入 Skill 与项目上下文。

3. MAF 提供 Step/Checkpoint，业务编排主要由项目实现

项目使用实验性的 Functional Workflow：@workflow、@step、FileCheckpointStorage。DAG 拓扑、同层并发、条件分支、质量循环、ToolBroker、Reviewer 和 Final Gate 仍由 PackHorizon 实现。

4. 必需工具不是“看模型心情”

Skill 声明的 required tools 会由执行器确定性调用，并把真实结果作为证据注入 Agent。模型可以调用额外授权工具，但最终会检查必需工具是否实际调用以及是否越权。

5. 多层质量门

  1. JSON 解析
  2. Skill Output Schema
  3. Skill Gate
  4. Required Tool 校验
  5. 独立 Reviewer 逐条检查 Acceptance Criteria
  6. Repair/Retry
  7. 全局 Final Gate

二、Pi Agent 如何运行

用户 Prompt ↓ 同一个 AgentSession ↓ LLM 生成文本或 Tool Calls ↓ 并行 / 串行执行 Tools ↓ Tool Results 回到同一会话 ↓ 再次调用 LLM ↓ 直到模型不再调用 Tool

Pi 的中心是持续存在的 AgentSession：消息、模型、Thinking Level、Tools、流式状态共同构成 Agent State。用户可以中途 Steering、排队 Follow-up、Abort、切换模型或从历史节点分支。

会话而非 Run

Pi 默认没有 Requirement Card、Frozen Plan、业务 Step 和 Final Gate。它围绕消息历史持续行动。

模型主导工具循环

模型选择何时调用 read/bash/edit/write/grep/find/ls 等工具；同一轮多个工具可并行。

JSONL 会话树

Session 自动保存为 JSONL，支持 resume、tree、fork、clone 和 compaction。

扩展优先

权限门、计划模式、Subagent、Todo、Git Checkpoint 等通常通过 TypeScript Extension 或 Package 添加。

Pi Skill 与 MAF Skill 不是同一种东西

Pi Skill 更像按需加载的操作手册和能力包；PackHorizon MAF Skill 是包含 Prompt、Output Schema、Gate、Required Tools、Output Kind 和重试规则的可执行业务契约。

三、核心差异

维度PackHorizon MAFPi Agent
产品定位后台业务工作流运行时交互式 Agent Harness / 编码助手
基本单位Plan / Run / TaskSession / Turn
控制权模型先规划，执行时冻结LLM 每轮动态决定下一步
Agent 生命周期每个 Task 新建 Agent同一 Agent 持续整个 Session
上下文Binding、Artifact、Snapshot 显式传递消息历史自然累积
流程结构DAG、条件、循环、拓扑并行默认线性 Agent Loop
并行同拓扑层 Task 并行同一 Turn 多 Tool Call 并行
持久化PostgreSQL + 文件 CheckpointJSONL Session
恢复语义从已完成业务 Step 后恢复恢复会话、分支和上下文
输出强制结构化业务交付物默认文本、代码和 Tool Result
质量控制Schema + Gate + Reviewer + Final Gate主要依赖模型自检，可扩展
Tool 权限每个 Task 独立白名单、必需工具和审计Session 工具集，Hook 可拦截
Skill可执行、版本化、冻结的业务契约按需加载的知识与操作包
模型Run 内冻结，禁止漂移Session 中可切换模型与 Thinking
用户干预Intake 后主要后台运行实时 steer / follow-up / abort
调度Celery + Redis + Outbox当前进程内 Agent Loop
多租户Owner 隔离、权限、积分、审计默认本地单用户
安全服务端 ToolBroker、脱敏、SSRF 和图片安全闸默认继承本机权限，Extension 可执行任意代码
扩展体验后台配置、数据库版本和部署TS Extension 热加载与 Package 生态

四、自主性边界

MAF 的自主区

  • Intake 如何补问
  • Planner 选择 Skill 并编排 DAG
  • 单个 Task 如何组织内容
  • 是否调用可选工具

MAF 的确定区

  • 需求与 Workflow Policy
  • 可用 Skill/Tool Catalog
  • Plan Validator 与冻结快照
  • 工具权限、Schema、Reviewer、Final Gate
  • 计费、归属和发布

Pi 默认把“下一步做什么、是否调用工具、何时认为任务完成、最终输出如何组织”都留给同一个 Agent Loop。因此 Pi 灵活度更高，MAF 可预测性更高。

五、对 PackHorizon 的适配结论

PackHorizon 有付费、图片成本、可复现报告、失败恢复、管理员审计、多租户隔离、内部轨迹隐藏和配置冻结等要求。这些都更符合当前 MAF Workflow 架构。

如果直接用 Pi 替换生产主链，仍需重新实现：Plan 冻结、DAG、Outbox、幂等计费、Step Checkpoint、Artifact 类型系统、Schema/Gate、Reviewer、Final Gate、多租户隔离和用户/管理员事件分层。

Pi 更适合作为辅助 Agent

  • 开发人员本地维护 PackHorizon
  • 管理员自然语言排查失败 Run
  • Skill / Workflow 草稿生成
  • 报告质量人工复核助手
  • 运营分析与“问系统”式运维助手

六、当前 MAF 实现风险

实验 API 与私有导入

项目依赖 Functional Workflow，并使用 agent_framework._workflows._functional 私有路径。虽然已有 Adapter 和版本锁，升级仍有破坏风险。

Checkpoint 仍是本地文件

FileCheckpointStorage 适合单机。多机 Worker、容器迁移或磁盘丢失场景，需要共享或分布式 Checkpoint Backend。

大量编排能力仍是自研

DAG、拓扑、并发、Gate、Reviewer、快照、队列与审计主要由项目承担，MAF 并未消除这部分复杂度。

每 Task 新建 Agent 的 Token 成本

边界更干净，但 Requirement Card、Skill 正文和上游结果会重复注入，应关注上下文压缩与 Progressive Disclosure。

七、建议

保留 MAF 作为报告生产内核，不建议改成 Pi Agent Loop。

  1. 增加安全的暂停、人工补充和继续能力；
  2. 借鉴 Pi 的 Session Tree，提供 Plan/Run 版本分支查看；
  3. Skill 做 Progressive Disclosure，减少重复 Token；
  4. 增加 Artifact/Context Compaction；
  5. 管理端增加实时 Abort；
  6. 开发环境使用 Pi 辅助 Skill、Workflow 和运维工具开发。

最合适的组合是：MAF 做生产流水线，Pi 做开发与运营操作员。

资料来源

PackHorizon 代码依据：agent_engine/plan、agent_engine/workflow、domains/agent_runtime、tasks/agent_tasks.py，基于当前分支最新代码审计。

↑