opper-sdks

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Opper SDKs

The Python and TypeScript SDKs for Opper live in a single monorepo: github.com/opper-ai/opper-sdks. Both publish as

opperai

(PyPI / npm). Agents are part of the SDK — there is no separate

opperai-agents

package.

The upstream READMEs (

python/README.md

typescript/README.md

) and the numbered example files are the source of truth. This skill points at them; it does not duplicate them.

Opper的Python和TypeScript SDK存放在同一个单体仓库中：github.com/opper-ai/opper-sdks。两者均以

opperai

的名称发布（分别在PyPI和npm上）。Agent是SDK的一部分——不存在单独的

opperai-agents

包。

上游的README文件（

python/README.md

、

typescript/README.md

）以及编号示例文件是权威参考来源。本技能仅引导用户查看这些资源，不重复其内容。

Pick your primitive

选择合适的基础组件

The unified

opperai

package exposes a few different shapes. Pick by what you're building:

One-shot structured task (input → typed output, including image / audio / video generation): opper.call(...)
is recommended. Pass
```
output_schema=
```
(Python) or
```
outputSchema:
```
(TS) — Pydantic / Zod / dataclasses / TypedDict / raw JSON Schema all work.
Streaming any of the above: opper.stream(...)
— same shape, async-iterable of typed chunks.
Multi-turn chat or message-thread style: Conversation
(re-exported from
```
opperai
```
) — keeps history across
```
opper.call(...)
```
invocations.
Tool-using agent, multi-step reasoning, multi-agent, MCP: the Agent SDK (
```
Agent
```
,
```
tool
```
,
```
Conversation
```
,
```
Hooks
```
,
```
mcp
```
) is recommended for any "model decides what to do next" flow. Use agent.run(...)
for a single shot or agent.stream(...)
for live progress.
Drop-in compatibility with OpenAI / Anthropic / Google SDKs: not exposed through the
```
opperai
```
SDK. Recommended: call the compat endpoints directly through the provider's own SDK (point its
```
baseURL
```
/
```
base_url
```
at
```
https://api.opper.ai/v3/compat
```
), or see the opper-api
skill for raw HTTP.
Knowledge bases / RAG: opper.knowledge.*
—
```
create
```
,
```
query
```
,
```
add
```
, etc.

统一的

opperai

包提供了多种不同的功能形态，可根据你的开发需求选择：

一次性结构化任务（输入→类型化输出，包括图像/音频/视频生成）：推荐使用**
```
opper.call(...)
```
**。传入
```
output_schema=
```
（Python）或
```
outputSchema:
```
（TypeScript）——Pydantic/Zod/数据类/TypedDict/原生JSON Schema均支持。
上述任意场景的streaming：opper.stream(...)
——与
```
opper.call(...)
```
形态一致，返回类型化分片的异步迭代器。
多轮对话或消息线程模式：Conversation
（从
```
opperai
```
重导出）——在多次
```
opper.call(...)
```
调用之间保留对话历史。
支持工具调用的Agent、多步骤推理、多Agent、MCP：对于任何“由模型决定下一步操作”的流程，推荐使用Agent SDK（
```
Agent
```
、
```
tool
```
、
```
Conversation
```
、
```
Hooks
```
、
```
mcp
```
）。单次调用使用**
```
agent.run(...)
```
，实时进度反馈使用
```
agent.stream(...)
```
**。
与OpenAI/Anthropic/Google SDK的即插即用兼容性：未通过
```
opperai
```
SDK暴露。推荐方案：直接通过供应商自身的SDK调用兼容端点（将其
```
baseURL
```
/
```
base_url
```
指向
```
https://api.opper.ai/v3/compat
```
），或查看**
```
opper-api
```
技能**了解原生HTTP调用方式。
知识库/RAG：opper.knowledge.*
——包含
```
create
```
、
```
query
```
、
```
add
```
等方法。

Pick a path

选择学习路径

You are…	Read
Writing Python (calls, streaming, schemas, knowledge, tracing)	references/python.md
Writing TypeScript / JavaScript	references/typescript.md
Building an agent in either language	references/agents.md
Calling Opper without an SDK (curl, fetch)	switch to the `opper-api` skill

你正在开发…	查看文档
Python（调用、streaming、Schema、知识库、tracing）	references/python.md
TypeScript/JavaScript	references/typescript.md
用任意语言构建Agent	references/agents.md
不使用SDK调用Opper（curl、fetch）	切换至 `opper-api` 技能

Install

安装

bash

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

Authentication: both SDKs read

OPPER_API_KEY

from the environment, or accept

api_key=

apiKey:

in the constructor.

bash

pip install opperai          # Python — 仅依赖一个运行时库：httpx
npm  install opperai         # TypeScript — 无运行时依赖；zod和@modelcontextprotocol/sdk为可选对等依赖

认证方式：两个SDK均从环境变量读取

OPPER_API_KEY

，或在构造函数中传入

api_key=

apiKey:

参数。

Canonical seed — Python

典型示例 — Python

python

from opperai import Opper

opper = Opper()  # uses OPPER_API_KEY

result = opper.call(
    "summarise",
    instructions="Summarise the article in two sentences.",
    input={"text": "..."},
)
print(result.data)

python

from opperai import Opper

opper = Opper()  # 使用OPPER_API_KEY

result = opper.call(
    "summarise",
    instructions="Summarise the article in two sentences.",
    input={"text": "..."},
)
print(result.data)

Canonical seed — TypeScript

典型示例 — TypeScript

import { Opper } from "opperai";

const opper = new Opper(); // uses OPPER_API_KEY

const result = await opper.call("summarise", {
  instructions: "Summarise the article in two sentences.",
  input: { text: "..." },
});
console.log(result.data);

import { Opper } from "opperai";

const opper = new Opper(); // 使用OPPER_API_KEY

const result = await opper.call("summarise", {
  instructions: "Summarise the article in two sentences.",
  input: { text: "..." },
});
console.log(result.data);

The numbered examples are the highest-bandwidth reference

编号示例是最高效的参考资源

Both

python/examples/

and

typescript/examples/

hold parallel numbered files. Read by topic.

Getting started (

examples/getting-started/

Topic	File pattern
First call	`00_your_first_call.{py,ts}`
Schemas — Pydantic / Zod / dataclass / TypedDict / raw JSON Schema	`01a_` and `01b_`
Streaming	`02_stream.{py,ts}`
Tools — call & stream	`03a_` , `03b_` (TS-only `03c-server-side-tools.ts` )
Images, audio, video	`04a/04b/04c` , `05` , `06`
Embeddings	`07_*`
Function management	`08_*`
Observability / tracing	`09` , `09b_manual_tracing` , `09c_traces`
Models	`10_models.{py,ts}`
Real-time	TS-only: `11-real-time.ts`
Knowledge base	`12_knowledge_base.{py,ts}`
Web tools	`13_web_tools.{py,ts}`

Agents (

examples/agents/

, numbered

00..10

): first agent → output schema → tools → streaming → hooks (logging / timing / streaming) → agent-as-tool → multi-agent → MCP (stdio) → conversation. See references/agents.md for the topic↔file table.

Type definitions:

python/src/opperai/types.py

and

typescript/src/types.ts

python/examples/

和

typescript/examples/

目录下均包含对应的编号示例文件，可按主题查看。

入门指南（

examples/getting-started/

）：

主题	文件命名模式
首次调用	`00_your_first_call.{py,ts}`
Schema — Pydantic/Zod/数据类/TypedDict/原生JSON Schema	`01a_` 和 `01b_`
Streaming	`02_stream.{py,ts}`
工具 — 调用与streaming	`03a_` 、 `03b_` （TypeScript专属： `03c-server-side-tools.ts` ）
图像、音频、视频	`04a/04b/04c` 、 `05` 、 `06`
Embeddings	`07_*`
函数管理	`08_*`
可观测性/tracing	`09` 、 `09b_manual_tracing` 、 `09c_traces`
模型	`10_models.{py,ts}`
实时功能	TypeScript专属： `11-real-time.ts`
知识库	`12_knowledge_base.{py,ts}`
Web工具	`13_web_tools.{py,ts}`

Agent相关（

examples/agents/

，编号

00..10

）：从第一个Agent→输出Schema→工具→streaming→Hooks（日志/计时/流式传输）→Agent作为工具→多Agent→MCP（标准输入输出）→对话。查看references/agents.md获取主题与文件的对应表。

类型定义：

python/src/opperai/types.py

和

typescript/src/types.ts

。

Non-obvious gotchas

易忽略的注意事项

No required schema library. Both SDKs accept plain JSON Schema dicts and don't need any third-party schema package. Pydantic (Python) and Zod (TS) are bundled integrations for convenience — most users will reach for them, but they are optional.
If you use Zod with the TS SDK, it must be v4.
```
npm install zod@4
```
. The
```
zod@3.25.x
```
dual-mode package is not supported. (Zod is an optional peer dependency.)
Python depends on
httpx
(not zero-dep at runtime); TypeScript is zero-dep at runtime.
opperai
is the unified package. Old separate
```
opperai-agents
```
(PyPI) and
```
@opperai/agents
```
(npm) are deprecated;
```
Agent
```
,
```
tool
```
,
```
Conversation
```
,
```
Hooks
```
, etc. are all re-exported from the top-level
```
opperai
```
.
Migration from earlier versions is documented at
```
python/MIGRATION.md
```
and
```
typescript/MIGRATION.md
```
upstream.
For API signature questions, fetch the live OpenAPI spec at
```
https://api.opper.ai/v3/openapi.yaml
```
. The SDK shape mirrors the spec.

无强制依赖的Schema库：两个SDK均接受原生JSON Schema字典，无需任何第三方Schema包。Pydantic（Python）和Zod（TypeScript）是为方便用户而集成的可选依赖——大多数用户会选择使用，但它们并非必需。
若在TypeScript SDK中使用Zod，必须是v4版本：执行
```
npm install zod@4
```
。不支持
```
zod@3.25.x
```
双模式包。（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的形态与该规范一致。

Where to look next

下一步参考

For	Look at
Install, quick start, full READMEs	opper-sdks repo — `python/README.md` , `typescript/README.md`
Working examples (numbered, progressive)	`python/examples/` , `typescript/examples/` in the repo
Type definitions	`python/src/opperai/types.py` , `typescript/src/types.ts`
Live API spec	`https://api.opper.ai/v3/openapi.yaml`
Migrating from older SDK versions	`python/MIGRATION.md` , `typescript/MIGRATION.md`
Repo-level workflows (OpenAPI sync, beta endpoints)	`CLAUDE.md` in the opper-sdks repo
Models available, gateway concepts, raw HTTP	the `opper-api` skill
Calling Opper from a terminal	the `opper-cli` skill

需求	查看资源
安装、快速入门、完整README	opper-sdks仓库 — `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调用	`opper-api` 技能
从终端调用Opper	`opper-cli` 技能