Overview

AgentOS is a runtime, API, and SDK stack for building intelligent applications.

Many developers no longer read a full doc set and implement everything manually. Instead, they first clarify the scenario and constraints, then hand the task to an AI coding tool.
Because of that, these docs now provide two kinds of material:

• decision-making guidance for humans
• prompts, fact checklists, and minimal examples for AI coding tools

For most app developers, three questions matter first:

1. How do I connect to AgentOS capabilities?
2. How do I organize sessions, messages, tools, and state?
3. Which SDK, UI layer, or API surface should I choose?

Who this is for

• Developers integrating chat or agent capabilities into Web, Node.js, Dart, or Flutter apps
• Client developers calling AgentOS through SDKs or HTTP APIs
• Advanced developers who need runtime and extension details

Recommended reading mode

Traditional mode

Read quickstarts, guides, and examples yourself, then implement the integration manually.

AI-assisted mode

1. Decide whether your target is the model gateway, agent orchestration, or RAG services
2. Copy the page's recommended prompt and minimal fact checklist into your AI coding tool
3. Let the AI make the change inside your real codebase
4. Use the manual verification checklist to confirm the critical AgentOS facts

If you already code with Claude, Codex, Cursor, or ChatGPT, the second mode is usually the better default.
Start from AI-Assisted Integration.

Common integration scenarios

1. Your app already has its own complex agent and only needs model access

Use modelkit first, not agentkit.
The AgentOS gateway exposes OpenAI-compatible interfaces, so you can often use the official OpenAI SDK directly:

• baseURL: if using the official OpenAI SDK directly, chat uses ${baseUrl}/modelkit/chat/v1, where baseUrl comes from the AgentOS root endpoint
• apiKey: the bearer token returned by registerBundle or POST /appkit/register
• model: a model.id from sdk.modelkit.listModelsByTask(ModelTask.chat) or a task=chat item from GET /modelkit/models

Best for:

• managing prompts, memory, state machines, and tool orchestration yourself
• keeping your own customized agent runtime
• reusing AgentOS only as the model gateway and unified auth layer

2. Your app provides tools but you do not want to assemble the agent yourself

Use agentkit.
AgentKit handles sessions, message flow, tool calls, and callback orchestration.

3. Your app needs TTS

Use the OpenAI SDK TTS interface against AgentOS /modelkit/tts/*.

apiKey still comes from the registration token, and the model should come from the ModelKit task=tts list. If you use the official OpenAI SDK directly, point baseURL to /modelkit/tts/v1.

4. Your app needs ASR

Use the OpenAI SDK ASR interface against AgentOS /modelkit/asr/*.

apiKey still comes from the registration token, and the model should come from the ModelKit task=asr list. If you use the official OpenAI SDK directly, point baseURL to /modelkit/asr/v1.

5. Your app needs embeddings

Use the OpenAI SDK embeddings interface against AgentOS /modelkit/embedding/*.

apiKey still comes from the registration token, and the model should come from the ModelKit task=embedding list. If you use the official OpenAI SDK directly, point baseURL to /modelkit/embedding/v1.

6. Your app needs ready-made RAG services rather than building on embeddings directly

Use ragkit.
It is better suited for apps that want query, document management, synchronization, and knowledge-base workflows directly instead of building embeddings, ChromaDB, or docs management logic from scratch.

Suggested reading order

1. AI-Assisted Integration
2. Choose Your Stack
3. TypeScript Quickstart or Dart Quickstart
4. Architecture
5. The relevant examples/ section