TypeScript Quickstart

This guide is based on agentos-sdk-ts and agentos-api, and its goal is to get one AgentOS call working in a Node.js environment with the shortest possible path.

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

What you will do

• Install and initialize the SDK
• Connect to an AgentOS gateway
• Register an app bundle
• List available models and send one message
• Understand where to continue if you need AgentKit, CronKit, or ToolKit later

Recommended prompts

Minimal TypeScript integration

Implement a minimal AgentOS integration in a Node.js / TypeScript project and give me runnable code, not just an explanation.

Goals:
- Use agentos-sdk-ts 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
- When using the AgentOS SDK, configure only the gateway `baseUrl`
- If you use the official OpenAI SDK directly, chat `baseURL` is `${root.baseUrl}/modelkit/chat/v1`
- The bearer token comes from registerBundle
- model must come from listModelsByTask(ModelTask.chat), not a made-up model id
- If the docs already show subscribe and an event handler, stay close to that structure

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

Adapting existing OpenAI code

Adapt my existing OpenAI SDK integration so it runs against AgentOS while preserving as much of my business logic as possible.

You must use these mappings:
- baseURL = `${baseUrl from the AgentOS root endpoint}/modelkit/chat/v1`
- apiKey = bearer token returned by registerBundle
- model = `model.id` or a valid alias from `sdk.modelkit.listModelsByTask(ModelTask.chat)`

Do not rewrite my business layer and do not invent a new AgentOS initialization flow. Limit changes to the integration layer and tell me which environment variables and initialization steps need to change.

Prerequisites

• A working Node.js / TypeScript environment
• A local or remote AgentOS gateway that your app can reach
• A known gateway address such as http://127.0.0.1:8888

Step 1: Prepare the AgentOS gateway

If you already have a local gateway running, you can skip this step.

If you need a quick local gateway, use agentos-api README:

git clone https://github.com/agentos-org/agentos-api.git
cd agentos-api
./tool/run_server.sh

By default, the gateway listens on http://127.0.0.1:8888.

You can also verify that the service is available:

curl http://127.0.0.1:8888/version

Step 2: Install the SDK

npm install agentos-sdk-ts

If you are using TypeScript, it is usually best to import from the unified package entry:

import { AgentOSEventHandler, AgentOSSDK, ModelTask } from 'agentos-sdk-ts';

Step 3: Write a minimal runnable example

The snippet below is adapted from agentos-sdk-ts/example/agentos_sdk_example.mjs and keeps the most important integration steps intact.

import { AgentOSEventHandler, AgentOSSDK } from 'agentos-sdk-ts';

const sdk = new AgentOSSDK({
  baseUrl: 'http://127.0.0.1:8888'
});

class DemoEventHandler extends AgentOSEventHandler {
  async onWelcome(welcome) {
    console.log('Welcome bundleId:', welcome.bundleId);
  }

  async onCallApp(call) {
    console.log('CallApp event:', call.contentList);
  }
}

async function main() {
  const version = await sdk.agentos.getVersion();
  console.log('AgentOS version:', version.version);

  const registration = await sdk.agentos.registerBundle({
    bundleId: 'com.example.agentos.docs',
    appGroupId: 'com.example.agentos'
  });
  console.log('Registered token for bundle:', registration.bundleId);

  sdk.agentos.connectionEvents.subscribe((event) => {
    console.log('Subscribe status:', event.status);
  });

  await sdk.agentos.subscribe(new DemoEventHandler());

  const models = await sdk.modelkit.listModelsByTask(ModelTask.chat);
  console.log('Available chat models:', models.map((model) => model.alias));

  const completion = await sdk.modelkit.chat.create({
    model: models[0]?.id ?? 'qwen3-1.7b',
    messages: [
      {
        role: 'user',
        content: 'Hello from AgentOS docs.'
      }
    ]
  });

  console.log(completion.choices?.[0]?.message?.content);
}

main().catch(console.error);

Minimal fact checklist

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

• You usually start with new AgentOSSDK({ baseUrl })
• registerBundle(...) returns the token used for later authenticated calls
• 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
• If you use the official OpenAI SDK directly with ModelKit, baseURL, apiKey, and model all have specific sources and should not be guessed

Step 4: Understand what the example is doing

new AgentOSSDK({ baseUrl })

Creates the SDK client. In most cases, the gateway address is the only required input.

sdk.agentos.registerBundle(...)

Registers the current app with AppKit. The SDK stores the returned bearer token and reuses it automatically when you call protected modules such as agentos, agentkit, cronkit, and toolkit.

sdk.agentos.subscribe(...)

Opens the AppKit SSE subscription so the app can receive events such as welcome and callApp. This matters whenever your app needs background notifications, tool callbacks, or host-app coordination.

sdk.modelkit.chat.create(...)

Calls the OpenAI-compatible chat interface exposed by the gateway. It is ideal for the lightest possible request-response check before you move on to AgentKit or more complex workflows.

Using the official OpenAI SDK directly with ModelKit

If your app already has its own complex and customized agent, you usually do not need agentkit first.
You can treat AgentOS directly as an OpenAI-compatible gateway.

Parameter mapping

OpenAI SDK field	AgentOS source
baseURL	${root.baseUrl}/modelkit/chat/v1
apiKey	bearer token returned by sdk.agentos.registerBundle(...)
model	model.id from sdk.modelkit.listModelsByTask(ModelTask.chat)

Example

import OpenAI from 'openai';
import { AgentOSSDK, ModelTask } from 'agentos-sdk-ts';

async function main() {
  const sdk = new AgentOSSDK({
    baseUrl: 'http://127.0.0.1:8888'
  });

  const root = await sdk.agentos.getRoot();
  const registration = await sdk.agentos.registerBundle({
    bundleId: 'com.example.agentos.openai',
    appGroupId: 'com.example.agentos'
  });
  const models = await sdk.modelkit.listModelsByTask(ModelTask.chat);

  const client = new OpenAI({
    baseURL: `${root.baseUrl}/modelkit/chat/v1`,
    apiKey: registration.token
  });

  const completion = await client.chat.completions.create({
    model: models[0].id,
    messages: [
      {
        role: 'user',
        content: 'Hello from the OpenAI-compatible AgentOS gateway.'
      }
    ]
  });

  console.log(completion.choices[0]?.message?.content);
}

main().catch(console.error);

The same mapping also applies to

• TTS
• ASR
• Embeddings

In other words, apiKey always comes from the registration token, and model comes from the ModelKit task-specific model list. Choose baseURL by task: chat uses /modelkit/chat/v1, embeddings uses /modelkit/embedding/v1, and so on.

Common configuration

Custom gateway address

const sdk = new AgentOSSDK({ baseUrl: 'http://localhost:8888' });

Adjusting long-lived connection timeouts

const sdk = new AgentOSSDK({
  baseUrl: 'http://localhost:8888',
  connectTimeout: 20_000,
  receiveTimeout: 0
});

receiveTimeout: 0 is useful when you want to keep SSE connections open for a long time.

Where to go next

• If you want to keep delegating work to AI, start with AI-Assisted Integration
• If you want to continue at the HTTP and routing layer, read agentos-api README
• If you want a complete example only, read TypeScript Minimal App
• If you want the work-in-progress SDK reference draft, read /en/draft/references/sdk-ts/overview

Suggested reading

• AI-Assisted Integration
• Architecture
• TypeScript Minimal App

Manual verification checklist

• Did the code actually call registerBundle(...)?
• Did it fetch the model from listModels() instead of hardcoding an arbitrary value?
• If it uses the OpenAI SDK, did it switch chat baseURL to ${root.baseUrl}/modelkit/chat/v1?
• Did it use the bearer token as apiKey?
• Did it preserve the minimal runnable path instead of introducing too many abstractions too early?