技术选型
如果你准备把接入工作直接交给 AI 编程工具，这一页的目标不是让你先学会所有细节，而是先判断该把 AI 引导到哪条实现路径上。
先看结论
| 你的目标 | 推荐入口 | 为什么 |
|---|---|---|
| 直接调用 HTTP 接口，自己管理鉴权和请求 | agentos-api | 最贴近网关能力，适合服务端、网关或强定制客户端 |
| App 已有自己的复杂 agent，只需要模型层 | modelkit + OpenAI SDK | 直接复用 OpenAI 兼容接口，不必接入 AgentKit |
| App 自己提供 tool，但不想自己组装 agent | agentkit | AgentKit 负责会话、消息流、工具调用与回调 |
| App 需要 TTS / ASR / Embeddings | modelkit + OpenAI SDK | 接口风格与 LLM 一致，适合统一接入 |
| App 需要现成 RAG 服务而不是自己封装向量层 | ragkit | 直接使用 query、docs 管理、同步和知识库接口 |
| 在 Web 或 Node.js 中快速接入 | agentos-sdk-ts | 已封装注册、鉴权、模块访问和流式接口 |
| 在 Dart / Flutter 中快速接入能力层 | agentos-sdk-dart | 已封装 AgentOS 网关访问，并对 Dart 类型做了适配 |
| 在 Flutter 中快速落地聊天 UI | chatkit_dart | 直接提供 AgentSidebar、运行时和会话控制器 |
给 AI 编程工具的选型提示词
先把下面这段发给 AI，让它先判断方向，再开始写代码：
text
请先不要急着写代码，先根据我的场景判断我应该优先接 modelkit、agentkit 还是 ragkit，然后再按判断结果直接实现。
我的情况：
- 项目类型：[Node.js / TypeScript / Dart / Flutter]
- 当前状态：[新项目 / 已有 OpenAI 接入 / 已有自定义 agent / 已有知识库]
- 目标：[只接模型 / 接工具和 agent 编排 / 接 RAG / 接 TTS / 接 ASR / 接 embeddings]
请遵守这些 AgentOS 事实：
- 如果我已有自己的复杂 agent，通常优先 modelkit，不必先接 agentkit
- 如果我有 tool，但不想自己处理会话、工具调用链和消息编排，通常优先 agentkit
- 如果我需要的是现成知识库查询、文档管理和同步能力，通常优先 ragkit
- 如果直接使用 OpenAI SDK，chat 的 baseURL 是 `${AgentOS 根接口返回的 baseUrl}/modelkit/chat/v1`
- apiKey 来自 registerBundle 或 POST /appkit/register 返回的 Bearer token
- model 来自 sdk.modelkit.listModelsByTask(ModelTask.chat) 返回的 model.id 或可用 alias
- 不要臆造不存在的 SDK 方法和接口字段
请输出：
1. 你推荐的模块和理由
2. 不推荐路径的原因
3. 你接下来会如何在项目里实现场景化选择
场景 1：你已经有自己的 agent，只需要模型网关
优先使用 modelkit，并直接调用 OpenAI 官方 SDK。
在 AgentOS 里，这几个值的对应关系是：
| OpenAI SDK 参数 | AgentOS 中的来源 |
|---|---|
baseURL | ${GET / 返回的 baseUrl}/modelkit/chat/v1 |
apiKey | registerBundle / POST /appkit/register 返回的 Bearer token |
model | sdk.modelkit.listModelsByTask(ModelTask.chat) 或 GET /modelkit/models 中 task=chat 的 model.id |
适合同一套方式接入：
- Chat Completions
- TTS
- ASR
- Embeddings
也就是说，如果你的 App 自己已经有复杂的 prompt、记忆、工具路由和状态管理，AgentOS 更像是你的统一 AI Gateway。
推荐交给 AI 的任务描述：
text
这是一个已有自定义 agent 的项目。请不要引入 agentkit，也不要重写我的 agent 编排。只把模型调用层切换到 AgentOS 的 modelkit/OpenAI 兼容网关，并保留我现有的 prompt、记忆、工具路由和状态管理。场景 2：你有 tool，但不想自己组装 agent
优先使用 agentkit。
适合：
- 你希望自己提供工具能力
- 但不想自己处理 agent 会话、工具调用链、回调流和消息状态
- 你更希望把 Agent 能力交给 AgentKit 编排
推荐交给 AI 的任务描述：
text
这是一个我自己提供 tool 的项目，但我不想自己维护 agent 会话、消息流和工具调用链。请优先按 agentkit 路径设计接入方案，不要只给 modelkit 聊天示例。场景 3：你需要 TTS / ASR / Embeddings
优先仍然是 modelkit，并继续使用 OpenAI 兼容 SDK。
推荐原因：
- 与 chat 接口的接入方式一致
- 网关地址、token 和 model 选择规则一致
- 容易在现有 OpenAI SDK 客户端中复用
推荐交给 AI 的任务描述：
text
请在现有 OpenAI SDK 客户端基础上，把 TTS / ASR / embeddings 的调用改成 AgentOS 兼容接入，并复用同一套注册、鉴权和 ModelKit 模型查询方式；不同任务的 baseURL 请分别指向 `/modelkit/tts/v1`、`/modelkit/asr/v1` 或 `/modelkit/embedding/v1`。场景 4：你需要现成 RAG 服务
优先使用 ragkit，而不是自己从 embeddings 开始往上搭。
适合：
- 需要知识库查询
- 需要文档入库与管理
- 需要同步和维护知识库内容
- 不想自己封装 embeddings、向量库和 docs 生命周期
推荐交给 AI 的任务描述：
text
我需要的是现成 RAG 服务，而不是只拿 embeddings 自己搭向量层。请优先按 ragkit 路径设计文档管理、同步和查询接入，不要只返回一个 embedding 示例。你应该用哪个仓库或模块
agentos-api
适合需要直接对接服务端接口、鉴权、请求响应模型的场景。
也适合需要自己直接访问以下能力的场景：
modelkit/chat/*modelkit/tts/*modelkit/asr/*modelkit/embedding/*agentkit/*ragkit/*
agentos-sdk-ts
适合 Web 或 Node.js 开发者，以 TypeScript 方式接入 AgentOS 能力。
如果你不想自己处理：
- bundle 注册
- token 保存
- 模块封装
- SSE 订阅
那么 SDK 比直接调 HTTP 更省事。
agentos-sdk-dart
适合 Dart / Flutter 开发者，以 Dart SDK 方式接入 AgentOS。
chatkit_dart
适合在 Dart / Flutter 应用中快速集成聊天式 UI 与上层交互体验。
典型路径
Web / Node.js
- 先启动或连接 AgentOS 网关
- 如果你已有自己的 agent，优先直接走
modelkit的 OpenAI 兼容接口 - 如果你要把 tool + agent 编排交给平台，改走
agentkit - 如果需要更细的协议控制，再回头补看
agentos-api
Dart / Flutter
- 先用
agentos-sdk-dart跑通基础连接和消息请求 - 如果需要现成聊天界面，再接
chatkit_dart - 如果要自己做 UI，只保留 SDK 即可
AI 扩展能力
- 需要
chat completions：优先modelkit - 需要
tts：优先modelkit - 需要
asr：优先modelkit - 需要
embeddings：优先modelkit - 需要现成 RAG：优先
ragkit
平台或基础设施开发
如果你要做的是：
- 网关部署
- 接口联调
- 定时任务、RAG 或工具系统集成
那就应该优先看 agentos-api。
推荐阅读顺序
- 如果你要先把正确上下文交给 AI：看 AI 辅助接入
- 如果你只想尽快接入：先看对应语言的 quickstart
- 如果你在做 Dart App：优先看
agentos-sdk-dart，需要 UI 时再接chatkit_dart
人工验收清单
- AI 是否先做了模块判断，而不是上来就默认给
agentkit - AI 是否把“已有自定义 agent”与“有 tool 但不想自己编排”区分清楚
- AI 是否在 RAG 场景下给出文档管理与查询方案，而不是只给 embeddings 片段
- AI 是否正确说明了
baseURL、apiKey、model的来源