Opper Sdks

Sub-skill of opper — start there for discovery and setup guidance. Source: https://github.com/opper-ai/opper-skills/blob/main/opper-sdks/SKILL.md

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.

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): the recommended path is a compat chat endpoint with response_format, called through the provider SDK you already know — point the OpenAI SDK's base_url at https://api.opper.ai/v3/compat and pass your Pydantic / Zod model via chat.completions.parse(...). Seeds below; full shape in the opper-api skill.
• Streaming: stream: true on the same compat call — standard OpenAI SSE semantics.
• Multi-turn chat or message-thread style: the compat chat endpoints are message-native — carry the messages array forward.
• 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.
• Knowledge bases / RAG: opper.knowledge.* — create, query, add, etc.
• opper.call(...) / opper.stream(...) are legacy. They ride Opper's /call surface, which is being sunset — don't start new work on them, and don't use them in examples. The opperai SDK itself is being reworked to no longer use /call; a future release drops it. Existing code migrates to compat + response_format; the field-by-field mapping (name → X-Opper-Name header, output_schema → response_format, result.data → parsed message content) is in the opper-api skill's references/migration.md.

Pick a path

Install

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.

Canonical seed — Python

One-shot tasks go through the compat endpoint with the stock OpenAI SDK; X-Opper-Name keeps named-function tracing:

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)

For typed output, use client.chat.completions.parse(..., response_format=YourPydanticModel) and read resp.choices[0].message.parsed.

Canonical seed — 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);

For typed output, pass response_format: { type: "json_schema", json_schema: { name, schema } } (generate the schema from Zod v4 with z.toJSONSchema(...)) and JSON.parse the message content.

For the agent seeds (Agent, tool, agent.run(...)), see references/agents.md.

Picking a model

The SDK uses the project's default model when model: is omitted — set the default once via a Control Plane Route rule at platform.opper.ai so the same code works across environments without edits. Pin a specific model: "provider/name" only when you need to override.

• Browse models for the user: link them at opper.ai/models — the human catalog.
• Discover models in code: GET https://api.opper.ai/v3/models (no auth required). Never hardcode model lists — they change.

The numbered examples are the highest-bandwidth reference

Both python/examples/ and typescript/examples/ hold parallel numbered files. Read by topic. Caveat: many of the getting-started examples still demonstrate the legacy opper.call surface — treat them as reference for existing code, not as the pattern for new work (that's compat + response_format, above).

Getting started (examples/getting-started/):

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.

Non-obvious gotchas

• opper.call rides the legacy /call surface, which is being sunset — and the SDK is being reworked to drop it. Recommend it to no one; migrate existing opper.call code to a compat endpoint with response_format (mapping in the opper-api skill's references/migration.md).
• 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.

Where to look next