TypeScript 快速开始

本文档基于 agentos-sdk-ts 和 agentos-api，目标是在 Node.js 环境中用最短路径跑通一次 AgentOS 调用。

如果你正在用 Claude、Codex、Cursor 或 ChatGPT 编码，这一页也可以直接当成“给 AI 的执行说明书”来用。

你将完成什么

安装并初始化 SDK
连接到 AgentOS 网关
注册一个 app bundle
查询可用模型并发送一条消息
理解后续该去哪里继续看 AgentKit、CronKit 和 ToolKit

前置条件

具备 Node.js / TypeScript 开发环境
本地或远程可访问的 AgentOS 网关
已知网关地址，例如 http://127.0.0.1:8888

第 1 步：准备 AgentOS 网关

如果你本地已有网关，可以直接跳过。

如果需要快速启动一个本地网关，可参考 agentos-api：

bash

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

默认情况下，网关会监听在 http://127.0.0.1:8888。

你也可以先确认服务是否可用：

bash

curl http://127.0.0.1:8888/version

第 2 步：安装 SDK

bash

npm install agentos-sdk-ts

如果你使用 TypeScript，建议直接从统一入口导入：

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

第 3 步：写一个最小可运行示例

下面这段示例整理自 agentos-sdk-ts/example/agentos_sdk_example.mjs，保留了最关键的接入流程。

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);

最小事实清单

这是最适合和上面提示词一起交给 AI 的事实：

你通常先创建 new AgentOSSDK({ baseUrl })
registerBundle(...) 返回的 token 会作为后续调用凭证
subscribe(...) 用于建立 AppKit 的 SSE 订阅
modelkit.listModels() 用于查询全部可用模型
modelkit.listModelsByTask(ModelTask.chat) 用于筛选 chat 模型
modelkit.chat.create(...) 可以做最小消息往返验证
如果要用 OpenAI 官方 SDK 直接接 ModelKit，baseURL、apiKey、model 都有明确来源，不要猜

第 4 步：理解示例里发生了什么

`new AgentOSSDK({ baseUrl })`

创建 SDK 客户端。大多数情况下，你只需要提供网关地址。

`sdk.agentos.registerBundle(...)`

向 AppKit 注册当前应用。SDK 会保存返回的 Bearer token，后续调用 agentos、agentkit、cronkit、toolkit 等模块时会自动带上它。

`sdk.agentos.subscribe(...)`

建立 AppKit 的 SSE 订阅，用来接收 welcome、callApp 等事件。对于需要后台通知、工具回调或宿主应用协作的场景，这一步很关键。

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

调用网关暴露的 OpenAI 兼容 chat 接口。它适合做最轻量的消息往返验证，也适合在真正接入 AgentKit 之前先检查模型和网关是否可用。

使用 OpenAI 官方 SDK 直接对接 ModelKit

如果你的 App 自己已经有复杂且定制化的 agent，通常不需要先接 agentkit。
你可以直接把 AgentOS 当作一个 OpenAI 兼容网关来使用。

参数如何映射

OpenAI SDK 参数	AgentOS 中的来源
`baseURL`	`${root.baseUrl}/modelkit/chat/v1`
`apiKey`	`sdk.agentos.registerBundle(...)` 返回的 Bearer token
`model`	`sdk.modelkit.listModelsByTask(ModelTask.chat)` 返回列表中的 `model.id`

示例

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);

同样的规则也适用于

TTS
ASR
Embeddings

也就是说，只要你使用的是 AgentOS 网关暴露的 OpenAI 兼容能力，apiKey 都来自注册返回的 token，model 都来自 sdk.modelkit 的任务模型列表；baseURL 需要按任务选择对应前缀，例如 chat 用 /modelkit/chat/v1，embeddings 用 /modelkit/embedding/v1。

常用配置

自定义网关地址

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

调整长连接超时

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

receiveTimeout: 0 适合长时间保持 SSE 连接。

下一步去哪里

如果你打算继续把任务交给 AI：先看 AI 辅助接入
如果你想继续走 HTTP 和路由层：看 agentos-api README-zh_CN
如果你只想要完整示例：看 TypeScript 最小示例
如果你想看仍在整理中的 SDK 参考草稿：看 /draft/references/sdk-ts/overview

建议阅读

人工验收清单

是否真的执行了 registerBundle(...)
是否从 listModels() 获取模型，而不是随便写了一个模型名
如果使用 OpenAI SDK，是否把 chat 的 baseURL 改成了 ${root.baseUrl}/modelkit/chat/v1
是否把 Bearer token 当成 apiKey 使用
是否保留了最小可运行路径，而不是一上来引入过多抽象

TypeScript 快速开始

你将完成什么

推荐提示词

新项目最小接入

已有 OpenAI 代码改造

前置条件

第 1 步：准备 AgentOS 网关

第 2 步：安装 SDK

第 3 步：写一个最小可运行示例

最小事实清单

第 4 步：理解示例里发生了什么

`new AgentOSSDK({ baseUrl })`

`sdk.agentos.registerBundle(...)`

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

使用 OpenAI 官方 SDK 直接对接 ModelKit

参数如何映射

示例

同样的规则也适用于

常用配置

自定义网关地址

调整长连接超时

下一步去哪里

建议阅读

人工验收清单

TypeScript 快速开始 ​

你将完成什么 ​

推荐提示词 ​

新项目最小接入 ​

已有 OpenAI 代码改造 ​

前置条件 ​

第 1 步：准备 AgentOS 网关 ​

第 2 步：安装 SDK ​

第 3 步：写一个最小可运行示例 ​

最小事实清单 ​

第 4 步：理解示例里发生了什么 ​

new AgentOSSDK({ baseUrl }) ​

sdk.agentos.registerBundle(...) ​

sdk.agentos.subscribe(...) ​

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

使用 OpenAI 官方 SDK 直接对接 ModelKit ​

参数如何映射 ​

示例 ​

同样的规则也适用于 ​

常用配置 ​

自定义网关地址 ​

调整长连接超时 ​

下一步去哪里 ​

建议阅读 ​

人工验收清单 ​

TypeScript 快速开始

你将完成什么

推荐提示词

新项目最小接入

已有 OpenAI 代码改造

前置条件

第 1 步：准备 AgentOS 网关

第 2 步：安装 SDK

第 3 步：写一个最小可运行示例

最小事实清单

第 4 步：理解示例里发生了什么

`new AgentOSSDK({ baseUrl })`

`sdk.agentos.registerBundle(...)`

`sdk.agentos.subscribe(...)`

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

使用 OpenAI 官方 SDK 直接对接 ModelKit

参数如何映射

示例

同样的规则也适用于

常用配置

自定义网关地址

调整长连接超时

下一步去哪里

建议阅读

人工验收清单