AgentOS 开发文档

简体中文

English

简体中文

English

主题

Dart 快速开始 ​

本文档基于 agentos-sdk-dart 与 chatkit_dart，帮助你在 Dart 或 Flutter 应用中快速跑通 AgentOS。

如果你正在用 Claude、Codex、Cursor 或 ChatGPT 编码，这一页也可以直接当成“给 AI 的执行说明书”来用。

推荐路径 ​

  • 只接能力层：先用 agentos-sdk-dart
  • 需要聊天 UI：在 SDK 之上结合 chatkit_dart

你将完成什么 ​

  • 初始化 Dart SDK
  • 连接到 AgentOS 网关
  • 注册一个 app bundle
  • 查询模型并发送一条消息
  • 了解何时接入 ChatKit

推荐提示词 ​

Dart 最小接入 ​

text
请在一个 Dart 项目里完成 AgentOS 最小接入，并直接给出可运行代码，而不是只解释步骤。

目标：
- 使用 agentos_sdk 连接 AgentOS 网关
- 调用 registerBundle 完成应用注册
- 调用 modelkit.listModelsByTask(ModelTask.chat) 获取可用 chat 模型
- 发送一次最小 chat 请求并打印结果

必须遵守的 AgentOS 事实：
- 网关地址示例是 http://127.0.0.1:8888
- 先初始化 AgentOSSDK，再 registerBundle，再 listModels，再发 chat 请求
- model 应来自 listModelsByTask(ModelTask.chat) 返回结果，不要臆造模型 id
- 如果文档里已有 subscribe 和事件处理器，请优先贴近文档示例结构

请输出：
1. pubspec 依赖
2. 完整示例代码
3. 运行命令
4. 我应该看到的成功结果

Flutter + ChatKit 接入 ​

text
请帮我在 Flutter 项目里接入 AgentOS，并区分清楚 agentos_sdk 与 chatkit_dart 的职责。

要求：
- agentos_sdk 负责连接网关、注册 bundle、调用能力层
- chatkit_dart 负责聊天 UI、runtime 和 session controller
- 不要把 ChatKit 当成底层 SDK 替代品
- 如果我已经有自己的页面和状态管理，请优先保留现有结构，只在需要聊天 UI 的地方接入 AgentSidebar

请输出：
1. 依赖配置
2. 最小 runtime 初始化代码
3. AgentSidebar 挂载示例
4. 我需要注意的宿主集成点

前置条件 ​

  • Dart SDK 已安装
  • 如果你要做 Flutter UI，已安装 Flutter stable
  • 本地或远程可访问的 AgentOS 网关

第 1 步：添加依赖 ​

如果你只需要能力层：

yaml
dependencies:
  agentos_sdk: ^0.1.0

然后执行：

bash
dart pub get

如果你还需要 Flutter 聊天界面，再额外加入：

yaml
dependencies:
  chatkit_dart: ^0.1.0

并执行：

bash
flutter pub get

第 2 步：使用 SDK 跑通最小调用 ​

下面的示例整理自 agentos-sdk-dart/example/agentos_sdk_dart_example.dart。

dart
import 'package:agentos_sdk/agentos_sdk.dart';

Future<void> main() async {
  final sdk = AgentOSSDK(baseUrl: 'http://127.0.0.1:8888');

  final version = await sdk.agentos.getVersion();
  print('AgentOS version: ${version.version}');

  final registration = await sdk.agentos.registerBundle(
    bundleId: 'com.example.agentos.docs',
    appGroupId: 'com.example.agentos',
  );
  print('Registered bundle: ${registration.bundleId}');

  sdk.agentos.connectionEvents.listen((event) {
    print('Subscribe status: ${event.status.name}');
  });

  await sdk.agentos.subscribe(_DemoEventHandler());

  final models = await sdk.modelkit.listModelsByTask(ModelTask.chat);
  print(models.map((model) => model.alias).toList());

  final completion = await sdk.modelkit.chat.create(
    model: models.first.id,
    messages: <OpenAIChatCompletionChoiceMessageModel>[
      OpenAIChatCompletionChoiceMessageModel(
        role: OpenAIChatMessageRole.user,
        content: <OpenAIChatCompletionChoiceMessageContentItemModel>[
          OpenAIChatCompletionChoiceMessageContentItemModel.text(
            'Hello from AgentOS docs.',
          ),
        ],
      ),
    ],
  );

  print(completion.choices.first.message.content?.first.text);
}

class _DemoEventHandler extends AgentOSEventHandler {
  @override
  Future<void> onWelcome(Welcome welcome) async {
    print('Welcome bundleId: ${welcome.bundleId}');
  }
}

最小事实清单 ​

这是最适合和上面提示词一起交给 AI 的事实：

  • 你通常先创建 AgentOSSDK(baseUrl: ...)
  • registerBundle(...) 会完成应用注册并建立后续调用上下文
  • connectionEvents.listen(...) 可以观察连接状态
  • subscribe(...) 用于建立 AppKit 的 SSE 订阅
  • modelkit.listModels() 用于查询全部可用模型
  • modelkit.listModelsByTask(ModelTask.chat) 用于筛选 chat 模型
  • modelkit.chat.create(...) 可以做最小消息往返验证
  • agentos_sdk 是能力层 SDK，chatkit_dart 是聊天 UI 层

第 3 步：什么时候该接 ChatKit ​

agentos_sdk 负责：

  • 访问 AgentOS 网关
  • 注册 bundle 和保存 token
  • 调用 AgentKit、ModelKit、RagKit、CronKit、ToolKit
  • 管理 SSE 事件与请求模型

chatkit_dart 负责：

  • 提供现成聊天 UI
  • 管理 AgentSidebar、ChatKitRuntime、ChatKitSessionController
  • 帮你处理会话、消息流和配置表单的宿主集成

如果你已经有自己的页面和状态管理，只保留 SDK 就够了。
如果你要尽快落地一个 Flutter 聊天侧栏，直接接入 ChatKit 会更高效。

第 4 步：最小 ChatKit 集成 ​

下面是一个最小侧栏接入示意，整理自 chatkit_dart/README-zh_CN.md。

dart
import 'package:chatkit_dart/chatkit_dart.dart';

late final ChatKitRuntime runtime;

@override
void initState() {
  super.initState();
  runtime = ChatKitRuntime(config: config);
  unawaited(runtime.start());
}

@override
Widget build(BuildContext context) {
  return AgentSidebar(
    runtime: runtime,
    config: config,
    onConfigSaved: (next) async {
      runtime.updateConfig(next);
    },
    onLogout: () async {
      await runtime.stop();
    },
  );
}

常见注意点 ​

  • AgentOsConfig.isNotEmpty 需要 baseUrl 和 bundleId 都非空
  • 长连接场景建议把 receiveTimeout 设为 Duration.zero
  • 如果宿主已经自己渲染用户气泡，注意 emitLocalUserEcho 的重复消息问题
  • ChatKit 适合做聊天 UI，不代替底层 SDK 能力

人工验收清单 ​

  • 是否真的执行了 registerBundle(...)
  • 是否从 listModels() 获取模型，而不是随便写了一个模型名
  • 是否区分了 agentos_sdk 与 chatkit_dart 的职责边界
  • 如果接入 ChatKit，是否仍然保留了宿主应用自己的配置保存和登出逻辑
  • 是否先跑通 SDK 最小链路，再叠加 Flutter 聊天 UI

下一步去哪里 ​

建议阅读 ​