Choose Your Stack

If you plan to hand the integration work directly to an AI coding tool, the goal of this page is not to make you learn every detail first. The goal is to decide which implementation path the AI should follow.

Quick answer first

Your goal	Recommended entry point	Why
Call HTTP endpoints directly and manage auth and requests yourself	agentos-api	Closest to the raw gateway capabilities; good for servers, gateways, or heavily customized clients
Your app already has its own complex agent and only needs the model layer	modelkit + OpenAI SDK	Reuse the OpenAI-compatible interface directly without introducing AgentKit
Your app provides tools but you do not want to assemble the agent yourself	agentkit	AgentKit handles sessions, message flow, tool calls, and callbacks
Your app needs TTS / ASR / Embeddings	modelkit + OpenAI SDK	Same integration style as LLM access, which makes it easier to unify
Your app needs ready-made RAG services instead of building the vector layer yourself	ragkit	Use query, docs management, synchronization, and knowledge-base interfaces directly
You want quick access from Web or Node.js	agentos-sdk-ts	Wraps registration, auth, module access, and streaming interfaces
You want quick access from Dart or Flutter	agentos-sdk-dart	Wraps AgentOS gateway access and adapts it to Dart types
You want a Flutter chat UI quickly	chatkit_dart	Provides AgentSidebar, runtime, and session controllers directly

Stack-selection prompt for AI coding tools

Send this to your AI first so it chooses the right path before writing code:

Please do not start by writing code. First decide whether my scenario should use modelkit, agentkit, or ragkit, then implement the integration based on that decision.

My context:
- Project type: [Node.js / TypeScript / Dart / Flutter]
- Current state: [greenfield / existing OpenAI integration / existing custom agent / existing knowledge base]
- Goal: [model access only / tools plus agent orchestration / RAG / TTS / ASR / embeddings]

You must follow these AgentOS facts:
- If I already have my own complex agent, usually prefer modelkit and do not introduce agentkit first
- If I have tools but do not want to manage sessions, tool orchestration, and message flow myself, usually prefer agentkit
- If I need ready-made document retrieval, management, and sync, usually prefer ragkit
- If you use the official OpenAI SDK directly, chat baseURL is `${baseUrl}/modelkit/chat/v1`, where `baseUrl` comes from the AgentOS root endpoint
- apiKey comes from the bearer token returned by registerBundle or POST /appkit/register
- model comes from `sdk.modelkit.listModelsByTask(ModelTask.chat)`, or a `task=chat` `model.id` from `GET /modelkit/models`
- Do not invent SDK methods or response fields

Please return:
1. Your recommended module and why
2. Why the other paths are less suitable
3. How you will implement the integration in the project

Scenario-based choices

Scenario 1: you already have your own agent and only need the model gateway

Use modelkit first and call it through the official OpenAI SDK.

Inside AgentOS, these values map like this:

OpenAI SDK field	AgentOS source
baseURL	${baseUrl from root GET /}/modelkit/chat/v1
apiKey	bearer token from registerBundle or POST /appkit/register
model	model.id from sdk.modelkit.listModelsByTask(ModelTask.chat) or a task=chat item from GET /modelkit/models

The same integration style works for:

• Chat Completions
• TTS
• ASR
• Embeddings

In other words, if your app already owns complex prompts, memory, tool routing, and state management, AgentOS behaves more like a unified AI gateway.

Suggested task description for AI:

This project already has its own custom agent. Do not introduce agentkit and do not rewrite my agent orchestration. Only switch the model access layer to the AgentOS modelkit/OpenAI-compatible gateway while preserving my existing prompts, memory, tool routing, and state management.

Recommended because:

• you do not need platform-managed agent orchestration
• your existing runtime already owns the business logic
• the migration cost stays focused on the model access layer

Scenario 2: you have tools but do not want to assemble the agent yourself

Use agentkit first.

Best for:

• exposing your own tool capabilities
• avoiding agent session management, tool-call chains, callback flow, and message state
• delegating the orchestration layer to AgentKit

Suggested task description for AI:

This project provides its own tools, but I do not want to maintain agent sessions, message flow, and tool-call chains myself. Please design the integration around agentkit instead of giving me only a basic modelkit chat example.

Recommended because:

• the value you need is not just model access
• you want “model + tools + session” orchestration together
• you want to reduce the amount of state-machine code you own

Scenario 3: you need TTS / ASR / Embeddings

The first choice is still modelkit, using the OpenAI-compatible SDK interfaces.

Recommended because:

• the integration style matches chat access
• the gateway URL, token, and model selection rules stay the same
• it is easy to reuse in an existing OpenAI SDK client

Suggested task description for AI:

Please adapt my existing OpenAI SDK client so TTS / ASR / embeddings run against AgentOS instead. Reuse the same registration, auth, and ModelKit model lookup flow; choose task-specific baseURLs such as `/modelkit/tts/v1`, `/modelkit/asr/v1`, or `/modelkit/embedding/v1`.

Scenario 4: you need ready-made RAG services

Use ragkit first instead of building upward from embeddings and vector infrastructure yourself.

Best for:

• knowledge-base query workflows
• document ingestion and management
• synchronization and long-term maintenance of knowledge content
• avoiding hand-built embeddings, vector stores, and docs lifecycle plumbing

Suggested task description for AI:

I need ready-made RAG services, not just embeddings. Please design the integration around ragkit document management, synchronization, and query workflows instead of returning only an embeddings example.

Recommended because:

• it gives you a usable knowledge service instead of only vectors
• it avoids rebuilding the lower-level retrieval stack
• it matches applications that want direct query and docs workflows

Which repository or module should you use

agentos-api

Best when you want direct control over server endpoints, auth, and request/response models.

It also fits cases where you want to access these capability surfaces directly:

• modelkit/chat/*
• modelkit/tts/*
• modelkit/asr/*
• modelkit/embedding/*
• agentkit/*
• ragkit/*

agentos-sdk-ts

Best for Web or Node.js developers integrating AgentOS through TypeScript.

If you do not want to manage these pieces yourself:

• bundle registration
• token persistence
• module wrappers
• SSE subscriptions

then the SDK is usually easier than working with raw HTTP.

agentos-sdk-dart

Best for Dart / Flutter developers integrating AgentOS through a Dart SDK.

chatkit_dart

Best when you want to integrate a ready-made chat UI and a higher-level interaction layer into a Dart / Flutter app.

Typical paths

Web / Node.js

1. Start or connect to the AgentOS gateway
2. If you already own the agent runtime, go straight to modelkit through the OpenAI-compatible interface
3. If you want the platform to manage tool + agent orchestration, switch to agentkit
4. If you need lower-level protocol control later, add agentos-api

Dart / Flutter

1. Start with agentos-sdk-dart to validate the basic connection and message path
2. Add chatkit_dart if you need a ready-made chat UI
3. If you already own the UI layer, keep only the SDK

AI capability access

• Need chat completions: prefer modelkit
• Need tts: prefer modelkit
• Need asr: prefer modelkit
• Need embeddings: prefer modelkit
• Need ready-made RAG: prefer ragkit

Platform or infrastructure work

If your work is mainly about:

• gateway deployment
• API integration debugging
• scheduled tasks, RAG, or tool-system integration

then start with agentos-api.

Suggested reading order

• If you want to prepare the correct context for AI first, read AI-Assisted Integration
• If you want the quickest path to working code, read the quickstart for your language first
• If you are building a Dart app, start with agentos-sdk-dart and add chatkit_dart only when you need UI

Manual verification checklist

• Did the AI decide the module first instead of defaulting to agentkit immediately?
• Did it clearly distinguish “I already have my own agent” from “I have tools but want AgentKit to orchestrate them”?
• In RAG scenarios, did it include document management and retrieval rather than only embeddings?
• Did it explain the correct sources of baseURL, apiKey, and model?