AgentKit — Swift 编写的 App Sandbox 下的 Agent Runtime

项目简介

AgentKit 是一款由 Swift 编写的、专为 App Sandbox 环境设计的 Agent 运行时框架。它为 macOS 15+ 和 iOS 18+ 上的 Swift 应用提供了完整的 Agent 执行循环，包括工具调用、权限审批、并发调度和会话修复等核心能力。该项目由 AkinoKaede 开发，采用 MIT 许可证开源，核心设计理念是安全在本地验证而非远程断言。

核心功能

AgentKit 提供完整的 Agent 运行时架构，核心功能包括：

• 工具调用循环：标准的两阶段循环——流式输出助手消息，执行为此请求的工具调用，循环往复直到任务完成
• 权限审批三层模式：askForApproval（每条 Acting 调用都需用户审批）、approveForMe（由模型审查员在超时或凭证缺失时自动拒绝）、fullAccess（完全放行）
• 本地安全验证：每个工具调用都必须经过本地预检，远程元数据只能收紧权限而无法放宽，确保调用安全
• 并发调度机制：支持按调用粒度选择并行或串行执行，同一 turn 内的所有调用结果按模型提问顺序返回
• 会话修复机制：支持运行快照和存储历史记录，自动修复崩溃或中断导致的不完整调用状态
• Secrets 保护：用户输入的密钥绑定到特定运行和工具目的后，排除于模型输入、历史记录和持久化之外
• MCP 服务器集成：支持配置外部 MCP 服务器，并自动将服务器公告的工具注册到内置工具集中

技术实现

AgentKit 使用纯 Swift 实现，核心依赖包括 Swift 6 协程和 Swift Package Manager，零外部 UI 框架依赖。架构采用模块化设计：运行时核心由 AgentRuntime 驱动，接收请求后按事件流方式输出消息；AgentTurnDriver 负责流式输出单个助手轮次；AgentToolScheduler 负责规划调用批次；AgentToolExecutor 负责按固定顺序（验证、预检、钩子、授权、执行）执行每个工具调用。

权限模型模仿了 Pi 和 Codex 的设计思路，但在 App Sandbox 约束下进行了适配。由于沙盒限制，本地命令执行类功能受限，但通过 SSH 远程主机执行的 Agent 场景可以突破这一限制。预装工具组包括 Scratch（便笺读写搜索）、Web（网页抓取与搜索）、UserInteraction（用户输入请求）、Planning（计划呈现）、Tasks（任务管理）、Skills（技能加载）和 MCP（外部 MCP 服务器工具）七大类，每类工具可按需选择性启用。

快速上手

在 Swift 项目中集成 AgentKit，只需几步即可完成。第一步，在 Package.swift 中添加依赖，指定从 0.3.0 版本开始。第二步，配置 AgentRuntime、模型提供者、工具目录和权限审批经纪人。第三步，调用 runtime.start() 启动运行循环，监听消息输出和工具执行事件。

适用人群

AgentKit 主要面向以下开发者群体：

• macOS/iiOS 开发者：希望在应用内集成 AI Agent 能力，同时严格控制工具调用安全边界的 Swift 开发者
• SSH 工具开发者：通过 SSH 软件与远程主机交互的场景，需要 Agent 执行远程命令但需要本地沙盒安全验证的开发者
• Agent 框架研究者：对 Agent 权限模型、并发调度和会话修复等机制感兴趣的技术研究人员

官方链接

GitHub 仓库：https://github.com/AkinoKaede/AgentKit