产品概览

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 管理逻辑。

推荐阅读顺序

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