Swift版LangGraph问世

背景

随着大语言模型（LLM）的普及，构建 AI 代理（Agent）和多步骤工作流（Workflow）的需求日益增长。在 Python 生态中，LangChain / LangGraph 等框架已经较为成熟，但 Swift 社区长期缺少一个原生、类型安全且充分利用 Swift 并发特性的代理框架。Hacker News 上发布的「Show HN: I Built LangGraph for Swift」正是这一空白的有力填补 —— 作者 Christopher Karani 开源了 Swarm，一个完全用 Swift 编写、支持类型安全工具调用、定义工作流 DAG、具备持久化检查点（durable checkpointing）等企业级特性的代理库。项目已发布至 Swift Package Index，支持 iOS 26+、macOS 26+ 及 Linux（Ubuntu 22.04+），并集成了 Foundation Models、Anthropic、OpenAI、Ollama 等十余种推理提供商。

核心内容

Swarm 允许开发者用声明式语法定义代理（Agent）和工作流（Workflow），并利用 Swift 的 async/await、AsyncThrowingStream、actors、result builders、宏（macros）等语言特性实现类型安全、高性能的 AI 流水线。

1. 代理（Agent）与工具（Tool）定义

代理通过 Agent 结构体创建，可指定指令（instruction）、名称、推理提供商（inferenceProvider），并通过 @ToolBuilder 闭包添加工具。工具使用 @Tool 宏在编译期生成 JSON Schema，参数用 @Parameter 标注，执行函数为 async throws -> String。例如：

let agent = try Agent("Answer finance questions using real data.",
    configuration: .init(name: "Analyst"),
    inferenceProvider: .anthropic(key: "{ENV}")) {
    PriceTool()
    CalculatorTool()
}
let result = try await agent.run("What is AAPL trading at?")
print(result.output) // "Apple (AAPL) is currently trading at $182.50."

工具调用完全类型安全：@Tool 宏从 Swift struct 自动生成 JSON schema，参数类型在编译期确保正确。

2. 工作流（Workflow）与 DAG

工作流由多个步骤（step）组成，步骤可以是代理或并行分支。顺序执行使用 .step() 链式调用，例如一个研究代理后接写作代理：

let researcher = try Agent("Research the topic and extract key facts.",
    inferenceProvider: .anthropic(key: "sk-...")) {
    WebSearchTool()
}
let writer = try Agent("Write a concise summary from the research.",
    inferenceProvider: .anthropic(key: "sk-..."))
let result = try await Workflow()
    .step(researcher)
    .step(writer)
    .run("Latest advances in on-device ML")

并行分支使用 .parallel()，可指定合并策略（.structured）；条件路由使用 .route() 根据输入内容选择不同代理。

工作流被编译为有向无环图（DAG），支持崩溃恢复和 Swift 并发安全。

3. 流式输出（Streaming）与事件

代理支持流式输出，通过 agent.stream() 返回 AsyncThrowingStream，事件类型包括 .output(.token)（文本令牌）、.tool(.completed)（工具完成）、.lifecycle(.completed)（完成状态）、.lifecycle(.failed)（错误）等。开发者可根据事件类型实时处理。

4. 持久化检查点（Durable Checkpointing）

工作流支持持久化检查点，可指定 checkpoint ID 和策略（如每步检查点 .everyStep），存储在文件系统中。从崩溃中恢复时，可通过 resumeFrom 参数恢复执行：

let workflow = Workflow()
    .step(monitor)
    .durable.checkpoint(id: "monitor-v1", policy: .everyStep)
    .durable.checkpointing(.fileSystem(directory: checkpointsURL))
let resumed = try await workflow.durable.execute("watch", resumeFrom: "monitor-v1")

5. 会话（Conversation）与记忆（Memory）

Conversation 对象封装了一个代理的连续对话，自动维持上下文。发送消息后，历史记录可通过 conversation.messages 获取。代理还支持向量记忆（memory: .vector），通过嵌入提供者和相似度阈值实现记忆检索。

6. 推理提供商（InferenceProvider）可插拔

Swarm 抽象了推理接口，支持 Foundation Models（Apple 原生）、Anthropic、OpenAI、Ollama、Gemini、MiniMax、OpenRouter、MLX 等。可在代理级别指定，也可通过 Swarm.configure() 设置全局默认。运行时可通过 .environment() 切换提供商（例如从 Anthropic 切换到 Ollama 的 mistral 模型）。

7. 功能展示（Capability Showcase）

Swarm 内置了一个功能展示矩阵，在确定性条件下测试所有稳定表面。运行命令列出、执行矩阵或单个场景：

swift run SwarmCapabilityShowcase list
swift run SwarmCapabilityShowcase matrix
swift run SwarmCapabilityShowcase run handoff
swift run SwarmCapabilityShowcase smoke

场景涵盖：代理与工具、流式输出、会话与持久化、顺序/并行/路由/重复-直到工作流、任务交接（handoff）、记忆、设备端工作区加载、护栏（guardrails）、弹性帮助（resilience helpers）、持久化检查点与恢复、可观测性、MCP 发现与工具桥接、提供商选择。矩阵是 CI 安全的，仅通过环境变量选择启用实时提供商烟雾测试。

8. 示例可执行文件

可通过环境变量 SWARM_INCLUDE_DEMO=1 开启示例编译，运行 SwarmDemo 和 SwarmMCPServerDemo。

9. 架构总览

Swarm 的架构层次如下（文字示意）：

• 你的应用层：iOS 26+ / macOS 26+ / Linux
• 接口层：Workflow · Conversation · .run() · .stream()
• 核心层：Agents（Agent struct）、Memory（Memory factories）、Tools（@Tool macro、FunctionTool、@ToolBuilder）
• 安全与弹性层：InputGuard · OutputGuard · Resilience · Observability · MCP
• 内部运行时：Durable Graph Runtime（Workflow Graph · Checkpointing · Deterministic retry）
• 推理提供商层：Foundation Models · Anthropic · OpenAI · Ollama · OpenRouter 等插件化

10. 开发与贡献

项目在 GitHub 上以 MIT 许可发布。所有公开类型必须遵守 Sendable（编译器强制检查），格式化使用 swiftformat Sources Tests --lint --config .swiftformat。贡献流程为：Fork → 分支 → swift test → PR。Bug 和特性请求通过 GitHub Issues。

关键要点

• Swarm 是用纯 Swift 编写的 AI 代理框架，充分利用 Swift 6.2 的 StrictConcurrency、async/await、actors、宏等语言特性。
• 代理工具通过 @Tool 宏在编译期生成 JSON Schema，确保类型安全，杜绝运行时类型错误。
• 工作流支持顺序、并行（.parallel()）、条件路由（.route()）、重复直到（repeat-until）等多种拓扑，编译为 DAG，支持崩溃恢复和持久化检查点。
• 推理提供商可插拔：内置 Foundation Models（设备端）、Anthropic、OpenAI、Ollama、Gemini 等十余种，可通过环境变量或代码在运行时切换。
• 流式输出提供细粒度事件：令牌、工具完成、生命周期（成功/失败）、handoff 等，便于实时构建 UI 或日志。
• 会话（Conversation）自动管理历史消息，代理可附加向量记忆实现长期记忆。
• 内置护栏（InputGuard 和 OutputGuard）用于输入长度、非空等校验，防止异常输入。
• 支持 MCP（Model Context Protocol）发现与工具桥接，可与其他 M