TypeScript SDK

@profy-ai/sdk 是袋袋平台的官方 TypeScript SDK，使用原生 fetch API，同时支持 Node.js 和浏览器环境。

安装

npm install @profy-ai/sdk

要求 Node.js 18+（需要原生 fetch 支持）。

快速开始

import { Profy } from "@profy-ai/sdk";

const client = new Profy({ apiKey: "sk-pro-your-key" });

// 调用 专家
const result = await client.agents.run("my-expert", "你好");
console.log(result.text);

客户端配置

import { Profy } from "@profy-ai/sdk";

const client = new Profy({
  apiKey: "sk-pro-your-key",
  baseUrl: "https://api.profy.cn",  // 默认值
  timeout: 300_000,                  // 默认值（毫秒）
});

参数	类型	默认值	说明
`apiKey`	`string`	（必填）	API Key 或 OAuth Access Token
`baseUrl`	`string`	`https://api.profy.cn`	API 基础 URL
`timeout`	`number`	`300000`	请求超时（毫秒）

资源命名空间

命名空间	方法	对应端点
`client.agents`	`run()`, `runStream()`	`POST /v1/agents/run`
`client.chat.completions`	`create()`	`POST /v1/chat/completions`
`client.models`	`list()`	`GET /v1/models`
`client.events`	`report()`	`POST /v1/events`

Agents

`agents.run()` — 调用专家

const result = await client.agents.run(
  "my-expert",
  "帮我分析这段代码的性能问题",
  {
    sessionId: "abc123",    // 可选：延续会话
    model: "deepseek-v3",   // 可选：指定模型
  }
);

console.log(result.text);        // 完整回复
console.log(result.model);       // 使用的模型
console.log(result.sessionId);   // 会话 ID
console.log(result.toolCalls);   // 工具调用列表
console.log(result.usage);       // Token 用量
console.log(result.elapsedMs);   // 耗时（毫秒）

AgentRunResult 类型定义：

interface AgentRunResult {
  text: string;
  model?: string;
  sessionId?: string;
  toolCalls: ToolCall[];
  usage: TokenUsage;
  error?: string;
  partial: boolean;
  elapsedMs: number;
}

interface ToolCall {
  name: string;
  status: "started" | "completed";
}

interface TokenUsage {
  promptTokens: number;
  completionTokens: number;
  totalTokens: number;
}

`agents.runStream()` — 流式调用专家

for await (const chunk of client.agents.runStream("my-expert", "你好")) {
  switch (chunk.type) {
    case "run.in_progress":
      console.log(`模型: ${chunk.raw.model_name}`);
      console.log(`会话: ${chunk.raw.session_id}`);
      break;
    case "output.text.delta":
      process.stdout.write(chunk.delta ?? "");
      break;
    case "tool_call.created":
      console.log(`\n🔧 调用工具: ${chunk.raw.tool_name}`);
      break;
    case "tool_call.completed":
      console.log(`✅ 工具完成`);
      break;
    case "run.completed":
      console.log("\n--- 完成 ---");
      break;
    case "run.failed":
      console.error(`❌ 错误: ${chunk.raw.message}`);
      break;
  }
}

AgentRunChunk 类型定义：

interface AgentRunChunk {
  type: string;
  delta?: string;
  raw: Record<string, unknown>;
}

Chat Completions

`chat.completions.create()` — 对话补全

非流式（返回 ChatResponse）：

const resp = await client.chat.completions.create({
  model: "deepseek-v3",
  messages: [
    { role: "system", content: "你是一个有帮助的助手" },
    { role: "user", content: "你好" },
  ],
  temperature: 0.7,
  maxTokens: 1000,
});

console.log(resp.text);
console.log(`Token: ${resp.usage.totalTokens}`);

流式（返回 AsyncGenerator<ChatChunk>）：

const stream = await client.chat.completions.create({
  model: "deepseek-v3",
  messages: [{ role: "user", content: "讲一个故事" }],
  stream: true,
});

for await (const chunk of stream) {
  if (chunk.delta) {
    process.stdout.write(chunk.delta);
  }
}

SDK 使用 TypeScript 函数重载确保类型安全：

// stream: false → Promise<ChatResponse>
const response: ChatResponse = await client.chat.completions.create({
  model: "deepseek-v3",
  messages: [...],
  stream: false,  // 或省略
});

// stream: true → Promise<AsyncGenerator<ChatChunk>>
const stream: AsyncGenerator<ChatChunk> = await client.chat.completions.create({
  model: "deepseek-v3",
  messages: [...],
  stream: true,
});

Models

`models.list()` — 获取模型列表

const models = await client.models.list();

for (const m of models) {
  console.log(`${m.id}: ${m.name}`);
  const caps = m.capabilities as Record<string, unknown>;
  console.log(`  工具: ${caps?.supportsTools ? "✅" : "❌"}`);
  console.log(`  视觉: ${caps?.supportsVision ? "✅" : "❌"}`);
  console.log(`  最大输入: ${caps?.maxInputTokens ?? "未知"}`);
}

Events

`events.report()` — 上报自定义事件

const result = await client.events.report("image_generation", {
  idempotencyKey: "order_123_gen_1",
  metadata: { style: "watercolor" },
});

console.log(`扣费: ${result.charged}`);
console.log(`剩余: ${result.balance_remaining}`);

Events API 仅支持 OAuth Token。使用 API Key 调用会返回 401 错误。

错误处理

SDK 在 API 返回非 2xx 状态码时抛出 ProfyApiError：

import { Profy, ProfyApiError } from "@profy-ai/sdk";

const client = new Profy({ apiKey: "sk-pro-your-key" });

try {
  await client.agents.run("non-existent", "你好");
} catch (e) {
  if (e instanceof ProfyApiError) {
    console.log(`HTTP 状态码: ${e.statusCode}`);
    console.log(`错误信息:`, e.body);

    switch (e.statusCode) {
      case 401:
        console.log("API Key 无效");
        break;
      case 403:
        console.log("访问被拒绝");
        break;
      case 404:
        console.log("专家 不存在");
        break;
      case 429:
        console.log("速率限制");
        break;
    }
  }
  throw e;
}

超时处理

const client = new Profy({
  apiKey: "sk-pro-your-key",
  timeout: 60_000,  // 60 秒
});

try {
  const result = await client.agents.run("my-expert", "复杂任务");
} catch (e) {
  if (e instanceof DOMException && e.name === "AbortError") {
    console.log("请求超时");
  }
}

agents.run() 在超时时会尽量返回已收到的部分结果（result.partial = true）。

浏览器环境

SDK 使用原生 fetch，可在浏览器中使用：

import { Profy } from "@profy-ai/sdk";

const client = new Profy({
  apiKey: oauthAccessToken,
  // 浏览器中建议使用 OAuth Token，不要暴露 API Key
});

const result = await client.agents.run("my-expert", userMessage);
document.getElementById("output")!.textContent = result.text;

不要在浏览器前端代码中使用 API Key。浏览器端应使用 OAuth Token。API Key 仅应在 Node.js 服务端使用。

完整示例：Express API 代理

import express from "express";
import { Profy } from "@profy-ai/sdk";

const app = express();
const client = new Profy({ apiKey: process.env.PROFY_API_KEY! });

app.use(express.json());

app.post("/api/chat", async (req, res) => {
  const { message, sessionId, expert } = req.body;

  try {
    res.setHeader("Content-Type", "text/event-stream");
    res.setHeader("Cache-Control", "no-cache");

    for await (const chunk of client.agents.runStream(
      expert ?? "my-expert",
      message,
      { sessionId }
    )) {
      res.write(`data: ${JSON.stringify(chunk)}\n\n`);
    }
    res.write("data: [DONE]\n\n");
    res.end();
  } catch (e) {
    res.status(500).json({ error: String(e) });
  }
});

app.listen(3000, () => console.log("Server running on :3000"));

完整示例：多轮对话

import { Profy } from "@profy-ai/sdk";
import * as readline from "readline";

const client = new Profy({ apiKey: process.env.PROFY_API_KEY! });
const rl = readline.createInterface({ input: process.stdin, output: process.stdout });

async function main() {
  let sessionId: string | undefined;
  console.log("开始对话（输入 quit 退出）\n");

  const ask = () => new Promise<string>((resolve) => rl.question("你: ", resolve));

  while (true) {
    const input = await ask();
    if (input.toLowerCase() === "quit") break;

    process.stdout.write("AI: ");
    for await (const chunk of client.agents.runStream("my-expert", input, { sessionId })) {
      if (chunk.type === "run.in_progress") {
        sessionId = chunk.raw.session_id as string;
      } else if (chunk.type === "output.text.delta") {
        process.stdout.write(chunk.delta ?? "");
      }
    }
    console.log();
  }

  rl.close();
}

main();

概览

Platform API

认证与密钥

集成

SDK

Cookbook

参考

TypeScript SDK

安装

快速开始

客户端配置

资源命名空间

Agents

`agents.run()` — 调用专家

`agents.runStream()` — 流式调用专家

Chat Completions

`chat.completions.create()` — 对话补全

Models

`models.list()` — 获取模型列表

Events

`events.report()` — 上报自定义事件

错误处理

超时处理

浏览器环境

完整示例：Express API 代理

完整示例：多轮对话

下一步

Python SDK

API 参考

​安装

​快速开始

​客户端配置

​资源命名空间

​Agents

​agents.run() — 调用专家

​agents.runStream() — 流式调用专家

​Chat Completions

​chat.completions.create() — 对话补全

​Models

​models.list() — 获取模型列表

​Events

​events.report() — 上报自定义事件

​错误处理

​超时处理

​浏览器环境

​完整示例：Express API 代理

​完整示例：多轮对话

​下一步

Python SDK

API 参考

安装

快速开始

客户端配置

资源命名空间

Agents

`agents.run()` — 调用专家

`agents.runStream()` — 流式调用专家

Chat Completions

`chat.completions.create()` — 对话补全

Models

`models.list()` — 获取模型列表

Events

`events.report()` — 上报自定义事件

错误处理

超时处理

浏览器环境

完整示例：Express API 代理

完整示例：多轮对话

下一步