Dart Quickstart

This guide is based on agentos-sdk-dart and chatkit_dart, and helps you get AgentOS working quickly in a Dart or Flutter app.

If you are coding with Claude, Codex, Cursor, or ChatGPT, this page can also act as an execution brief for the AI.

Recommended path

• If you only need the capability layer, start with agentos-sdk-dart
• If you need a chat UI, add chatkit_dart on top of the SDK

What you will do

• Initialize the Dart SDK
• Connect to an AgentOS gateway
• Register an app bundle
• List available models and send one message
• Understand when ChatKit becomes the right next step

Recommended prompts

Minimal Dart integration

Implement a minimal AgentOS integration in a Dart project and give me runnable code, not just an explanation.

Goals:
- Use agentos_sdk to connect to the AgentOS gateway
- Call registerBundle to register the app
- Call modelkit.listModelsByTask(ModelTask.chat) to discover available chat models
- Send one minimal chat request and print the result

AgentOS facts you must follow:
- Use http://127.0.0.1:8888 as the example gateway address
- Initialize AgentOSSDK first, then registerBundle, then listModels, then send the chat request
- model should come from listModels(), not a made-up id
- If the docs already show subscribe or event handling, stay close to that structure

Return:
1. pubspec dependencies
2. Complete example code
3. Run command
4. What success should look like

Flutter + ChatKit integration

Help me integrate AgentOS into a Flutter app and keep the responsibilities of agentos_sdk and chatkit_dart clearly separated.

Requirements:
- agentos_sdk handles gateway access, bundle registration, and capability-layer calls
- chatkit_dart handles chat UI, runtime, and session controller concerns
- Do not treat ChatKit as a replacement for the underlying SDK
- If my app already has its own pages and state management, preserve that structure and only add AgentSidebar where chat UI is needed

Return:
1. Dependency setup
2. Minimal runtime initialization
3. AgentSidebar mounting example
4. Host integration details I should watch for

Prerequisites

• Dart SDK installed
• Flutter stable installed if you need Flutter UI
• A local or remote AgentOS gateway that your app can reach

Step 1: Add dependencies

If you only need the capability layer:

dependencies:
  agentos_sdk: ^0.1.0

Then run:

dart pub get

If you also need a Flutter chat UI, add:

dependencies:
  chatkit_dart: ^0.1.0

Then run:

flutter pub get

Step 2: Use the SDK to validate the minimal call flow

The following example is adapted from agentos-sdk-dart/example/agentos_sdk_dart_example.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}');
  }
}

Minimal fact checklist

These are the most useful facts to send along with the prompts above:

• You usually start with AgentOSSDK(baseUrl: ...)
• registerBundle(...) completes app registration and establishes the later call context
• connectionEvents.listen(...) can be used to observe connection state
• subscribe(...) opens the AppKit SSE stream
• modelkit.listModels() is how you discover all available models
• modelkit.listModelsByTask(ModelTask.chat) filters chat models
• modelkit.chat.create(...) is enough to validate the minimal request-response path
• agentos_sdk is the capability-layer SDK and chatkit_dart is the chat UI layer

Step 3: When should you add ChatKit?

agentos_sdk is responsible for:

• accessing the AgentOS gateway
• registering bundles and managing the token context
• calling AgentKit, ModelKit, RagKit, CronKit, and ToolKit
• handling SSE events and request models

chatkit_dart is responsible for:

• providing a ready-made chat UI
• managing AgentSidebar, ChatKitRuntime, and ChatKitSessionController
• helping with host integration for sessions, message flow, and config forms

If your app already has its own pages and state management, the SDK alone may be enough.
If you want a Flutter chat sidebar quickly, ChatKit is usually the faster path.

Step 4: Minimal ChatKit integration

This minimal sidebar example is adapted from chatkit_dart/README.md.

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();
    },
  );
}

Common things to watch for

• AgentOsConfig.isNotEmpty requires both baseUrl and bundleId
• For long-lived connections, receiveTimeout is often best set to Duration.zero
• If the host app already renders local user bubbles, watch for duplicate echoes from emitLocalUserEcho
• ChatKit is a chat UI layer and should not be treated as a replacement for the underlying SDK

Manual verification checklist

• Did the code actually call registerBundle(...)?
• Did it fetch the model from listModels() instead of hardcoding an arbitrary model name?
• Did it keep the responsibilities of agentos_sdk and chatkit_dart separate?
• If ChatKit was added, did it preserve the host app's own config-save and logout flow?
• Did it validate the minimal SDK path before layering Flutter chat UI on top?

Where to go next

• If you want to keep delegating work to AI, start with AI-Assisted Integration
• Read Use ChatKit in Dart
• See Dart Minimal App
• If you want the work-in-progress reference pages, read /en/draft/references/chatkit-dart/overview

Suggested reading

• AI-Assisted Integration
• Choose Your Stack
• Use ChatKit in Dart