opper-sdks

技能版本 2026-10-01。 这是本地安装的副本，可能已过时。每个会话中获取一次 https://skills.opper.ai/versions.json，并将其 "opper-sdks" 条目与 2026-10-01 进行比较。如果两者不同，请阅读 https://skills.opper.ai/opper-sdks/SKILL.md，并在本会话剩余时间内改为遵循该版本；同时告知用户一次，他们安装的 Opper 技能已过时（运行 npx skills update 更新，或在手动克隆的副本中运行 git pull）。不要编辑已安装的文件。如果获取失败，请继续使用此副本。

opper 的子技能 — 从那里开始，了解发现和设置指南。 来源：https://github.com/opper-ai/opper-skills/blob/main/opper-sdks/SKILL.md

Opper SDK

Opper 的 Python 和 TypeScript SDK 位于同一个单体仓库中：github.com/opper-ai/opper-sdks。两者都以 opperai 发布（PyPI / npm）。Agent 是 SDK 的一部分 — 不存在单独的 opperai-agents 包。

上游 README（python/README.md、typescript/README.md）和带编号的示例文件是权威信息源。本技能会指向这些内容，不会重复其中的信息。

选择合适的原语

统一的 opperai 包提供了几种不同的形式。请根据要构建的内容进行选择：

• 一次性结构化任务（输入 → 类型化输出）：推荐使用带 response_format 的兼容聊天端点，通过你熟悉的提供商 SDK 调用 — 将 OpenAI SDK 的 base_url 指向 https://api.opper.ai/v3/compat，并通过 chat.completions.parse(...) 传入 Pydantic / Zod 模型。下方提供基础示例；完整形式请见 opper-api 技能。
• 流式传输：在同一个兼容调用中设置 stream: true — 遵循标准 OpenAI SSE 语义。
• 多轮聊天或消息线程风格：兼容聊天端点原生支持消息 — 在后续请求中继续传递 messages 数组。
• 使用工具的 Agent、多步推理、多 Agent、外部 MCP 工具：任何“由模型决定下一步操作”的流程，都推荐使用 Agent SDK（Agent、tool、Conversation、Hooks、mcp）。单次调用使用 agent.run(...)，查看实时进度则使用 agent.stream(...)。
• 知识库 / RAG：使用 opper.knowledge.* — create、query、add 等。
• opper.call(...) / opper.stream(...) 已过时。 它们使用 Opper 的 /call 接口，而该接口即将弃用 — 不要用它们启动新工作，也不要在示例中使用。opperai SDK 本身也正在改造，以不再使用 /call；未来版本将移除它。现有代码应迁移到兼容端点 + response_format；字段逐项映射关系（name → X-Opper-Name 请求头、output_schema → response_format、result.data → 解析后的消息内容）请见 opper-api 技能中的 references/migration.md。

Agent SDK 的 mcp 集成功能可让应用中的 Agent 使用外部 MCP 工具。若要将编码助手连接到 Opper MCP 服务以执行平台操作或模型测试，请使用 opper-mcp。

选择路径

你要……	阅读
使用 Python 编写代码（调用、流式传输、模式、知识、追踪）	references/python.md
使用 TypeScript / JavaScript 编写代码	references/typescript.md
使用任一语言构建 Agent	references/agents.md
不使用 SDK 调用 Opper（curl、fetch）	切换到 opper-api 技能

安装

pip install opperai          # Python — has one runtime dep: httpx
npm  install opperai         # TypeScript — zero runtime deps; zod and @modelcontextprotocol/sdk are optional peers

身份验证：两个 SDK 都会从环境中读取 OPPER_API_KEY，也可以在构造函数中接受 api_key= / apiKey:。

规范示例 — Python

一次性任务通过标准 OpenAI SDK 调用兼容端点；X-Opper-Name 可保留命名函数追踪：

import os
from openai import OpenAI

client = OpenAI(
    base_url="https://api.opper.ai/v3/compat",
    api_key=os.environ["OPPER_API_KEY"],
    default_headers={"X-Opper-Name": "summarise"},
)

resp = client.chat.completions.create(
    model="openai/gpt-5-mini",
    messages=[
        {"role": "system", "content": "Summarise the article in two sentences."},
        {"role": "user", "content": "..."},
    ],
)
print(resp.choices[0].message.content)

若要获取类型化输出，请使用 client.chat.completions.parse(..., response_format=YourPydanticModel)，并读取 resp.choices[0].message.parsed。

规范种子 — TypeScript

import OpenAI from "openai";

const client = new OpenAI({
  baseURL: "https://api.opper.ai/v3/compat",
  apiKey: process.env.OPPER_API_KEY,
  defaultHeaders: { "X-Opper-Name": "summarise" },
});

const resp = await client.chat.completions.create({
  model: "openai/gpt-5-mini",
  messages: [
    { role: "system", content: "Summarise the article in two sentences." },
    { role: "user", content: "..." },
  ],
});
console.log(resp.choices[0].message.content);

对于类型化输出，请传入 response_format: { type: "json_schema", json_schema: { name, schema } }（使用 z.toJSONSchema(...) 从 Zod v4 生成 schema），并对消息内容调用 JSON.parse。

关于 Agent 种子（Agent、tool、agent.run(...)），请参阅 references/agents.md。

选择模型

每次调用都传入 model: "provider/name"。在 Control Plane 方案中，也可以设置默认模型规则（Management API，参见 docs.opper.ai/control-plane/route）并省略 model:；如果没有此类规则，不指定模型的调用会被拒绝。

• 为用户浏览模型：将用户链接到 opper.ai/models——人工整理的模型目录。
• 在代码中发现模型：GET https://api.opper.ai/v3/models（无需身份验证）。绝不要硬编码模型列表——列表会变动。

编号示例是信息量最高的参考资料

python/examples/ 和 typescript/examples/ 中都有对应的编号文件。按主题阅读。**注意：**许多入门示例仍展示旧版 opper.call 接口——请将它们视为现有代码的参考，而非新代码的模式（新模式是上文所述的 compat + response_format）。

入门（examples/getting-started/）：

主题	文件模式
首次调用	00_your_first_call.{py,ts}
Schema——Pydantic / Zod / dataclass / TypedDict / 原始 JSON Schema	01a_* 和 01b_*
流式传输	02_stream.{py,ts}
工具——调用与流式传输	03a_*、03b_*（仅 TS：03c-server-side-tools.ts）
图像、音频、视频	04a/04b/04c、05、06
嵌入	07_*
函数管理	08_*
可观测性 / 追踪	09、09b_manual_tracing、09c_traces
模型	10_models.{py,ts}
实时	仅 TS：11-real-time.ts
知识库	12_knowledge_base.{py,ts}
Web 工具	13_web_tools.{py,ts}

Agents（examples/agents/，编号 00..10）：首个 Agent → 输出 Schema → 工具 → 流式传输 → 钩子（日志记录 / 计时 / 流式传输）→ Agent 即工具 → 多 Agent → MCP（stdio）→ 对话。主题与文件的对应表请参阅 references/agents.md。

类型定义：python/src/opperai/types.py 和 typescript/src/types.ts。

不太明显的注意事项

• opper.call 使用的是旧版 /call 接口，该接口即将停用，SDK 也正在重构以移除它。 不要向任何人推荐它；请将现有的 opper.call 代码迁移到带有 response_format 的 compat 端点（映射见 opper-api 技能中的 references/migration.md）。
• 不强制要求使用 Schema 库。 两个 SDK 都接受普通 JSON Schema 字典，无需任何第三方 Schema 包。Pydantic（Python）和 Zod（TS）是为方便使用而内置的集成——大多数用户会选择它们，但它们并非必需。
• 如果在 TS SDK 中使用 Zod，则必须使用 v4。 npm install zod@4。不支持 [email protected] 双模式包。（Zod 是可选的对等依赖项。）
• Python 依赖 httpx（运行时并非零依赖）；TypeScript 运行时零依赖。
• opperai 是统一的软件包。 旧的独立软件包 opperai-agents（PyPI）和 @opperai/agents（npm）已弃用；Agent、tool、Conversation、Hooks 等均从顶层 opperai 重新导出。
• 早期版本的迁移说明见上游的 python/MIGRATION.md 和 typescript/MIGRATION.md。
• 有关 API 签名的问题，请获取实时 OpenAPI 规范：https://api.opper.ai/v3/openapi.yaml。SDK 的结构与该规范一致。

接下来查看

内容	查看
安装、快速入门、完整 README	opper-sdks repo — python/README.md、typescript/README.md
可运行示例（按编号递进）	仓库中的 python/examples/、typescript/examples/
类型定义	python/src/opperai/types.py、typescript/src/types.ts
在线 API 规范	https://api.opper.ai/v3/openapi.yaml
从较旧版本的 SDK 迁移	python/MIGRATION.md、typescript/MIGRATION.md
仓库级工作流（OpenAPI 同步、Beta 端点）	opper-sdks 仓库中的 CLAUDE.md
可用模型、网关概念、原始 HTTP、Realtime	opper-api 技能
可浏览的模型目录（用于面向用户的推荐）	opper.ai/models
Control Plane 规则（支出限额、数据保留、模型访问、检查、路由）	docs.opper.ai/control-plane/rules/overview
Agent 辅助设置、平台运维和模型测试	opper-mcp 技能
在终端中调用 Opper	opper-cli 技能