SwiftUI 接入智能体：Agent 框架与工具调用实战-平芜编程栈

1. 项目概述：SwiftUI 遇上 Agent，不只是聊天框

先说结论：这个项目是一个面向 Apple 生态的 SwiftUI 客户端 Agent 能力框架，核心解决的是"原生应用如何优雅地接入智能体交互"这件事。我给它起的内部代号是 Agent-Skill，意思是把 Agent 的对话、工具调用、状态反馈这些能力，沉淀成 SwiftUI 可以直接复用的技能模块。

为什么这件事值得做？过去一年我陆续接手过几个智能客服和智能助手类项目，最深的感触是：服务端模型能力早就不是瓶颈了，真正难的是客户端怎么把流式输出、工具调用中间态、多轮上下文这些"非传统 UI"体验做扎实。你用List堆一个聊天界面很容易，但要让用户感觉到对面是一个"正在思考的 Agent"，而不是一个机械的回显管道，这里面的门道相当多。

这个框架的目标场景有三类：一是 App 内嵌的智能助手，二是基于工具调用的自动化任务面板，三是需要把推理过程可视化的调试工具。适合的读者是对 SwiftUI 有一定基础、想在原生端接入大模型能力的开发者——如果你只会摆弄VStack和TextField，建议先补一下 SwiftUI 的 state 管理基础。

我在这篇文章里会把这套框架从架构设计讲到状态机实现，再到工具调用桥接和性能优化，最后附上我在真机调试中踩过的几个坑。全程用 Swift 代码示例说话，不搞悬浮的架构图，尽量让每一段都能直接落到你的工程里。

1.1 需求拆解：Agent 交互到底难在哪

智能体交互和普通聊天有本质区别。普通聊天只需要管"消息列表 + 输入框"，但 Agent 场景里，消息不再是单纯的字符串数组——一条消息可能包含推理过程、结构化数据、工具调用参数、执行结果回填，甚至是一个需要用户确认的操作请求。这就意味着你的数据模型必须能表达"消息的不同形态"，而不是塞进一个String里完事。

另外，流式输出对 UI 框架的考验也很大。大模型的 token 是一个一个蹦出来的，如果每次更新都重建整个列表，SwiftUI 的 diff 机制再高效也架不住频繁的Identifiable变化。更麻烦的是，当 Agent 决定调用某个工具时，界面上要即时展示"正在调用 XX 工具"的状态，等工具返回后还要把结果拼到上下文里继续生成。这一串状态切换如果用@State硬扛，代码很快就会乱成一团。

所以我做这套框架时定下了三个设计目标：消息模型可扩展、状态机可感知、工具调用可插拔。后面的所有实现都围绕这三点展开。

2. 架构设计：把 Agent 运行时从 SwiftUI 里剥离

很多人在 SwiftUI 里写 Agent 界面，最大的误区是把业务逻辑全部塞进 View 的@StateObject里。短期的 Demo 没问题，但一旦功能变多——流式输出、工具调用、错误恢复、多会话管理——你会发现自己不得不用大量 if-else 去处理各种状态组合，View 层变得越来越臃肿，调试体验直线下降。

我采用的分层思路是：展示层只订阅状态，决策层只管状态流转，桥接层负责和外部工具通信。这三层各自独立，用协议和组合的方式连接起来。

- 展示层（SwiftUI Views）：只负责根据 ViewModel 的状态渲染 UI - ViewModel 层（ObservableObject）：持有状态机，对外暴露 intent 方法 - Agent 内核（Actor）：管理消息序列、调用外部模型服务、调度工具 - 工具桥接层（Tool Protocol）：把 Agent 的调用请求转发给具体实现

这个结构被很多人问过，为什么不直接用 MVVM？MVVM 本身没问题，但 Agent 场景的核心是"状态流转"，ViewModel 如果既要管 UI 状态又要维护 Agent 内部状态，很容易产生同步问题。我这里让 ViewModel 退化为纯粹的"状态投影层"，真正的状态机放在 Agent 内核里，ViewModel 只负责把内核状态映射成 UI 可以消费的对象。SwiftUI 的 Combine 天然适合这种单向数据流，订阅关系清晰，也不会出现视图和模型互相引用的循环。

2.1 状态机设计：把对话过程变成可枚举状态

Agent 交互过程在我看来就是四个状态的循环：idle（空闲）、streaming（生成中）、tool-calling（调用工具）、tool-result（工具结果处理）。有时候工具调用会连续发生多轮，所以状态机不能是简单的线性跳转，得支持循环和嵌套。

我给每个会话维护了一个状态枚举：

enum AgentState: Equatable { case idle case thinking // 模型正在思考（等待首个 token） case streaming // 正在输出文本 case toolCalling(ToolCallInfo) // 正在执行工具 case toolResultReady(ToolResult) // 工具执行完成，准备回填 case error(String) }

这里有个容易忽略的点：streaming和thinking是两种不同的 UI 呈现。thinking阶段用户看到的是"小菊花转一转"，因为还没有任何 token 到达；streaming阶段要实时渲染文字。如果只用一个状态表示，界面会闪烁。

状态机解决了一个很关键的问题：取消和超时。比如用户在 Agent 生成中按了停止，状态要从streaming正确回落到idle，同时底层网络请求要被真正取消，而不是假装停住。状态机里我用Task的取消传播来实现这个逻辑，UI 层只需要调用viewModel.stopGenerating()，内部会按状态流转去取消当前任务。

2.2 Agent 内核：Actor 隔离的必要性

SwiftUI 的 View 运行在主线程，而网络请求、工具执行天然需要后台线程。如果直接用 class 让多个线程同时改同一个消息数组，并发问题迟早找上门。我用Actor做 Agent 内核，保证消息序列的写入是串行的。

actor AgentCore { private var messages: [ChatMessage] = [] private var stateMachine = AgentStateMachine() func send(userMessage: String) async throws { messages.append(.user(text: userMessage)) stateMachine.transition(to: .thinking) // 调用远端模型接口，拿到流式数据 let stream = try await modelClient.streamResponse(messages: messages) for try await token in stream { let newText = stateMachine.appendToken(token) // 通过回调把增量文本抛给 UI } } }

关键点在for try await token in stream这一段。每次拿到一个 token，我们不是把整段文本发给 UI，而是把"增量"发过去。UI 侧只需要在原有消息上追加文本，渲染压力会小很多。另外，Actor 内更新状态之后，还要考虑如何通知 UI——我通常用一个PassthroughSubject或者AsyncStream把 token 抛出去，ViewModel 侧统一聚合。

3. 消息模型与 SwiftUI 渲染的细节

聊完架构，进入实操层面。这一节是整篇文章里我认为含金量最高的部分：消息模型怎么设计、SwiftUI 怎么渲染不同类型的消息、流式文本更新怎么避免闪屏和滚动抖动。

3.1 消息结构体的设计

普通的聊天消息模型大概是{id, role, content}，但对 Agent 来说太简陋了。至少需要区分以下形态：

用户发的文本
Agent 回复的文本（可能是流式逐步生成）
工具调用的请求展示（例如search_web(query: "xxx")）
工具执行的结果（可能是一段 JSON 或者表格）
系统提示或错误消息

我把ChatMessage设计成枚举加泛型关联值：

enum ChatMessage: Identifiable, Equatable { case user(String) case agent(StreamedText) case toolCall(ToolCall) case toolResult(ToolResult) case system(String) var id: String { ... } } struct StreamedText { var full: String // 完整文本（已生成部分） var isCompleted: Bool }

用枚举的好处是 SwiftUI 渲染时可以精确 switch，每个 case 对应不同的气泡或卡片布局。StreamedText专门为流式场景设计——UI 拿到一个新值，只需要对比full的变化量来增量更新。

有人会问，为什么不用 class 加@Published呢？因为 Agent 内核是 Actor，消息是跨线程传递的值，如果用引用类型，线程安全问题又回来了。值类型加不可变设计，天然适合跨并发域传递。

3.2 列表渲染：避免滚动跳跃和闪烁

SwiftUI 的List在处理大量消息时有个老毛病：内容更新时容易滚动跳动，尤其当你用ScrollViewReader滚动到底部，每来一个 token 就scrollTo一次，用户会看到界面在抽搐。

我的方案是：List结合LazyVStack，并且对滚动逻辑做节流——只在用户接近底部时才自动滚动，如果用户已经往上翻了，就绝不强行拉回底部。

struct MessageListView: View { @ObservedObject var viewModel: ChatViewModel @State private var isUserScrolling = false var body: some View { ScrollViewReader { proxy in List(viewModel.messages) { message in MessageRow(message: message) .id(message.id) } .onChange(of: viewModel.latestMessageId) { newID in guard !isUserScrolling else { return } withAnimation(.easeOut(duration: 0.2)) { proxy.scrollTo(newID, anchor: .bottom) } } } } }

注意onChange监听的不是整个消息数组，而是latestMessageId。在流式输出的场景中，每秒钟可能有十几个增量 token，如果每次onChange都触发滚动，性能会很差。我只在"新消息产生"和"用户发送消息"时滚动，token 增量期间保持当前位置不变，体感会自然很多。

3.3 流式文本更新的三个方案对比

处理流式文本增量更新，我试过三种方案，各有取舍：

每来一个 token 重建消息数组：最简单，但性能最差。当消息数组超过几十条时，SwiftUI 的 diff 会明显卡顿。
用@Published持有一条消息的引用，原地 append：这个方法性能尚可，但前提是消息对象是 class。跨线程更新时要小心在主线程操作。
通过AsyncStream抛增量，UI 侧手动拼接：最终采用的是这个。Agent 内核每次吐出 token，ViewModel 收到后在主线程更新对应的StreamedText。

第三种方案的直觉是：网络流式数据是"推"的模式，AsyncStream是最贴近用户实际使用场景的通信原语。代码结构像这样：

final class ChatViewModel: ObservableObject { @Published var messages: [ChatMessage] = [] private var agentCore: AgentCore private var streamTask: Task<Void, Never>? func send(_ text: String) { streamTask = Task { let updates = await agentCore.streamResponse(to: text) for await update in updates { // 主线程更新消息 await MainActor.run { applyTokenUpdate(update) } } } } }

关于MainActor.run，很多新手会直接把 UI 更新写在子线程里，这是 SwiftUI 的大忌。用MainActor显式跳转，虽然多写两行，但能保证任何对@Published的修改都发生在主线程，也方便调试。

4. 工具调用链：Agent 的双手如何伸到 SwiftUI 里

Agent 能力区别于纯聊天的标志性功能就是工具调用。用户说"帮我查一下明天上海到北京的机票"，模型生成一个search_flights工具调用，客户端真实执行这个工具，把结果回传模型，再生成自然语言回答。这一串流程横跨前后端，协作细节特别容易出错。

4.1 工具协议化与参数校验

我在框架里定义了这样一个协议：

protocol AgentTool { var name: String { get } var description: String { get } var parametersSchema: String { get } // JSON Schema 格式 func execute(arguments: Data) async throws -> String }

用 JSON Schema 来描述参数，好处是可以把 schema 直接传给服务端模型去做 function calling，模型输出的参数会被JSONDecoder解析成结构体再传给execute。我还保留了一个rawArguments的通道，某些场景下模型会用非结构化文本传参，这个通道能兜底。

测试过发现，模型生成的参数有时候会不符合 schema，比如字段名多了一个空格，或者类型是字符串而不是数字。所以我专门写了参数校验逻辑：解析失败时不要直接抛错，而是把错误信息当作工具结果回传给模型，让模型自行修正参数。这个 trick 在实际使用中非常管用，能省掉很多联调烦恼。

4.2 工具调用过程中的 UI 状态

工具调用期间，UI 不能无动于衷。我设计了一个ToolCallCard组件，专门展示当前正在执行的工具名、参数摘要、执行状态（进行中/成功/失败）。为了不让用户感觉冷冰冰，卡片会展示转圈动画和进度提示。

struct ToolCallCard: View { let info: ToolCallInfo var body: some View { HStack(spacing: 8) { ProgressView() VStack(alignment: .leading) { Text(info.toolName).font(.headline) Text(info.argumentSummary).font(.caption).foregroundColor(.secondary) } Spacer() } .padding() .background(RoundedRectangle(cornerRadius: 12).fill(Color.gray.opacity(0.1))) } }

这里有一个体验细节：工具执行可能很快（比如本地文件读取），如果卡片出现后 200ms 内就消失，用户会感觉界面"闪了一下"。视觉上最好做一个最小展示时间（比如 0.5 秒）才允许消失，保证体验平滑。

4.3 多轮工具调用的上下文管理

模型在完成一个工具调用后，可能会根据结果再调用第二个工具，这就是 Agent 常用的 ReAct 循环。客户端要做的事是维护好整个调用的顺序，不能把工具结果放错位置。

我的做法是：Agent 内核维护一个turn计数器，每次用户发送消息算一个 turn；工具调用和工具结果都标记turn序号；消息列表按(turn, sequence)排序。这样无论工具调用发生多少轮，最终的展示顺序永远是用户消息 -> 工具调用卡 -> 工具结果卡 -> 最终回答，顺序不会乱。

这个设计在模型连续调用三四个工具时尤其重要。如果只用一个数组追加，出现并发回填时消息顺序就会错位，调试起来会让人非常崩溃。

5. 实操环节：搭建一个可运行的 Agent 聊天 Demo

前面理论说了一堆，这一节我把整个工程的关键实现串起来。为了让文章可复现，我尽量使用苹果自带框架和轻量依赖实现一个可运行的聊天 Demo。

5.1 工程结构与核心依赖

我采用的是 Swift Package 方式组织代码，分为三个 Target：AgentCore、AgentUI、DemoApp。工程结构如下：

AgentCore：状态机、消息模型、Agent 协议、工具协议
AgentUI：SwiftUI 组件（消息列表、输入框、工具卡片、状态指示器）
DemoApp：用假数据模拟流式输出，不需要真实的大模型 API 也能跑起来

开发环境我用的 Xcode 15+、iOS 17+，SwiftUI 的新特性比如Observable宏在 iOS 17 上表现很好，不过考虑到兼容性，Demo 里还是用ObservableObject和@Published，这套代码在 iOS 16 上也能编译。

5.2 假数据流式输出的实现

真实调试时每次都调大模型 API 太浪费时间和 token。我在 Demo 里写了一个MockModelClient，用一个Task循环定时吐出 token，模拟流式效果。

struct MockModelClient: ModelClientProtocol { let fullText = """ 好的，我来帮你分析这个问题。首先，我们需要拆解需求... """ func streamResponse(messages: [ChatMessage]) -> AsyncStream<String> { AsyncStream { continuation in let task = Task { for char in fullText { try await Task.sleep(nanoseconds: 50_000_000) // 每个 token 间隔 50ms continuation.yield(String(char)) } continuation.finish() } continuation.onTermination = { _ in task.cancel() } } } }

onTermination这段很关键。当用户点击停止时，UI 层取消 Task，流还会继续跑吗？如果 AsyncStream 没有感知取消，底层任务不会终止，token 照样往 UI 发。把task.cancel()挂在onTermination里，才能实现"取消真正生效"。这是我踩过的最深的坑之一，一开始没处理这个问题，导致取消生成后界面还在持续收到文本。

5.3 输入框与发送逻辑

输入框我用TextField加.onSubmit处理发送。这里有个需要注意的点：发送后要立刻清空输入框、收起键盘、滚动到底部，三件事的时序要处理好。

TextField("输入消息", text: $inputText, axis: .vertical) .lineLimit(1...5) .onSubmit { send() } func send() { let trimmed = inputText.trimmingCharacters(in: .whitespacesAndNewlines) guard !trimmed.isEmpty else { return } inputText = "" viewModel.send(trimmed) }

注意axis: .vertical允许输入框多行扩展，超过 5 行自动滚动，这是 iOS 16 之后支持的特性。处理完输入框后，UI 还要处理"正在输入"的禁用状态——当 Agent 正在生成或正在调用工具时，发送按钮应该禁用或变成停止按钮。这个细节直接影响可用性，用户连点了两次发送，消息序列就乱了。

我做了两种模式切换：idle 状态下显示发送图标，.streaming或.toolCalling状态下显示停止方块图标。点击停止就调用viewModel.stopGenerating()，走状态机的取消路径。

5.4 运行效果与验收清单

跑通 Demo 后，我建议你用这个验收清单自查一遍，几乎全是日常会踩的点：

流式输出时列表是否平滑滚动，是否出现跳动？
点击停止后，Agent 状态是否在 1 秒内回到 idle，token 是否彻底停止？
连续触发两次工具调用，工具卡片是否按顺序排列在消息流里？
后台执行工具时界面是否 60 帧稳定，有没有卡顿或内存暴涨？
旋转屏幕或者切换到后台，再回到 App，消息列表是否保持正确状态？

每个问题背后都是一个优化点。比如第 5 项，要处理 scene phase，在进入后台时暂停流式渲染，回到前台再恢复。这个我没在 Demo 里做完，但它真的是真实场景里用户会遇到的。

6. 常见问题与排查技巧实录

最后聊我在开发这套框架过程中遇到的典型问题，有些已经解决，有些至今还在优化，分享出来供各位参考。

6.1 列表刷新卡顿，帧率掉到 30

刚开始我把每个 token 写入@Published var messages数组，结果列表以每秒 20~30 次的频率重建，很快就卡了。原因是每条消息整个视图都被重算，而 SwiftUI 的 diff 对数组的 instrument 开销有限。

解决办法是消息模型中实现高效的Equatable，让 SwiftUI 对没有变化的行跳过 diff。另外，把MessageRow做成@ViewBuilder拆分成多个子视图，每个子视图只绑定自己关心的数据。经过这两步优化，帧率从 30 提到 60。

经验：流式界面优化第一原则是减少不必要的视图重建，而不是优化文字的渲染速度。

6.2 工具调用结果乱序

有一段时间用户提到，工具 A 的结果还没回来，工具 B 的结果先显示了，消息顺序混乱。排查后发现是并发任务里两个工具调用同时发起，各自完成后直接 append 到消息列表，没有经过 Agent 内核的状态机。

解决方案是：工具调用统一走 Agent 内核派发，内核用AsyncStream把工具结果封装成有序事件，UI 严格按事件顺序渲染。这条规则我写在团队开发规范里：任何对消息列表的修改，必须经过 AgentCore actor。

6.3 SwiftUI 预览与 Actor 的兼容性

开发时用 Xcode Preview 调试，结果Preview一直报错，说是调用了一个 actor isolated 的方法。查了半天发现 Preview 的主体本身运行在主线程，但 AgentCore 是@MainActor隔离的，初始化时调用了非隔离方法。

解决办法是在预览代码里显式标注@MainActor，或者将 AgentCore 的初始化方法设置成nonisolated。这里想提醒一句：不要偷懒把所有类都标成@MainActor，当 AgentCore 需要处理后台网络回调时会很被动，设计 actor 边界时要把 UI 线程和网络线程的隔离边界划清楚。

6.4 状态漂移的隐性问题

用户连续发送多条消息时，界面上消息显示一切正常，但有时候最后一条回答会出现在错误的位置。这个问题的根源是：ViewModel 持有 message 数组，而 Agent 内核也有自己的消息快照，两个地方没有做一致性校验。

我后来加了一层同步机制：Agent 内核每次发送更新事件时带一个全局递增的sequence，ViewModel 按sequence排序渲染。只要有乱序或者重复，就按sequence重排。从那以后，这类问题几乎绝迹。

这个问题不要等到用户报告才处理，很容易导致内容错乱。建议在设计阶段就把消息数组的"唯一数据源"问题想清楚，别两处维护同样的数据。

实践体会

写这套框架的一个月里，我调整最多的是状态机的边界。一开始把 UI 动画状态也放进 Agent 状态机里，很快变得一团糟；后来彻底分开，Agent 只管业务逻辑状态，UI 动画交给 SwiftUI 自己管，才清爽起来。这套框架目前支撑了我们两个内部项目，目前已经跑得很稳。

说到底，SwiftUI 是一个非常适合表达 Agent 交互的框架，只要把状态管理和跨线程边界想清楚，写起来会非常顺手。如果你准备做一个智能助手类 App，或者想让现有 App 具备 Agent 能力，希望这篇文章能让你少走几个弯路。后面如果有精力，我打算把工具调用链的测试方法也整理出来，那个话题也挺有意思。