AgentKitten 完全指南：在 Apple 生态中用 Swift 构建 AI Agent

如果你在开发 iOS/macOS 应用，想为 App 引入 AI Agent 能力，目前的选择并不多——Python 框架（LangChain、LlamaIndex）跑不了在移动设备上，Anthropic/OpenAI 的 SDK 是单提供商绑定的，Vercel AI SDK 是 JavaScript 生态的。

AgentKitten 是首个专为 Apple 生态设计的 Swift 包，提供了一组标准化的 AI Agent 构建模块，让你在 iOS、macOS、visionOS、tvOS、watchOS 上都能创建多提供商、可定制、可审计的 AI Agent。

项目特点：多提供商抽象（Anthropic、Apple Intelligence 等）、工具权限系统、自动上下文压缩、验证循环、内置追踪。安装只需一行 SPM 配置。

安装

在 Package.swift 中添加依赖：

.package(url: "https://github.com/fbeeper/agentkitten", from: "0.0.1")

然后添加 AgentKitten 到目标依赖中。支持 Swift 6.1+，最低系统版本 macOS 15+ / iOS 17+ / tvOS 17+ / watchOS 10+ / visionOS 1+。

项目附带一个 Playground，可快速体验所有功能：

swift run Playground --help

核心概念

AgentKitten 的架构围绕五个核心抽象设计：

InferenceProvider（推理提供商）

Agent 背后的大模型来源。可以是 Anthropic Claude API、本地 Apple Intelligence 的 Foundational Models，或者你自己的推理服务。关键特性：提供商切换不影响 agent 实现代码。

import AgentKitten
import AgentKittenAnthropicInference

let provider = InferenceProvider.anthropic()

Agent（智能体）

你的基础控制器。配置工具集、系统行为、提供商。

let agent = Agent(
    behavior: behavior,
    provider: provider,
    toolDefinition: toolConfig,
)

AgentSession（会话）

从 Agent 创建独立会话。每个会话隔离，支持多轮对话和并行线程，轻量且天生并发安全。

Trace（追踪）

每个会话的详细记录：工具调用、结果、压缩事件等。用于调试、测试、评估。

ToolDefinition（工具定义）

工具 + 策略 + 钩子的完整包装：

• ToolExecutionPolicy：工具调用前批准、拒绝或挂起
• ToolHook：执行前转换输入，执行后重塑结果
• @Tool 宏：极简绑定 Swift 函数

实战：构建一个自动压缩的搜索 Agent

以下是一个完整的例子，创建一个带自动上下文压缩的搜索助手 Agent：

import AgentKitten
import AgentKittenAnthropicInference

// 1. 配置工具
struct MySearchTool: AgentTool {
    var metadata: ToolMetadata {
        ToolMetadata(
            name: "search_documents",
            description: "Search through the app's document store"
        )
    }
    
    func call(using parameters: ToolParameters) async throws -> ToolResult {
        guard let query = parameters["query"]?.stringValue else {
            return ToolResult.failure("Missing query")
        }
        // 实际搜索逻辑
        return ToolResult.success("Search results for: \(query)")
    }
}

// 2. 定义工具集和执行策略
let toolConfig = ToolDefinition(tools: [
    AnyAgentTool(MySearchTool()),
], policy: ToolExecutionPolicy { tool, context in
    // 只批准搜索工具，拒绝其他
    if tool.metadata.name == "search_documents" {
        return .approve
    }
    return .deny
})

// 3. 配置行为（含自动压缩）
let behavior = AgentBehavior(
    systemPrompt: "你是一个文档搜索助手。",
    defaultAutomaticCompactionPolicy: .enabled(
        trigger: .percentOfContextWindow(0.5)
    )
)

// 4. 创建 Agent
let provider = InferenceProvider.anthropic()
let agent = Agent(
    behavior: behavior,
    provider: provider,
    toolDefinition: toolConfig
)

// 5. 启动会话
let session = agent.makeSession()
let turn = try await session.send("帮我找一下关于 Swift Concurrency 的文档")

for try await event in turn.events {
    if case .textDelta(let text) = event.kind {
        print(text, terminator: "")
    }
}

代码要点：

• @Tool 宏可以进一步简化工具定义，一行代码将 Swift 函数暴露为 Agent 工具
• 自动压缩策略：对话达到上下文窗口 50% 时自动触发压缩，用户无感
• ToolExecutionPolicy：支持 approve、deny、suspend 三种模式

四大高级特性

1. 人类参与审批（Human-in-the-Loop）

Agent 需要在执行敏感操作前征求用户许可：

let config = ToolDefinition(tools: [tool], policy: ToolExecutionPolicy.ask())

Agent 会在调用工具前生成理由，让用户选择批准或拒绝。也可以用 .ask(autoApproveTimeout: 30) 设置超时自动审批。

2. 结构化输出

除了流式文本，AgentKitten 原生支持解析结构化数据：

let turn = try await session.generate<[PointOfInterest]>("找附近的公园")
for try await event in turn.events {
    if case .result(let pois) = event.kind {
        updateMap(with: pois)
    }
}

3. 隐私保护（PII 脱敏）

在敏感输入发送到云端模型前，自动剥离个人信息：

// AgentKitten 提供钩子模式：输入脱敏 → 推理 → 工具执行前恢复
let piiConfig = ToolDefinition(
    tools: [tool],
    hooks: [PIIRedactionHook()]
)

这种模式确保用户数据完全不出设备，工具执行时才恢复必要信息。

4. 验证循环（Validation Loop）

要求模型的输出满足特定的质量门禁：

let validator = JudgeValidator(judgeProvider: judgeProvider) { response in
    // 检查响应是否符合质量标准
    return response.contains("code example") ? .pass : .fail("需要包含代码示例")
}

session.validator = validator

验证失败时自动重试，并在提示中加入失败原因。可配合 maxAttempts 设置重试上限。

适用场景

• iOS App 的智能搜索：用户用自然语言描述需求，Agent 组合搜索参数
• macOS 自动化助手：文件管理、批量处理、系统配置
• visionOS 多模态交互：结合图片理解和语音输入
• App 内容审核：自动检测用户上传内容的安全合规性
• 游戏 NPC 交互：Agent 驱动角色对话和物品交换

与主流方案的对比

最佳实践

1. 善用自动压缩：对于长时间对话的 App（客服、助手），启用 percentOfContextWindow(0.5) 压缩策略，避免 Token 超限
2. 策略与工具分离：将执行策略定义为独立的 ToolExecutionPolicy，方便测试和复用
3. 优先使用 PII 钩子：对于涉及用户隐私的场景，始终使用 PIIRedactionHook 脱敏
4. 结构化输出优于流式：当需要驱动 App UI 更新时，用 session.generate() 替代流式文本
5. Playground 原型验证：在 Xcode 项目接入前，先用 swift run Playground 验证概念

注意事项

• AgentKitten 目前是预发布阶段（0.0.1），API 可能在正式版前调整
• 自动压缩仅在开启时生效，且需要提供商支持 Token 计数
• ToolExecutionPolicy 的 ask 模式需要 UI 层配合展示审批对话框
• 当前仅内置 Anthropic 提供商插件，Apple Intelligence 和 OpenAI 插件待完善

总结

AgentKitten 填补了 Swift/Apple 生态中 AI Agent 框架的空白——不同于 Python 和 JS 生态的成熟方案，Apple 开发者此前只能绑定单提供商 SDK 或从头实现 agent harness。AgentKitten 提供了一套标准化、可组合、高可用的构建模块，从工具权限到自动压缩、验证循环到隐私保护，覆盖了生产级 AI Agent 的核心需求。

如果你正在为 iOS/macOS App 引入 AI Agent 能力，AgentKitten 值得一试。