AgentOS SDK for Dart #

A lightweight Dart SDK for the AgentOS API, supporting Root, AgentKit, AppKit, AuthKit, CronKit, DiscoveryKit, HarnessKit, RagKit, ModelKit (chat / embedding / asr / tts / decision, app models), ToolKit, and TransferKit endpoints. Use the unified AgentOSSDK to avoid managing tokens manually.

Features #

Root API: version check
AgentKit API: agent CRUD, session init, chat stream/simple, history, stop/clear, callbacks)
AppKit API: bundle registration and SSE subscription
HarnessKit API: runtime engine, threads, runs, commands, and resumable SSE events
AuthKit API: deliver third-party login requests to local AgentOS Desktop
CronKit API: cron task CRUD, run history, and scheduler control
DiscoveryKit API: nearby device discovery, peer streaming, registration
RagKit API: RAG base, document, sync, and query endpoints
ModelKit API: task-oriented model listing, OpenAI-compatible chat / embedding / asr / tts clients under /modelkit/*, typed-question decision inference, and external app-model registration
ToolKit API: tool listing, tool definition loading, and tool lifecycle event subscription
TransferKit API: device-to-device file transfer, progress streaming, receive policy, and transfer history

Getting Started #

Add the dependency to your pubspec.yaml:

dependencies:
  agentos_sdk: ^0.10.0

Then run:

dart pub get

Use a single public import:

import 'package:agentos_sdk/agentos_sdk.dart';

Usage #

import 'package:agentos_sdk/agentos_sdk.dart';

Future<void> main() async {
  final sdk = AgentOSSDK();

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

  final registration = await sdk.agentos.registerBundle(
    bundleId: 'com.demo.app',
    appGroupId: 'com.demo.group',
    opentoolServers: const <OpenToolServerDeclaration>[
      OpenToolServerDeclaration(
        ref: 'websearch',
        name: 'opentool-server-websearch',
      ),
    ],
  );
  print('App token: ${registration.token}');

  await sdk.agentos.subscribe(_DemoEventHandler());
  await Future<void>.delayed(const Duration(seconds: 1));
}

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

  @override
  Future<void> onAppEvent(AppEvent event) async {
    final success = event.openToolProvisionSuccess;
    if (success != null) {
      print('OpenTool ${success.ref} is ready: ${success.id}');
      return;
    }
    final failure = event.openToolProvisionFailure;
    if (failure != null) {
      print('OpenTool ${failure.ref} failed: ${failure.error.message}');
    }
  }

  @override
  Future<void> onDone() async {
    print('SSE subscription ended');
  }

  @override
  Future<void> onError(Exception error) async {
    print('Subscribe error: $error');
  }
}

Configure Gateway Address #

import 'package:agentos_sdk/agentos_sdk.dart';

final sdk = AgentOSSDK(baseUrl: 'http://localhost:8888');

Configure Long-Running Stream Timeouts #

import 'package:agentos_sdk/agentos_sdk.dart';

final sdk = AgentOSSDK(
  baseUrl: 'http://localhost:8888',
  connectTimeout: const Duration(seconds: 20),
  receiveTimeout: Duration.zero, // keep long SSE streams alive
);

Use ModelKit Chat #

agentos_sdk re-exports package:dart_openai_sdk/dart_openai_sdk.dart, so you can use OpenAI chat request/response types directly.

import 'package:agentos_sdk/agentos_sdk.dart';

final sdk = AgentOSSDK(baseUrl: 'http://localhost:8888');

final models = await sdk.modelkit.listModels();
print(models.map((model) => '${model.alias} (${model.task.name})').toList());

// Or filter by task:
final chatModels = await sdk.modelkit.listModelsByTask(ModelTask.chat);

final completion = await sdk.modelkit.chat.create(
  model: 'qwen3-1.7b',
  messages: <OpenAIChatCompletionChoiceMessageModel>[
    OpenAIChatCompletionChoiceMessageModel(
      role: OpenAIChatMessageRole.user,
      content: <OpenAIChatCompletionChoiceMessageContentItemModel>[
        OpenAIChatCompletionChoiceMessageContentItemModel.text('Hello.'),
      ],
    ),
  ],
);

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

sdk.modelkit returns ModelInfo, classified by task + capabilities.

Use ModelKit Decision #

Decision models (ModelTask.decision, served by llama.cpp /v1/systemone) do not generate text. They score the options of typed questions about a given state. POST /modelkit/decision needs no app token.

final decisionModels = await sdk.modelkit.listModelsByTask(ModelTask.decision);

final response = await sdk.modelkit.decision.create(
  model: decisionModels.first.name, // optional, the gateway picks a default
  state: <String, dynamic>{'text': 'My order is late and I am furious!'},
  questions: <String, DecisionQuestion>{
    // Pick one option (option -> description).
    'route': DecisionQuestion.choice(
      instructions: 'Which team should handle this?',
      options: const <String, String>{
        'billing': 'Payment and invoices',
        'support': 'Product or delivery problems',
      },
    ),
    // Ordinal scale with 2-10 level descriptions.
    'urgency': DecisionQuestion.score(
      instructions: 'How urgent is this?',
      levels: const <String>['low', 'medium', 'high'],
    ),
    // Yes/no judgement.
    'angry': DecisionQuestion.noul(instructions: 'Is the user angry?'),
  },
  // images: ['data:image/png;base64,...'], // for models with image input
);

final route = response.answers['route']!;
print('${route.choice} (confidence: ${route.confidence})');
print('urgency: ${response.answers['urgency']!.score}');
print('angry: ${response.answers['angry']!.noul}');
print('tokens: ${response.usage?.inputTokens} / ${response.usage?.outputTokens}');

DecisionAnswer exposes choice, score, noul, confidence, probabilities and legend; probabilities / legend are passed through as returned by the server, and raw holds the complete answer object.

Register an App Model #

Apps can register their own models into the gateway. Registered models show up in listModels() / listModelsByTask() with isAppModel == true and the owning appBundleId.

await sdk.agentos.registerBundle(bundleId: 'com.example.app');

// Register (or replace) a model. Only `id` and `name` are required.
final result = await sdk.modelkit.registerAppModel(
  request: const AppModelRegistration(
    id: 'my-router',
    name: 'my-router',
    task: ModelTask.decision,
    baseUrl: 'http://127.0.0.1:9000',
    apiKey: 'upstream-secret', // stored by the server, never returned
  ),
);
print(result.updated); // true when an existing model of this app was replaced

// Partial update: unset fields stay unchanged.
await sdk.modelkit.updateAppModel(
  modelId: 'my-router',
  request: const AppModelUpdate(description: 'Routes support tickets'),
);

// Enable/disable without deleting.
await sdk.modelkit.toggleAppModel(modelId: 'my-router');

// List every app-registered model (public, no token needed).
final appModels = await sdk.modelkit.listAppModels();
print(appModels.map((m) => '${m.id} by ${m.appBundleId} disabled=${m.isDisabled}'));

await sdk.modelkit.unregisterAppModel(modelId: 'my-router');

Write calls attach the app token automatically and refresh it once on 401. They throw a DioException carrying the server status: 401 invalid token, 403 not the owning app or appBundleId mismatch, 404 unknown id, 409 the id belongs to another app, 400 invalid body or unknown task.

Decision models are normalized by the server: input text (+ optional image), output decisions, and stream / tool_call / reasoning all false.

API Reference #

AgentOSSDK #

Constructor:

AgentOSSDK({
  String? baseUrl,
  Duration? connectTimeout,
  Duration? receiveTimeout,
})

Use baseUrl, connectTimeout, and receiveTimeout for public configuration.

Property	Type	Description
`agentos`	`AgentOSModule`	Root/AppKit endpoints with internal token handling.
`agentkit`	`AgentKitModule`	AgentKit endpoints with internal token handling.
`authkit`	`AuthKitModule`	Delivers third-party login authorization to local Desktop.
`cronkit`	`CronKitModule`	CronKit task management endpoints with internal token handling.
`discoverykit`	`DiscoveryKitModule`	DiscoveryKit nearby device discovery endpoints.
`harnesskit`	`HarnessKitModule`	Harness runtime, thread, run, command, and event endpoints.
`ragkit`	`RagKitModule`	RagKit knowledge-base endpoints with internal token handling.
`modelkit`	`ModelKitModule`	ModelKit task-oriented model listing, chat / embedding / asr / tts / decision clients, and app-model registration.
`toolkit`	`ToolKitModule`	ToolKit discovery endpoints and tool lifecycle event subscription.
`transferkit`	`TransferKitModule`	TransferKit file transfer endpoints.
`dispose()`	`Future<void>`	Releases SDK resources and cancels active AppKit subscription.

AgentOSModule (`sdk.agentos`) #

Method	Parameters	Description
`getVersion()`	none	Fetches AgentOS service version.
`getRoot()`	none	Fetches AgentOS gateway metadata.
`getReady()`	none	Fetches AgentOS readiness status.
`registerBundle({required String bundleId, String? appGroupId, List<OpenToolServerDeclaration> opentoolServers = const []})`	`bundleId`, `appGroupId`, `opentoolServers`	Registers an app bundle, declares native OpenTool server dependencies, stores the bearer token internally, and returns registration statuses.
`subscribe(AgentOSEventHandler handler)`	`handler`	Subscribes to AppKit SSE events using a handler implementation.

CronKitModule (`sdk.cronkit`) #

Method	Parameters	Description
`getTask({required String cronId})`	`cronId`	Fetches a cron task by ID.
`listTasks({bool? enabled, int? offset, int? limit})`	`enabled`, `offset`, `limit`	Lists visible cron tasks for the current app group.
`createTask({required CronTaskCreateRequest request})`	`request`	Creates a cron task.
`updateTask({required CronTaskUpdateRequest request})`	`request`	Updates a cron task owned by the current app.
`deleteTask({required String cronId})`	`cronId`	Deletes a cron task owned by the current app.
`enableTask({required String cronId})`	`cronId`	Explicitly enables a cron task and returns its updated status.
`disableTask({required String cronId})`	`cronId`	Explicitly disables a cron task and returns its updated status.
`runTaskNow({required String cronId, DateTime? scheduledAt})`	`cronId`, `scheduledAt`	Triggers an immediate run for a cron task.
`getRun({required String runId})`	`runId`	Fetches one cron run record by ID.
`listRuns({String? cronId, DateTime? after, DateTime? before, int? offset, int? limit})`	`cronId`, `after`, `before`, `offset`, `limit`	Lists cron task runs visible to the current app group.
`listRunMessages({required String runId, int? offset, int? limit})`	`runId`, `offset`, `limit`	Lists persisted `AgentMessage` records for a cron run.
`deleteRun({required String runId})`	`runId`	Deletes one cron run and its persisted messages.

Cron tasks can reuse an existing LiteAgent session and evaluate their schedule in an IANA timezone:

await sdk.cronkit.createTask(
  request: CronTaskCreateRequest(
    name: 'Daily summary',
    schedule: '0 9 * * *',
    sessionId: 'existing-liteagent-session',
    timezone: 'Asia/Shanghai',
    concurrency: CronTaskConcurrency.skipIfRunning,
    spec: CronSpec(
      systemPrompt: 'You are a scheduled agent.',
      content: <Content>[
        Content(type: ContentType.text, message: 'Generate the daily summary.'),
      ],
      modelId: 'gpt-4o',
    ),
  ),
);

sessionId is optional. Scheduled runs reuse it when provided; otherwise the kernel initializes a LiteAgent session when the task runs.
timezone accepts an IANA timezone such as Asia/Shanghai. Cron evaluation is timezone-aware, while lastRunAt, nextRunAt, and run timestamps are serialized in UTC.
CronTaskConcurrency supports allow, skipIfRunning, and replace.
modelId is an optional request field used by CronKit to resolve the backing model.
modelName is an optional response field returned in CronTask.spec after resolution.

AuthKitModule (`sdk.authkit`) #

Delivers third-party login authorization requests to the local AgentOS Desktop. The SDK does not implement OAuth endpoints and does not return authorization codes, ID tokens, or access tokens — those stay between your backend and AgentOS Server.

Typical flow:

Your backend creates an authorization request on AgentOS Server and returns launchUri to the client.
The client calls sdk.authkit.openAuthorization(launchUri: ...) to present the consent UI on Desktop.
Poll your backend's login transaction status for the final result.

Method	Parameters	Description
`openAuthorization({required String launchUri, bool waitForDecision = false, Duration? decisionTimeout})`	`launchUri`, `waitForDecision`, `decisionTimeout`	Delivers `launchUri` (unchanged from your server) to local Desktop. Returns `AuthorizationPresentationResult`.
`isAuthorizationReady()`	none	Returns whether Desktop is running and ready to show the consent UI.

openAuthorization returns AuthorizationPresentationResult:

Status	Meaning
`opened`	Consent UI shown; user has not decided yet (default when `waitForDecision` is false).
`submitted`	User approved and Desktop submitted the decision to AgentOS Server. Does not mean login is complete.
`denied`	User declined.
`failed`	Local delivery failed; see `errorCode`.

Common errorCode values:

Error code	Meaning
`desktop_not_running`	Desktop gateway is unreachable.
`desktop_not_ready`	Desktop is starting; UI not ready yet.
`desktop_not_logged_in`	Desktop is not signed in to AgentOS.
`invalid_launch_uri`	`launchUri` must be passed through from your server as-is.
`authorization_expired`	Request expired; start login again.
`authorization_not_found`	Request missing or already handled.

Example:

await sdk.agentos.registerBundle(bundleId: 'com.demo.app');

if (!await sdk.authkit.isAuthorizationReady()) {
  // Prompt user to install / launch / sign in to AgentOS Desktop
}

final start = await myBackend.startAgentOSLogin(); // returns launchUri from AgentOS Server
final result = await sdk.authkit.openAuthorization(
  launchUri: start.launchUri,
);
if (result.isFailure) {
  print('AuthKit error: ${result.errorCode}');
} else {
  // Poll your backend for the final login transaction status
}

For end-to-end local testing, see example/authkit_test_harness/.

DiscoveryKitModule (`sdk.discoverykit`) #

Method	Parameters	Description
`getPeers()`	none	Returns a snapshot of nearby peer devices.
`streamPeers()`	none	Returns an SSE stream of peer device events (joined/left/updated).
`getSelf()`	none	Returns self device information and registration status.
`register({DiscoveryRegisterRequest? request})`	`request`	Registers the current app for nearby discovery.
`unregister()`	none	Unregisters the current app from nearby discovery.

TransferKitModule (`sdk.transferkit`) #

Method	Parameters	Description
`send({required TransferSendRequest request})`	`request`	Initiates a file transfer to a target device.
`listTransfers()`	none	Lists active transfer sessions.
`getStatus({required String transferId})`	`transferId`	Gets the status of a specific transfer.
`streamProgress({required String transferId})`	`transferId`	Returns an SSE stream of transfer progress updates.
`cancel({required String transferId})`	`transferId`	Cancels an active transfer.
`respond({required String transferId, required TransferRespondRequest request})`	`transferId`, `request`	Accepts or rejects an incoming transfer.
`receiveStream()`	none	Returns an SSE stream of incoming transfer events.
`setPolicy({required SetPolicyRequest request})`	`request`	Sets the file receive policy (autoAccept / requireConfirm).
`getPolicy()`	none	Gets the current file receive policy.
`getHistory({String? deviceId, String? userId})`	`deviceId`, `userId`	Lists transfer history records.
`deleteHistory({required String recordId, String? deviceId, String? userId})`	`recordId`, `deviceId`, `userId`	Deletes a specific transfer history record.
`clearHistory({String? deviceId, String? userId})`	`deviceId`, `userId`	Clears all transfer history records.

HarnessKitModule (`sdk.harnesskit`) #

After agentos.registerBundle, use HarnessKit through the authenticated Gateway. Apps that need their own managed runtime must declare harnessKit in their installable process App manifest.

Method	Parameters	Description
`health()`	none	Checks whether the Harness runtime is reachable.
`getRuntime()` / `switchEngine({required String engine})`	`engine`	Reads or changes the active runtime engine.
`listThreads()` / `getThread({required String threadId})`	`threadId`	Lists saved conversations or reads one snapshot.
`renameThread({required String threadId, required String title})` / `deleteThread({required String threadId})`	`threadId`, `title`	Renames or deletes a saved conversation.
`startRun({required String threadId, required HarnessKitRunRequest request})`	`threadId`, `request`	Starts a run and returns its `runId`.
`submitCommand({required String threadId, required HarnessKitCommand command})`	`threadId`, `command`	Submits a command and returns its receipt, including rejected receipts returned with HTTP 400.
`events({required String threadId, HarnessKitEventsOptions options})`	`threadId`, `afterSequence`, `runId`	Opens an SSE stream that can resume from a sequence number. Cancel the stream subscription to close it.
`getRunResult({required String runId})` / `getOperationalSnapshot()`	`runId`	Reads a completed run result or runtime status snapshot.

The request and response models are exported from the package entry point. See example/agentos_sdk_dart_example.dart for a minimal runtime and thread listing example.

AgentKitModule (`sdk.agentkit`) #

Method	Parameters	Description
`initSession({Capability? capability})`	`capability`	Initializes a SessionAgent session, optionally with recursively nested inline agents.
`initSimple({required SimpleCapability simpleCapability})`	`simpleCapability`	Initializes a SimpleAgent session.
`chat(Session session, UserTask userTask, AgentMessageHandler agentMessageHandler)`	`session`, `userTask`, `agentMessageHandler`	Starts a SessionAgent task and delivers SSE events to the handler callbacks.
`chatSimple({required String sessionId, required UserTask userTask})`	`sessionId`, `userTask`	Executes a SimpleAgent request and returns a one-time response.
`history({required String sessionId, int? page, int? pageSize})`	`sessionId`, `page`, `pageSize`	Retrieves typed message history. Supply positive, 1-based `page` and `pageSize` together for pagination, or omit both for the complete history.
`historySummary({required String sessionId, int page = 1, int pageSize = 30})`	`sessionId`, `page`, `pageSize`	Retrieves summary-first task history.
`historyProcess({required String sessionId, required String originalTaskId, int page = 1, int pageSize = 50})`	`sessionId`, `originalTaskId`, `page`, `pageSize`	Lazily retrieves process messages for one task turn.
`stop({required String sessionId, String? taskId})`	`sessionId`, `taskId`	Stops a session or task.
`clear({required String sessionId})`	`sessionId`	Clears session data.
`callback({required String sessionId, required ToolReturn toolReturn})`	`sessionId`, `toolReturn`	Sends tool callback results.
`streamCallback({required String sessionId, required EventToolReturn eventToolReturn})`	`sessionId`, `eventToolReturn`	Sends streaming tool callback results.

RagKitModule (`sdk.ragkit`) #

Method	Parameters	Description
`getBase({required String baseId})`	`baseId`	Fetches a RAG base by ID.
`listBases({int? offset, int? limit})`	`offset`, `limit`	Lists RAG bases visible to the current app group.
`createBase({required RagBaseCreateRequest request})`	`request`	Creates a RAG base.
`updateBase({required RagBaseUpdateRequest request})`	`request`	Updates a RAG base owned by the current app.
`deleteBase({required String baseId})`	`baseId`	Deletes a RAG base owned by the current app.
`getDocument({required String baseId, required String documentId})`	`baseId`, `documentId`	Fetches one RAG document.
`listDocuments({required String baseId, int? offset, int? limit})`	`baseId`, `offset`, `limit`	Lists documents inside a RAG base.
`upsertDocument({required RagUpsertDocumentRequest request})`	`request`	Creates or updates one markdown document.
`upsertDocuments({required RagUpsertDocumentsRequest request})`	`request`	Batch creates or updates markdown documents.
`deleteDocument({required String baseId, required String documentId})`	`baseId`, `documentId`	Deletes one RAG document.
`syncDocument({required String baseId, required String documentId})`	`baseId`, `documentId`	Triggers embeddings sync for one document.
`syncBase({required String baseId})`	`baseId`	Triggers embeddings sync for one base.
`retryFailed({String? baseId})`	`baseId`	Retries failed document sync jobs, optionally scoped to one base.
`query({required RagQueryRequest request})`	`request`	Runs a semantic query against one RAG base.

ModelKitModule (`sdk.modelkit`) #

Method/Property	Type	Description
`listModels()`	`Future<List<ModelInfo>>`	Fetches available models from `/modelkit/models`.
`listModelsByTask(ModelTask task)`	`Future<List<ModelInfo>>`	Returns models filtered by task (`chat` / `embedding` / `asr` / `tts` / `decision`).
`chat`	`ModelKitChatClient`	OpenAI-compatible chat client using `{baseUrl}/modelkit/chat`.
`embedding`	`ModelKitEmbeddingClient`	OpenAI-compatible embeddings client under `/modelkit/embedding`.
`asr`	`ModelKitAsrClient`	Speech-to-text client under `/modelkit/asr`.
`tts`	`ModelKitTtsClient`	Text-to-speech client under `/modelkit/tts`.
`decision`	`ModelKitDecisionClient`	`decision.create({model, state, questions, images, extra})` → `POST /modelkit/decision`, returns `DecisionResponse`.
`listAppModels()`	`Future<List<AppModel>>`	Lists app-registered models from `GET /modelkit/app-models` (public).
`registerAppModel({required AppModelRegistration request})`	`Future<AppModelWriteResult>`	Registers or replaces an app model (`POST /modelkit/app-models`, app token).
`updateAppModel({required String modelId, required AppModelUpdate request})`	`Future<AppModelWriteResult>`	Partially updates an owned app model (`PUT /modelkit/app-models/<id>`).
`unregisterAppModel({required String modelId})`	`Future<AppModelWriteResult>`	Removes an owned app model (`DELETE /modelkit/app-models/<id>`).
`toggleAppModel({required String modelId})`	`Future<AppModelWriteResult>`	Enables/disables an owned app model (`POST /modelkit/app-models/<id>/toggle`).

ModelInfo describes each model with task (ModelTask), inputModalities / outputModalities (Modality), and capabilities (ModelCapabilities: vision / toolCall / stream / reasoning). In particular, capabilities.reasoning is a bool. Convenience getters hasVision, supportsChatInference, supportsDecisionInference and isVisionLanguage are provided. App-registered models additionally report isAppModel and appBundleId.

ModelKitClient (ModelKitClient(apiClient: ...)) offers the same app-model methods with an explicit bearerToken: parameter instead of the automatic app token.

ToolKitModule (`sdk.toolkit`) #

Method	Parameters	Description
`listTool([String? all])`	`all`	Lists available tools from `/toolkit/list`.
`loadTool(String toolId)`	`toolId`	Loads an `OpenTool` definition from `/toolkit/{toolId}/load`.
`subscribeToolEvents({required String daemonApiKey, bool snapshot = true})`	`daemonApiKey`, `snapshot`	Subscribes to `/toolkit/events` and streams `ToolLifecycleEventDto` updates.

listTool / listTools return the daemon 0.5 ToolDto. Its optional server identity uses namespace, name, and version; when available, materializedArtifactDigest identifies the installed content and contentState reports whether that content is current. The SDK also re-exports the daemon 0.5 client API, including VersionDto.apiVersion and VersionDto.capabilities for capability negotiation, typed PullEvent streams, detailed ServerDeleteResultDto responses, and stable DaemonApiException errors.

AgentOSEventHandler #

Method	Parameters	Description
`onWelcome(Welcome welcome)`	`welcome`	Receives `welcome` events.
`onAppEvent(AppEvent event)`	`event`	Receives AppKit business events, including asynchronous OpenTool provisioning success and failure results.
`onDone()`	none	Called when the SSE stream ends.
`onError(Exception error)`	`error`	Called when the SSE stream errors.

Subscription Lifecycle #

import 'package:agentos_sdk/agentos_sdk.dart';

final sdk = AgentOSSDK(baseUrl: 'http://localhost:8888');

await sdk.agentos.registerBundle(bundleId: 'com.demo.app');
await sdk.agentos.subscribe(myHandler); // app start

// app stop/dispose
await sdk.dispose();

AgentKit Schema Notes #

UserTask supports passthrough fields:
- extraSystemPrompt
- llmConfig
LLMConfig supports:
- contextWindowSize
- supportsToolCall (read/write)
- supportsReasoning (read/write)
- read compatibility for supportsToolCalling and supportsDeepThinking
Capability supports:
- llmConfigList
- toolReturnPackMinLength

Capability also accepts these optional execution limits. The SDK forwards provided integer values unchanged, omits null values, and leaves validation and defaults to the server.

Field	Meaning	Server default
`maxLlmRequests`	Maximum LLM requests for one tool-based task.	`64`
`maxToolRounds`	Maximum tool-call rounds for one task.	`16`
`maxToolCalls`	Maximum total tool calls for one task.	`64`
`maxConsecutiveIdenticalToolRounds`	Maximum consecutive rounds with identical tool calls.	`3`
`maxTaskDurationSeconds`	Maximum duration of one tool-based task, in seconds.	`300`

const plannerSkillMarkdown = '''
---
name: planner
description: Break work into clear steps.
---
Plan the task before execution.
''';

final capability = Capability(
  systemPrompt: 'You are an assistant',
  skills: <String>[plannerSkillMarkdown],
  maxLlmRequests: 32,
  maxToolRounds: 8,
  maxToolCalls: 20,
  maxConsecutiveIdenticalToolRounds: 2,
  maxTaskDurationSeconds: 120,
);

await sdk.agentkit.initSession(
  capability: Capability(
    systemPrompt: 'Coordinate the team',
    subAgentList: <Agent>[
      Agent(name: 'limited-agent', capability: capability),
    ],
  ),
);

AgentMessage.completions supports limits:
- maxTokens
- contextWindowSize
AgentMessage.originalTaskId identifies the root task and falls back to taskId when reading older responses.
TaskStatus.taskId identifies the task associated with a status update.

AgentMessageHandler (Tool Callback) #

Implement onFunctionCall(...) for non-stream tool calls. The SDK sends the returned value via /agentkit/callback.
Implement onStreamFunctionCall(...) for stream tool calls. The SDK sends each event via /agentkit/streamCallback.

class MyHandler extends AgentMessageHandler {
  @override
  Future<void> onStreamFunctionCall(
    String sessionId,
    FunctionCall functionCall,
    void Function(EventToolReturn) onToolReturn,
  ) async {
    onToolReturn(
      EventToolReturn(
        event: EventType.DATA,
        toolReturn: ToolReturn(
          id: functionCall.id,
          result: <String, dynamic>{'partial': '...'},
        ),
      ),
    );
    onToolReturn(
      EventToolReturn(
        event: EventType.DONE,
        toolReturn: ToolReturn(
          id: functionCall.id,
          result: <String, dynamic>{'ok': true},
        ),
      ),
    );
  }

  @override
  Future<void> onMessage(String sessionId, AgentMessage agentMessage) async {}
  @override
  Future<void> onChunk(String sessionId, AgentMessageChunk chunk) async {}
  @override
  Future<void> onDone() async {}
  @override
  Future<void> onError(Exception error) async {}
}

chat(...) keeps the SSE subscription inside the SDK and exposes events only through AgentMessageHandler. Event callbacks are processed serially, so onDone() runs only after the final event callback completes.

await sdk.agentkit.chat(
  Session(sessionId: sessionId),
  userTask,
  myHandler,
);

// Stops the remote task and closes active local chat streams for the session.
await sdk.agentkit.stop(sessionId: sessionId);

AgentOSSDK.dispose() also closes every active AgentKit chat stream. The public API does not expose the underlying Dart stream subscription.

CallbackOpenTool.timeout is an optional positive timeout in seconds. The gateway uses its compatibility default when the value is omitted or invalid.
callback(...) and streamCallback(...) may return status: ignored with reason: callback_expired or callback_completed for late results.

Token Handling #

agentos.registerBundle stores the bearer token internally.
agentkit/agentos requests use the stored token automatically.

Configuration #

Base URL is managed by the SDK and defaults to http://localhost:8888.

Notes #

Call agentos.registerBundle before using agentkit/agentos/authkit/discoverykit/transferkit/harnesskit APIs that require a token.
authkit.openAuthorization only delivers the consent UI locally. Treat your backend's login transaction status as the source of truth for login success.
AgentOSSDK exposes module properties (agentos, agentkit, authkit, cronkit, discoverykit, harnesskit, ragkit, modelkit, toolkit, transferkit) for clearer separation of API areas.
AgentKit endpoints are exposed under /agentkit/*.
sdk.modelkit.chat targets /modelkit/chat/....
sdk.modelkit.decision targets /modelkit/decision; app-model management targets /modelkit/app-models. Only app-model writes need agentos.registerBundle first.
sdk.toolkit.subscribeToolEvents(...) requires a daemon API key and streams tool lifecycle events via SSE.
External integrations should use only package:agentos_sdk/agentos_sdk.dart and avoid importing package:agentos_sdk/src/....

Development #

dart format .
dart analyze
dart test

Regenerate JSON models when DTOs change:

dart run build_runner build --delete-conflicting-outputs

agentos_sdk 0.9.0
agentos_sdk: ^0.9.0 copied to clipboard

Metadata

AgentOS SDK for Dart #

Features #

Getting Started #

Usage #

Configure Gateway Address #

Configure Long-Running Stream Timeouts #

Use ModelKit Chat #

Use ModelKit Decision #

Register an App Model #

API Reference #

AgentOSSDK #

AgentOSModule (`sdk.agentos`) #

CronKitModule (`sdk.cronkit`) #

AuthKitModule (`sdk.authkit`) #

DiscoveryKitModule (`sdk.discoverykit`) #

TransferKitModule (`sdk.transferkit`) #

HarnessKitModule (`sdk.harnesskit`) #

AgentKitModule (`sdk.agentkit`) #

RagKitModule (`sdk.ragkit`) #

ModelKitModule (`sdk.modelkit`) #

ToolKitModule (`sdk.toolkit`) #

AgentOSEventHandler #

Subscription Lifecycle #

AgentKit Schema Notes #

AgentMessageHandler (Tool Callback) #

Token Handling #

Configuration #

Notes #

Development #

← Metadata

Documentation

Publisher

Weekly Downloads

Metadata

License

Dependencies

More

agentos_sdk 0.9.0 agentos_sdk: ^0.9.0 copied to clipboard

Metadata

AgentOS SDK for Dart #

Features #

Getting Started #

Usage #

Configure Gateway Address #

Configure Long-Running Stream Timeouts #

Use ModelKit Chat #

Use ModelKit Decision #

Register an App Model #

API Reference #

AgentOSSDK #

AgentOSModule (sdk.agentos) #

CronKitModule (sdk.cronkit) #

AuthKitModule (sdk.authkit) #

DiscoveryKitModule (sdk.discoverykit) #

TransferKitModule (sdk.transferkit) #

HarnessKitModule (sdk.harnesskit) #

AgentKitModule (sdk.agentkit) #

RagKitModule (sdk.ragkit) #

ModelKitModule (sdk.modelkit) #

ToolKitModule (sdk.toolkit) #

AgentOSEventHandler #

Subscription Lifecycle #

AgentKit Schema Notes #

AgentMessageHandler (Tool Callback) #

Token Handling #

Configuration #

Notes #

Development #

← Metadata

Documentation

Publisher

Weekly Downloads

Metadata

License

Dependencies

More

agentos_sdk 0.9.0
agentos_sdk: ^0.9.0 copied to clipboard

AgentOSModule (`sdk.agentos`) #

CronKitModule (`sdk.cronkit`) #

AuthKitModule (`sdk.authkit`) #

DiscoveryKitModule (`sdk.discoverykit`) #

TransferKitModule (`sdk.transferkit`) #

HarnessKitModule (`sdk.harnesskit`) #

AgentKitModule (`sdk.agentkit`) #

RagKitModule (`sdk.ragkit`) #

ModelKitModule (`sdk.modelkit`) #

ToolKitModule (`sdk.toolkit`) #