Android Compose版本的AI组件库来了。

把几份资料交给手机里的 AI，让它整理一份报告。它开始读文件、查资料，还把一部分工作交给另一个 AI 助手。可屏幕上只有"正在处理"和一个转圈的动画。

用户很难判断：它现在在做什么？哪些步骤已经完成？是需要补充信息，还是某一步卡住了？等它准备保存文件，又该怎样先查看内容、修改参数，再决定允许还是拒绝？

有些任务还需要用户选日期、填地址、确认偏好。如果 AI 只发来一串文字问题，用户就得在聊天里逐项回答；直接显示一张可填写的表单，操作会清楚得多。

当 AI 从回答问题走向使用工具、执行任务，应用界面也需要跟上：显示计划和进度，展开工具的输入与结果，在关键操作前等待确认，再把用户的选择交回 AI。聊天气泡之外，还有一整段需要接好的交互。

AI Elements for Kotlin 是面向 Android 的原生 AI 交互组件库。它把聊天、工具审批、任务过程、文件与媒体、生成式 UI 做成可以组合的组件，让这些能力接进已有应用。Compose 是 Android 的原生界面框架，组件的颜色、字体和样式也可以与应用保持一致。

Web 上有 AI Elements，Flutter 有 Flyer Chat，React Native 有 Gifted Chat 等界面方案。Kotlin / Compose 也已有聊天 UI SDK。这个项目补齐的是原生 Android 应用中的 Agent 交互组件：工具审批、子 Agent、任务过程和可操作的结果，可以配合现有的页面与 AI 服务使用，减少重复开发。

0.3.0 已发布到 Maven Central，使用 Apache 2.0 许可证。源码、双语文档和可安装的 Demo 已公开。下面从实际使用场景开始，介绍组件能力、协议支持、架构与接入方式。

哪些应用适合接入

如果你已经有 Kotlin / Compose 应用，想给它加入 AI 助理，这个库可以提供消息、内容和工具交互，保留自己的业务页面与后端。

研发或知识类助手可以组合代码、引用、PDF、文件、Terminal 和 diff；多步任务可以组合计划、子 Agent 与电脑面板，让执行过程有地方查看；需要用户选择和填写的任务，可以通过 A2UI 原生表单继续操作。

希望在设备上运行 Agent 的应用，还可以按需添加模型 API、文件、记忆、MCP、浏览器和调度能力。只需要某个组件时，不必同时采用完整的 Agent 运行时。

工具调用与审批

工具调用可能刚收到参数，也可能正在执行，或者已经失败。如果它还在等用户批准，就不能先显示成"完成"。这几种状态混在同一个聊天气泡里，用户很难判断下一步该不该操作。

库里的工具卡片会显示输入、运行状态、结果和来源。点开可以查看参数与返回值；来自 MCP 服务器的工具可以显示服务器名称。委派给子 Agent 的任务、加载技能和普通函数调用，也有各自的展示方式。

更重要的是，审批按钮需要真的连到执行流程。用户允许，工具才继续；用户拒绝，后端要收到这个决定。协议支持时，还可以附上拒绝理由、编辑参数后批准，或者在当前会话内记住允许选择。

Agent 也可能只是需要补充信息。这时可以显示表单，支持文字、数字、布尔、单选、多选和用户自己填写的答案。AskUser 对应 Pydantic AI Harness 的提问工具，设备端与服务端使用一致的定义和结果形式。

下面这段录屏展示了一个最小闭环：用户提出请求，界面出现计划和推理，工具停在待审批状态。允许后，剪贴板工具在 Android 设备上执行，然后继续输出回复。这里使用的是内置离线演示 Agent，录屏来自真实模拟器，工具确实在设备上运行。

应用可以复用这段交互，再按自己的产品要求决定审批策略。界面负责让用户参与，权限、可信服务器和工具执行规则仍要由应用与后端明确处理。

支持哪些 AI 协议

本库支持 AI SDK、AG-UI、MCP / MCP Apps、A2A、ACP 和 A2UI，可按现有后端和需要的能力选择接入。

你要连接什么	对应标准	主要用途
Agent 服务与用户界面	AI SDK UI Message Stream、AG-UI	流式文本、工具、状态、进度和用户交互
Agent 与外部工具服务器	MCP	获取工具、资源和 prompt
MCP 工具自带的交互视图与 App	MCP Apps	给工具视图提供宿主、消息桥接和权限边界
一个 Agent 与另一个 Agent	A2A	发现远程 Agent、执行任务、保留会话上下文、接收产物
App 与编码 Agent	ACP	Session、计划、文件操作、diff 和权限询问
Agent 返回的界面与用户	A2UI	传递声明式表单或卡片，再把用户操作返回 Agent

这也是库里要做协议适配的原因。网络上仍遵循这些标准；进入 App 后，再转换成一套消息、事件和交互状态，供 Compose 组件显示。这些 App 内部对象不会被当成一个新协议发到网络上。

UI 根据上游提供的类型、来源、类别和位置显示内容。它不需要猜工具名字，也不需要知道一条 SSE 事件应该怎么解析。

各协议支持的交互仍有区别。例如 AI SDK 的工具审批可以带理由，但不提供修改参数；ACP 主要返回 Agent 给出的权限选项；AG-UI 和设备端可以返回更丰富的审批答案。界面按后端实际支持的能力提供操作。

v0.3.0 的 AI SDK 发布验证范围是 v5/v6 UI Message Stream 和 v4 Data Stream 回退，不能据此宣称兼容最新全部版本。具体版本、回退和限制在协议文档里分别列出。

架构与自定义后端

开发者可能已经有自己的 Agent 服务，也可能用 Pydantic AI、LangGraph，或者想让任务在设备上运行。UI 不应该强迫应用重选一套后端。

本库分成几个层次：

层次	负责什么
ai-elements-chat	消息、事件、backend 契约、controller、审批与输入；无网络、无 Compose
ai-elements-core	协议客户端、模型 API、Agent 循环、MCP、Skills 和认证；无 Compose
ai-elements-ui	Compose 组件与主题，只依赖 chat
可选模块	A2A、ACP、Koog、生成式 UI、MCP Apps 和端侧能力，按需添加

已有标准协议服务，就使用相应 backend；自己的协议可以实现 ChatBackend，把会话转换为事件流。认证、不同协议的能力差异和数据保存策略，仍在各自层次处理。

只需要界面组件，可以只引 UI 和 chat。想保留自己的页面布局，就分别使用 Conversation 和 PromptInput；想先跑起来，则可以使用完整的 Chat(controller)。

这意味着你可以保留现有原生 App、业务页面和服务端，逐步接入需要的交互。UI 不依赖协议和 Agent 运行时，接入时可以独立选择 backend、页面布局和 renderer。

任务计划、子 Agent 与执行过程

当一个 Agent 把工作委派出去，用户不应该只看到"任务中"。子 Agent 以嵌套运行显示在委派任务内，可以展开查看它的回复、工具和审批。

任务计划也有单独的组件。它可以显示当前步骤和完成状态，配合共享状态及活动信息，让用户知道一项长任务做到哪里。

浏览网页、执行命令、读取和编辑文件时，可以进一步打开 Agent 的电脑面板。这里按步骤展示截图、终端输出或 diff，下面有时间线和前后切换控件。它可以跟随最新步骤，也允许用户返回先前步骤查看。

Terminal 保留常见的颜色、进度重绘和链接，编辑内容可以显示 unified diff。长日志有显示范围和有限 scrollback，步骤与截图也按长运行的需求组织。

回看还有不同精度：保存消息后，可以查看其中已经记录的工具步骤；AG-UI 的事件日志可以按录制节奏重新构建文本增量和状态变化；支持 session/load 的 ACP Agent 可以提供自己的运行记录。

这不代表所有协议都有断点续传。当前断流后的 Retry 会重新请求一轮；事件回放和网络重连是两件事，存储与保留策略也由应用决定。

生成式 UI：让 AI 返回表单

如果助理让用户选择日期、填地址、勾选偏好，一张表单就比在聊天里来回核对字段更直接。

ai-elements-genui 把 A2UI v1.0 surface 渲染成 Compose 组件，内置 Basic Catalog，也可以扩展为自己的设计系统。用户填到一半时，更多内容继续流入或表单滚出屏幕，输入状态仍能保留。点下按钮后，操作通过相应协议返回 Agent，继续后续任务。

JsxPreview 也使用这套组件目录，支持常见控件、数据绑定和 action。它解析标签与数据，不执行模型生成的任意 JavaScript。消息里的 JSX/TSX 代码块可以显示实时预览，也可以切回源码。

如果 MCP 工具已经自带交互式 HTML 页面，可以引入 MCP Apps 宿主。它在沙箱 WebView 中运行，使用独立 origin、资源声明的 CSP 和标准桥接。视图可以调用允许给 app 的工具、发送消息、更新下一轮模型上下文、打开链接或请求全屏。

因此，本库中的"原生"也有明确范围：聊天与 A2UI/JSX 组件使用 Compose；默认 Mermaid 和 MCP Apps 使用 WebView。原生 Mermaid 是需要明确 opt-in 的实验性可选模块。

消息内容与会话操作

完整的 AI 界面还要处理代码、引用、文件和会话操作。库里提供流式 Markdown、代码高亮、数学公式、Mermaid、来源引用、上下文用量和模型选择器；图片能查看与缩放，视频和音频有对应播放器，PDF 可以在应用中预览和阅读，其他办公文档通过系统应用打开。

会话层包含发送、停止、重试、重新生成的分支、checkpoint，以及运行期间的消息队列。消息可以用于应用自己的持久化存储，但历史如何保存、保留多久、进程重建以后如何恢复，仍由应用决定。ViewModel 能应对配置变化，不能单独解决进程死亡。

语音使用设备上的 SpeechRecognizer 和 TextToSpeech，可以听写、朗读回复、选择引擎与音色，也可以通过同一个 controller 开启免手持 VoiceMode。遇到审批或用户提问时，语音模式会暂停并引导回到聊天。应用需要处理相应权限与设备能力。

代码类场景还可以选用 Artifact、WebPreview、Terminal、StackTrace、TestResults、FileTree、Commit、SchemaDisplay、PackageInfo、EnvironmentVariables、Sandbox 和 Snippet。工作流画布 WorkflowCanvas 则提供自定义节点、工具栏和面板位置。

这些组件负责呈现后端已经提供的内容，不会凭空生成执行结果或业务流程。图册目前有 65 个展示场景，每个给出图片、用途、imports、经过编译的示例和 API 链接，方便先看清效果，再选择需要的部分。

在应用内运行 Agent

服务端模式继续连接自己的 AI SDK、AG-UI、A2A 或 ACP Agent。参考服务用 Pydantic AI、Pydantic AI Harness 和官方 SDK，提供无需模型密钥的 scripted model，用来验证协议与界面。

设备端模式可以通过 OpenAI Chat Completions / Responses、Anthropic Messages、Gemini、Ollama 等 API 运行 Agent。AgentHarness 将模型与能力组合成 ChatBackend；Koog 也是可选的运行时集成。

这里的能力按模块拆开：

需要什么	可以添加的能力
处理资料与文件	工作区读写、编辑、查找，以及用户通过 SAF 分享的文件夹
保留计划与记忆	任务计划、跨会话记忆，以及按配置注入 MEMORY.md
执行命令	可插拔 Shell 运行时和可选 Alpine / PRoot 沙箱
浏览页面	离屏 WebView 的导航、快照、点击、输入与截图，模型可接收页面图片
接外部工具	MCP 服务器的工具、资源和 prompt，以及受保护服务器的 OAuth 接入
加载技能与委派	按需加载 SKILL.md，使用本地或远程子 Agent
使用手机能力	按需接设备信息、剪贴板、日历、联系人、定位、通知和平台 TTS
定时任务	WorkManager 调度，应用提供后台构建 Agent 的入口

它们不用和 UI 一起全部引入。端侧工具的名称与行为对应 Pydantic AI Harness 的公开约定，便于两端使用一致的交互语义。

Provider 配置可接模型列表和选择器，内置 store 使用 Android Keystore 加密保存凭据。MCP 接入可以处理 OAuth metadata、PKCE、工具缓存与服务器状态；某个服务器失败时，可以报告状态并在本轮跳过，而不必让整轮对话一起失败。

可信服务器、凭据来源、Android 权限、审批策略和资源生命周期，都仍需要应用明确配置。组件不会替应用自动获得权限。

手机、平板与折叠屏适配

组件使用 Material 3 Expressive，可以调整颜色、字体和 shape，也可以替换单个工具、数据 part 或代码块的 renderer。附件加载可以接自己的缓存、HTTP 栈和认证，不需要 fork 整个 Conversation。

手机上空间有限，电脑面板使用 bottom sheet；较宽的聊天容器可以显示侧栏，并接入 Material 3 list--detail 的 extra pane，适配平板和折叠屏。

平板或展开的折叠屏上，历史列表与当前会话可以并排，Agent 的电脑面板也可以放在额外一栏。它按聊天容器自身的空间适配，不是把手机界面简单拉宽。

可选通知模块通过 AgentProgress 展示运行状态。Android 16 支持 Live Update，较旧系统使用普通进度通知；等待审批时引导用户回到应用查看内容，完成后可以提示回复就绪。前台服务、后台运行时长和通知权限，由应用决定。

字符串提供英语、简体中文、繁体中文和日语，也包含 content description、触摸目标与 TalkBack 语义。这些是把 Agent 交互放进原生应用时需要一起考虑的部分。

怎么接入 Compose

连接 AI SDK / AG-UI 服务时，先用 BOM 对齐版本，再添加 UI 和 core：

dependencies {
    implementation(platform("io.github.junelegency:ai-elements-bom:0.3.0"))
    implementation("io.github.junelegency:ai-elements-ui")
    implementation("io.github.junelegency:ai-elements-core")
}

以 AG-UI 为例，在 Compose activity 的 setContent 中使用：

import dev.ai.elements.core.protocol.agui.AgUiBackend
import dev.ai.elements.ui.chat.Chat
import dev.ai.elements.ui.chat.rememberChat
import dev.ai.elements.ui.theme.AiElementsTheme

AiElementsTheme {
    Chat(rememberChat { approver ->
        AgUiBackend(
            "https://agents.example.com/api/agui",
            approver = approver,
        )
    })
}

把地址换成自己的服务即可继续接入。网络权限、debug HTTP 配置、ViewModel 管理 controller 和自定义布局的完整示例在快速开始文档里。只需要界面时可以只引 UI 与 chat，自己的协议实现 ChatBackend，再映射到消息与事件。

采用前要核对几项现实条件：本库目前只支持 Android；UI/core 的 minSdk 为 24，部分可选模块为 26。测试基线是 JDK 21、Gradle 9.8.0、AGP 9.4.1（内置 Kotlin 2.4.20）、compileSdk 37.2 和 Java 17 字节码。

Compose 1.13.0-alpha03 与 Material 3 1.5.0-alpha29 是预发布依赖。BOM 对齐的是本库，不会替应用统一所有 AndroidX；A2A 有 desugaring 要求，PRoot 有打包与许可证要求。安装页分别说明，接进正式工程前需要确认。

运行稳定性与使用限制

评估 SDK 时，可以先用 Demo 和 65 个图册场景，查看浅深色、内容类型、审批和长任务是否符合自己的产品交互，再把需要的部分接到真实后端。图册提供实际 Android 截图、imports、可编译示例和 API 链接，方便对照接入。

流式消息支持用户主动停止、重试和运行中的消息队列；用户向上滚动查看旧内容时，不会强行把页面拉回最新回答。长工具输出有显示边界，终端保留有限 scrollback，步骤和截图采用适合长运行的列表组织。

应用仍要处理自己的生命周期。Controller 放在 ViewModel 中可以保留配置变化时的会话；进程回收后的历史恢复需要应用持久化消息。断流后的 Retry 会重新发起请求，不代表所有协议都有自动续传。长任务在后台继续运行时，前台服务和通知策略也由应用决定。

生成式 UI 与外部视图有各自边界：JSX 不执行任意 JavaScript，MCP Apps 使用沙箱与 CSP，Android 权限和可信工具策略由应用明确配置。这些机制帮助接入方管理交互，不是对任何服务器或模型输出的绝对安全保证。

本库目前的适用范围、minSdk、alpha 依赖和额外配置在安装页列出。把它们与自己工程的工具链、设备范围和真实后端一起确认，再决定引入哪些模块。

如果你也在做原生 Android 的 AI 功能，希望少重复写一套工具审批、运行过程和表单界面，可以先装 Demo，挑需要的组件试着接入。

如果你觉得这块 Kotlin 原生 AI 交互生态值得继续完善，欢迎给项目一个 star，并通过 issue 反馈接入时缺少的能力，以及难以实现的交互。

项目与源码：github.com/JuneLeGency...

中文文档：junelegency.github.io/ai-elements...

英文文档：junelegency.github.io/ai-elements...

Demo 与 Release：github.com/JuneLeGency...

Maven Central：central.sonatype.com/artifact/io...

参考：

• Flyer Chat / Flutter
• Gifted Chat / React Native
• AI Elements Reasoning
• Stream Android Compose SDK
• 本库架构与协议文档