产品概览

AgentOS 是一套面向智能应用开发的运行时、接口与 SDK 体系。

今天很多开发者已经不是“先完整读文档，再自己一点点接入”，而是“先看清场景和约束，再把任务交给 AI 编程工具落代码”。
因此，这套文档现在同时提供两类内容：

• 给人做判断的场景说明、模块边界和阅读路径
• 给 AI 编程工具直接执行的提示词、事实清单和最小示例

对外部 App 开发者来说，通常会关注三件事：

1. 如何接入 AgentOS 提供的能力
2. 如何在自己的应用中组织会话、消息、工具和状态
3. 如何选择合适的 SDK、UI 组件和服务端接口

适用对象

• 希望在 Web、Node、Dart、Flutter 应用中集成智能会话能力的开发者
• 需要调用 AgentOS API 或 SDK 的客户端开发者
• 需要理解 AgentOS 运行机制与扩展点的高级开发者

推荐阅读方式

传统方式

你自己阅读 quickstart、guide 和 example，然后手工完成接入。

AI 辅助方式

1. 先判断你的目标是模型网关、Agent 编排还是 RAG 服务
2. 再把对应页面里的“推荐提示词”和“最小事实清单”复制给 AI 编程工具
3. 让 AI 在你的真实代码仓库中完成接入或改造
4. 最后用“人工验收清单”复核关键事实

如果你已经在用 Claude、Codex、Cursor 或 ChatGPT 编码，推荐优先走第二种方式。
对应入口见 AI 辅助接入。

常见接入场景

1. App 已经有自己的复杂 Agent，只需要模型能力

这类场景优先使用 modelkit，不必接 agentkit。
AgentOS 网关对外提供 OpenAI 兼容接口，因此你通常可以直接使用官方 OpenAI SDK：

• baseURL：如果直接使用 OpenAI SDK，chat 使用 ${AgentOS 根地址返回的 baseUrl}/modelkit/chat/v1
• apiKey：registerBundle / POST /appkit/register 返回的 Bearer token
• model：sdk.modelkit.listModelsByTask(ModelTask.chat) 或 GET /modelkit/models 中 task=chat 的 model.id

适合：

• 你自己管理 prompt、记忆、状态机和工具编排
• 你已经有定制化 agent runtime
• 你只想复用 AgentOS 的模型网关与统一鉴权

2. App 自己提供 tool，但不想自己组装 agent

这类场景优先使用 agentkit。
你把工具能力暴露给 AgentOS，再由 AgentKit 负责会话、消息流、工具调用和回调编排。

3. App 需要 TTS

可以继续使用 OpenAI SDK 的 TTS 接口，对应 AgentOS 的 /modelkit/tts/* 能力。

apiKey 仍来自注册返回的 token，模型从 ModelKit 的 task=tts 列表中选择；直接使用 OpenAI SDK 时，baseURL 指向 /modelkit/tts/v1。

4. App 需要 ASR

可以继续使用 OpenAI SDK 的 ASR 接口，对应 AgentOS 的 /modelkit/asr/* 能力。

apiKey 仍来自注册返回的 token，模型从 ModelKit 的 task=asr 列表中选择；直接使用 OpenAI SDK 时，baseURL 指向 /modelkit/asr/v1。

5. App 需要 Embeddings

可以继续使用 OpenAI SDK 的 embeddings 接口，对应 AgentOS 的 /modelkit/embedding/* 能力。

apiKey 仍来自注册返回的 token，模型从 ModelKit 的 task=embedding 列表中选择；直接使用 OpenAI SDK 时，baseURL 指向 /modelkit/embedding/v1。

6. App 需要现成 RAG 服务，而不是自己封装 embeddings 和向量库

这类场景优先使用 ragkit。
它更适合需要直接使用查询、文档管理、同步和知识库能力的应用，而不是自己从底层去封装 embeddings、ChromaDB 或 docs 管理逻辑。

7. App 需要获取 AgentOS 用户身份

这类场景使用 authkit。
它让第三方 App 能安全获取 AgentOS 用户授权，拿到用户身份（userId、name、avatarUrl），用于跨设备用户关联或数据隔离。

8. App 需要发现附近设备

这类场景使用 discoverykit。
它让 App 能发现同一局域网中的其他 AgentOS 设备和 App 实例，常与 TransferKit 配合使用。

9. App 需要在设备间传输文件

这类场景使用 transferkit。
它提供局域网内跨设备的文件传输能力，包括发送、接收、进度跟踪和历史管理。

推荐阅读顺序

1. AI 辅助接入
2. 技术选型
3. TypeScript 快速开始 或 Dart 快速开始
4. 整体架构
5. 对应语言的 examples/