跳转到主要内容
本指南带你从零到一个能聊天的运行中智能体，通过 BeeOS 公开 OpenAPI 完成。同样的流程可对本地 http://localhost:8095 和生产 https://openapi.beeos.ai。

​
准备

  • 一个 beeos.ai 账户。
  • 一个用户 API Key（oag_…），到 Settings → API Keys 创建。 这是长期 bearer 凭证 —— 见认证了解作用域和轮换。

​
1. 安装 SDK

npm install @beeos-ai/sdk
已发布的 @beeos-ai/sdk 由 OpenAPI Generator（typescript-fetch） 从 OpenAPI 契约自动生成。它导出一个 Configuration 值和每个 OpenAPI tag 一个 class —— DeployApi、InstancesApi、AgentsApi、TasksApi、 ConversationsApi、FilesApi。没有 BeeOS 顶层 client。

​
2. 配置 client

import {
  Configuration,
  DeployApi,
  InstancesApi,
  AgentsApi,
} from "@beeos-ai/sdk";

const config = new Configuration({
  basePath: "https://openapi.beeos.ai",
  headers: { Authorization: `Bearer ${process.env.BEEOS_API_KEY}` },
});

const deploy = new DeployApi(config);
const instances = new InstancesApi(config);
const agents = new AgentsApi(config);

​
3. 查看部署目录

const providers = await deploy.listProviders();
console.log(providers.data?.map(p => `${p.meta?.id} — ${p.meta?.name}`));

const regions = await deploy.listDeployRegions({ providerId: "default" });
const models = await deploy.listDeployModels({ agentFramework: "beeos-claw" });

​
4. 部署一个智能体实例

const created = await instances.deployInstance({
  deployInstanceRequest: {
    name: "my-first-agent",
    agentFramework: "beeos-claw",
    modelPrimary: "gpt-4o",
  },
});
const instanceId = created.data!.id;
console.log(`实例 ${instanceId} — 状态: ${created.data!.status}`);
部署需要几秒钟。轮询 GET /instances/{id} 直到 status === "running"，或在 dashboard 上看。

​
5. 拿到智能体 ID

一个部署的实例托管一个或多个智能体。调用要用的是智能体 ID（实例可 以被替换而不破坏你的集成；智能体身份是稳定的）。 
const list = await agents.listAgents({ instanceId, limit: 20 });
const agentId = list.data![0].id;
console.log(`调用智能体 ${agentId}`);

​
6. 调用智能体

阻塞调用在智能体完成回复后返回一个 JSON 载荷。长 prompt 见 流式。 
const reply = await agents.invokeAgent({
  agentId,
  invokeAgentRequest: {
    message: "你好 —— 你能做什么？",
  },
});
console.log("回复:", reply.data?.text);
console.log("Channel:", reply.data?.context_id);

​
流式变体

同一个端点设 Accept: text/event-stream 即可接收 agent_reply_delta 分块，最后由一个 agent_reply 关闭。SDK 不抽象 SSE —— 回落到 fetch / http.Client。 
curl -N -X POST "$BASE/api/v1/agents/$AGENT_ID/invoke" \
  -H "Authorization: Bearer $BEEOS_API_KEY" \
  -H "Accept: text/event-stream" \
  -H "Content-Type: application/json" \
  -d '{"message": "讲个短故事。"}'

​
6.5. invoke 调用会出现在哪里？

每次 invoke 都会创建一个短生命周期的 protocol=openapi 任务 通道， 而不是会话。可以通过下面的命令查看： 
curl -s "$BASE/api/v1/agents/$AGENT_ID/tasks?state=all" \
  -H "Authorization: Bearer $BEEOS_API_KEY" | jq
GET /agents/{agentId}/conversations 只返回你通过 POST /conversations 显式创建的长生命周期对话通道。invoke 之后立即调用该接口返回空列表 属于预期行为 —— 见 调用智能体 指南，了解 何时该用 conversation 何时该用 invoke。

​
7. 清理

curl -s -X DELETE "$BASE/api/v1/instances/$INSTANCE_ID" \
  -H "Authorization: Bearer $BEEOS_API_KEY" | jq

​
下一步去哪

选择协议

在 OpenAPI（本指南）、A2A、MCP 之间做出选择。

调用智能体

幂等键、附件、任务、会话、错误处理。

Webhook

HMAC 签名的终态回调 + 重试 + 审计日志。

A2A 协议

a2a.beeos.ai 上的 JSON-RPC + 智能体卡片。