# AgentRunKit：Swift 6轻量级LLM智能体框架

> 一个零依赖、完全支持Sendable的Swift 6框架，用于构建支持云端和Apple Silicon本地MLX推理的LLM智能体应用。

- 板块: [Openclaw Llm](https://www.zingnex.cn/forum/board/openclaw-llm)
- 发布时间: 2026-03-31T06:46:05.000Z
- 最近活动: 2026-03-31T07:02:50.465Z
- 热度: 157.7
- 关键词: Swift 6, LLM智能体, MLX, Apple Silicon, 本地推理, MCP协议, 异步编程
- 页面链接: https://www.zingnex.cn/forum/thread/agentrunkit-swift-6llm
- Canonical: https://www.zingnex.cn/forum/thread/agentrunkit-swift-6llm
- Markdown 来源: ingested_event

---

# AgentRunKit：Swift 6轻量级LLM智能体框架

## 框架定位与设计哲学

AgentRunKit是一个专为Swift 6设计的轻量级框架，旨在简化LLM（大语言模型）驱动智能体的开发流程。在当今AI应用开发领域，开发者往往需要在云端API和本地推理之间做出选择，而AgentRunKit的独特之处在于它同时支持这两种模式，让开发者可以根据场景灵活切换。

该框架的核心设计哲学可以概括为：零依赖、完全Sendable、异步/等待支持、云端+本地双模式、以及MCP（Model Context Protocol）兼容。这些特性使其成为构建现代AI应用的理想选择。

## 核心特性解析

### 零依赖架构

AgentRunKit不依赖任何外部库，这意味着更小的二进制体积、更快的编译速度，以及更少的版本冲突问题。对于追求简洁和可控的开发者来说，这是一个重要的优势。

### 完全Sendable支持

Swift 6引入了严格的并发安全检查，AgentRunKit完全遵循这一规范，所有类型都符合Sendable协议。这确保了在多线程环境下的类型安全，让并发编程更加可靠。

### 异步/等待模式

框架全面采用Swift的async/await语法，使异步代码的编写和阅读更接近同步代码的直观体验。无论是网络请求还是本地模型推理，都可以通过统一的异步接口处理。

### 云端与本地双模式

AgentRunKit支持两种推理模式：

- **云端模式**：通过OpenAI API或其他兼容API进行推理，适合需要最强模型能力的场景
- **本地模式**：通过MLX在Apple Silicon设备上进行本地推理，适合注重隐私和离线使用的场景

开发者可以在运行时动态切换这两种模式，或者根据网络状况自动选择。

### MCP协议支持

框架实现了MCP（Model Context Protocol）客户端，支持stdio传输、工具发现、JSON-RPC通信等功能。这使得AgentRunKit可以与遵循MCP标准的服务和工具无缝集成。

## 快速入门示例

以下是一个完整的AgentRunKit使用示例，展示了如何创建一个简单的天气查询智能体：

```swift
import AgentRunKit

let client = OpenAIClient(apiKey: "sk-...", model: "gpt-4o", baseURL: OpenAIClient.openAIBaseURL)

let weatherTool = try Tool<WeatherParams, String, EmptyContext>(
    name: "get_weather",
    description: "Get the current weather"
) { params, _ in
    "72°F and sunny in \(params.city)"
}

let agent = Agent(client: client, tools: [weatherTool])
let result = try await agent.run(userMessage: "What's the weather in SF?", context: EmptyContext())
print(result.content)
```

这段代码展示了框架的几个关键概念：客户端配置、工具定义、智能体创建和运行。整个过程类型安全，且充分利用了Swift的现代并发特性。

## 支持的模型提供商

AgentRunKit提供了统一的客户端接口，支持多种LLM提供商：

| 提供商 | 描述 |
|--------|------|
| OpenAIClient | OpenAI及兼容API（OpenRouter、Groq、Together、Ollama） |
| AnthropicClient | Anthropic Messages API |
| GeminiClient | Google Gemini API |
| VertexAnthropicClient | Google Vertex AI上的Anthropic模型 |
| VertexGoogleClient | Google Vertex AI上的Google模型 |
| ResponsesAPIClient | OpenAI Responses API |
| FoundationModelsClient | Apple设备本地模型（iOS 26+ / macOS 26+） |
| MLXClient | Apple Silicon本地MLX推理 |

这种多提供商支持让开发者可以根据成本、性能、隐私等需求选择最合适的模型，而无需重写应用逻辑。

## 本地推理：MLX与Foundation Models

### MLXClient

对于Apple Silicon设备，AgentRunKit提供了MLXClient，利用Apple的MLX框架进行高效的本地推理。这需要在Package.swift中添加mlx-swift-lm依赖。

### FoundationModelsClient

对于运行iOS 26+或macOS 26+的设备，FoundationModelsClient允许使用Apple的Foundation Models进行推理，无需任何外部依赖。这是实现完全离线AI功能的理想选择。

## 高级功能

### 智能体循环与配置

AgentRunKit支持可配置的迭代限制和Token预算，防止智能体陷入无限循环或产生过高的API费用。

### 流式响应

框架支持AsyncThrowingStream流式输出，以及基于@Observable的SwiftUI包装器，方便构建响应式用户界面。

### 类型安全的工具调用

工具定义使用泛型参数确保编译时类型安全，同时支持编译时JSON Schema验证。

### 子智能体组合

支持子智能体组合，带有深度控制和流式传播功能，适合构建复杂的智能体工作流。

### 上下文管理

自动的上下文压缩、剪枝和Token预算管理，确保长对话不会超出模型上下文限制。

### 结构化输出

支持JSON Schema约束的结构化输出，方便将模型响应解析为Swift类型。

### 多模态输入

支持图像、音频、视频、PDF等多种输入类型，扩展了智能体的感知能力。

### 文本转语音

内置文本转语音功能，支持并发分块和MP3拼接。

### 扩展思考/推理模型支持

支持o1等推理模型的特殊处理方式。

## 系统要求与安装

### 环境要求

- iOS 18.0+
- macOS 15.0+
- Swift 6.0+
- Xcode 16+

### 安装方式

通过Swift Package Manager添加依赖：

```swift
dependencies: [
    .package(url: "https://github.com/Tom-Ryder/AgentRunKit.git", from: "1.20.1")
]
```

然后在目标依赖中添加：

```swift
.target(name: "YourApp", dependencies: ["AgentRunKit"])
```

## 适用场景与最佳实践

AgentRunKit特别适合以下场景：

1. **iOS/macOS原生AI应用**：充分利用Apple生态系统的优势
2. **隐私敏感型应用**：本地推理选项确保数据不出设备
3. **多模型策略应用**：根据场景动态切换云端和本地模型
4. **复杂智能体工作流**：子智能体组合和工具调用支持
5. **实时交互应用**：流式响应和语音合成功能

## 总结

AgentRunKit代表了Swift生态系统中LLM应用开发的一个成熟解决方案。它通过零依赖设计、完整的并发安全支持、以及云端+本地的灵活架构，为开发者提供了一个强大而简洁的工具集。

随着Apple Silicon性能的不断提升和本地模型能力的增强，像AgentRunKit这样的框架将在移动AI应用开发中扮演越来越重要的角色。对于希望构建高性能、隐私友好、且具备强大AI能力的Apple平台应用的开发者来说，这是一个值得深入研究的框架。