Skip to content

TypeScript 快速开始 ​

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

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

你将完成什么 ​

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

推荐提示词 ​

新项目最小接入 ​

text
请在一个 Node.js / TypeScript 项目里完成 AgentOS 最小接入,并直接给出可运行代码,而不是只解释步骤。

目标:
- 使用 agentos-sdk-ts 连接 AgentOS 网关
- 调用 registerBundle 完成应用注册
- 调用 modelkit.listModelsByTask(ModelTask.chat) 获取可用 chat 模型
- 发送一次最小 chat 请求并打印结果

必须遵守的 AgentOS 事实:
- 网关地址示例是 http://127.0.0.1:8888
- 使用 AgentOS SDK 时只需要配置网关 `baseUrl`
- 如果直接使用 OpenAI 官方 SDK,chat 的 `baseURL` 是 `${root.baseUrl}/modelkit/chat/v1`
- Bearer token 来自 registerBundle 返回值
- model 应来自 listModelsByTask(ModelTask.chat) 返回结果,不要臆造模型 id
- 如果示例里已有 subscribe 和事件处理器,请优先贴近文档示例结构

请输出:
1. 依赖安装命令
2. 完整示例代码
3. 运行命令
4. 我应该看到的成功结果

已有 OpenAI 代码改造 ​

text
请把我现有使用 OpenAI 官方 SDK 的代码改成 AgentOS 兼容接入,尽量保留现有业务结构。

你必须使用这些映射关系:
- baseURL = `${AgentOS 根接口返回的 baseUrl}/modelkit/chat/v1`
- apiKey = registerBundle 返回的 Bearer token
- model = `sdk.modelkit.listModelsByTask(ModelTask.chat)` 返回的 `model.id` 或可用 alias

请不要重写我的业务层,也不要臆造新的 AgentOS 初始化方式。只改动接入层,并告诉我哪些环境变量和初始化逻辑需要调整。

前置条件 ​

  • 具备 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,建议直接从统一入口导入:

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

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

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

ts
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
apiKeysdk.agentos.registerBundle(...) 返回的 Bearer token
modelsdk.modelkit.listModelsByTask(ModelTask.chat) 返回列表中的 model.id

示例 ​

ts
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。

常用配置 ​

自定义网关地址 ​

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

调整长连接超时 ​

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

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

下一步去哪里 ​

建议阅读 ​

人工验收清单 ​

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